[Docs] Add documentation for ongoing major changes

[nikic]

Summary

This documents major changes to IR semantics or project infrastructure which are happening over long time frames. It provides a brief overview on current transition state and links to some place where more information can be found.

[nikic]

Respect 80 char width.

[xbolva00]

Thanks, great!

[xbolva00]

llvm/docs/OngoingMajorChanges.rst

23

Clang 15 will change IR codegen as well?

[xbolva00]

Not major, I would also mention switch to llvm.abs and llvm min / max intrinsics. Finished in trunk, right?

[xbolva00]

Also it would be interesting to have here some status/future plans/ideas to explore for new passes like CE by @fhahn, SLP with memory versioning, LoopFlatten, FuncSpecialization, DFA pass, etc..

@SjoerdMeijer
@aeubanks
@alexey.zhikhar

[alexey.zhikhar]

In D122122#3397403, @xbolva00 wrote:

Also it would be interesting to have here some status/future plans/ideas to explore for new passes like CE by @fhahn, SLP with memory versioning, LoopFlatten, FuncSpecialization, DFA pass, etc..

@SjoerdMeijer
@aeubanks
@alexey.zhikhar

In terms of the DFA pass, we're currently working on providing a feature to the Rust community. It's not really Rust-specific, it just has been reported by Rust folks. The idea is to relax the legality condition somewhat to allow switch statements, where the initial value of the switch condition isn't constant (e.g., it comes from a formal argument of the function) https://github.com/rust-lang/rust/issues/80630

There's also ongoing testing effort to enable the pass by default.

Although, I wouldn't say that any of these two changes are "major"; they won't affect everyone, like opaque pointers or new PM will, they are incremental improvements to an isolated transformation pass.

[fhahn]

In D122122#3397453, @alexey.zhikhar wrote:

In D122122#3397403, @xbolva00 wrote:

Also it would be interesting to have here some status/future plans/ideas to explore for new passes like CE by @fhahn, SLP with memory versioning, LoopFlatten, FuncSpecialization, DFA pass, etc..

@SjoerdMeijer
@aeubanks
@alexey.zhikhar

In terms of the DFA pass, we're currently working on providing a feature to the Rust community. It's not really Rust-specific, it just has been reported by Rust folks. The idea is to relax the legality condition somewhat to allow switch statements, where the initial value of the switch condition isn't constant (e.g., it comes from a formal argument of the function) https://github.com/rust-lang/rust/issues/80630

There's also ongoing testing effort to enable the pass by default.

Although, I wouldn't say that any of these two changes are "major"; they won't affect everyone, like opaque pointers or new PM will, they are incremental improvements to an isolated transformation pass.

IMO we should keep the document focused on major changes to key infrastructure that have a wide impact across LLVM and/or impact downstream users and/or frontends. If we were to include (big) changes to existing passes or new passes, then this document will likely become too big to be useful and too big to reasonably keep it up-to-date.

llvm/docs/OngoingMajorChanges.rst

+=====================
+Ongoing Major Changes
+=====================
+
+The LLVM intermediate representation, as well as the LLVM project
+infrastructure, are continuously evolving. Some changes are complex and
+happen over the span of many years.
+
+This page documents ongoing major changes and their current status.
+
+Opaque Pointers
+===============
+
+LLVM is moving away from typed pointers (``i8*``) towards opaque pointers (``ptr``), which do not have a pointer element type. New code should avoid inspecting pointer element types (do not call ``getPointerElementType()``) and instead inspect semantically relevant types, such as load or store types.
+
+Documentation is available at :doc:`OpaquePointers`.
+
+Transition status: Support for opaque pointers in LLVM and Clang is close to complete. LLVM 15 will enable opaque pointers by default, but retain support for typed pointers. Typed pointer support will be removed after the LLVM 15 release branch.
+
+New Pass Manager
+================
+
+LLVM is moving towards a new pass manager, which permits more efficient pass and analysis scheduling.
+
+Documentation is available at :doc:`NewPassManager`.
+
+Transition status: The new pass manager is enabled by default since LLVM 13. Support for the legacy pass manager in the middle-end optimization pipeline is planned to be removed in LLVM 15. The backend optimization pipeline continues using the legacy pass manager for the time being.
+
+GlobalISel
+==========
+
+LLVM is moving towards a new instruction selector, which replaces both SelectionDAG and FastISel. It works on the whole function rather than a single basic block, and operates directly on MIR.
+
+Documentation is available at :doc:`GlobalISel/index`, which has multiple sub-pages.
+
+Transition status: Some backends like AArch64 use GlobalISel for code generation at ``O0`` (replacing FastISel). However, there has been no effort towards migrating all backends, and there are currently no specific plans to remove SelectionDAG or FastISel.
+
+Poison Values
+=============
+
+LLVM is moving from undef values towards poison values. Poison values permit more optimizations and have much simpler semantics. Code and tests should prefer using poison wherever possible.
+
+Documentation is available at :ref:`poisonvalues`.
+
+Transition status: Large parts of LLVM have already moved towards using poison values, but there are still some operations that are specified to return undef on "failure". The most important are loads from uninitialized memory, which are tracked at `issue #52930 <https://github.com/llvm/llvm-project/issues/52930>`_.
+
+Branch on Undef/Poison
+======================
+
+The LLVM language reference specifies that branching on undef or poison is immediate undefined behavior. However, there are currently some optimizations that can introduce new branches on poison/undef. For that reason, we currently do not exploit this undefined behavior in most optimizations.
+
+Transition status: There are still a number of optimizations introducing branch on poison, with SimpleLoopUnswitch being the most important one.

llvm/docs/UserGuides.rst

.. toctree::
    HowToUpdateDebugInfo
    LinkTimeOptimization
    LoopTerminology
    MarkdownQuickstartTemplate
    MemorySSA
    MergeFunctions
    MCJITDesignAndImplementation
    ORCv2
+   OngoingMajorChanges
    OpaquePointers
    JITLink
    NewPassManager
    NVPTXUsage
    Phabricator
    Passes
    ReportingGuide
    Remarks