[llvm-branch-commits] [llvm] [docs] Migrate 20 LLVM docs to markdown (PR #201465)
Aiden Grossman via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Thu Jun 4 08:17:25 PDT 2026
================
@@ -33,315 +30,296 @@ This document contains information necessary to successfully implement this
interface, use it, and to test both sides. It also explains some of the finer
points about what exactly results mean.
-``AliasAnalysis`` Class Overview
-================================
+## `AliasAnalysis` Class Overview
-The `AliasAnalysis <https://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__
+The [AliasAnalysis](https://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html)
class defines the interface that the various alias analysis implementations
-should support. This class exports two important enums: ``AliasResult`` and
-``ModRefResult`` which represent the result of an alias query or a mod/ref
+should support. This class exports two important enums: `AliasResult` and
+`ModRefResult` which represent the result of an alias query or a mod/ref
query, respectively.
-The ``AliasAnalysis`` interface exposes information about memory, represented in
+The `AliasAnalysis` interface exposes information about memory, represented in
several different ways. In particular, memory objects are represented as a
starting address and size, and function calls are represented as the actual
-``call`` or ``invoke`` instructions that perform the call. The
-``AliasAnalysis`` interface also exposes some helper methods which allow you to
+`call` or `invoke` instructions that perform the call. The
+`AliasAnalysis` interface also exposes some helper methods which allow you to
get mod/ref information for arbitrary instructions.
-All ``AliasAnalysis`` interfaces require that in queries involving multiple
-values, values which are not :ref:`constants <constants>` are all
+All `AliasAnalysis` interfaces require that in queries involving multiple
+values, values which are not {ref}`constants <constants>` are all
defined within the same function.
-Representation of Pointers
---------------------------
+### Representation of Pointers
-Most importantly, the ``AliasAnalysis`` class provides several methods which are
+Most importantly, the `AliasAnalysis` class provides several methods which are
used to query whether or not two memory objects alias, whether function calls
can modify or read a memory object, etc. For all of these queries, memory
objects are represented as a pair of their starting address (a symbolic LLVM
-``Value*``) and a static size.
+`Value*`) and a static size.
Representing memory objects as a starting address and a size is critically
important for correct Alias Analyses. For example, consider this (silly, but
possible) C code:
-.. code-block:: c++
-
- int i;
- char C[2];
- char A[10];
- /* ... */
- for (i = 0; i != 10; ++i) {
- C[0] = A[i]; /* One byte store */
- C[1] = A[9-i]; /* One byte store */
- }
-
-In this case, the ``basic-aa`` pass will disambiguate the stores to ``C[0]`` and
-``C[1]`` because they are accesses to two distinct locations one byte apart, and
+```c++
+int i;
+char C[2];
+char A[10];
+/* ... */
+for (i = 0; i != 10; ++i) {
+ C[0] = A[i]; /* One byte store */
+ C[1] = A[9-i]; /* One byte store */
+}
+```
+
+In this case, the `basic-aa` pass will disambiguate the stores to `C[0]` and
+`C[1]` because they are accesses to two distinct locations one byte apart, and
the accesses are each one byte. In this case, the Loop Invariant Code Motion
(LICM) pass can use store motion to remove the stores from the loop. In
contrast, the following code:
-.. code-block:: c++
-
- int i;
- char C[2];
- char A[10];
- /* ... */
- for (i = 0; i != 10; ++i) {
- ((short*)C)[0] = A[i]; /* Two byte store! */
- C[1] = A[9-i]; /* One byte store */
- }
+```c++
+int i;
+char C[2];
+char A[10];
+/* ... */
+for (i = 0; i != 10; ++i) {
+ ((short*)C)[0] = A[i]; /* Two byte store! */
+ C[1] = A[9-i]; /* One byte store */
+}
+```
In this case, the two stores to C do alias each other, because the access to the
-``&C[0]`` element is a two byte access. If size information wasn't available in
+`&C[0]` element is a two byte access. If size information wasn't available in
the query, even the first case would have to conservatively assume that the
accesses alias.
-.. _alias:
+(alias)=
-The ``alias`` method
---------------------
+### The `alias` method
-The ``alias`` method is the primary interface used to determine whether or not
+The `alias` method is the primary interface used to determine whether or not
two memory objects alias each other. It takes two memory objects as input and
returns MustAlias, PartialAlias, MayAlias, or NoAlias as appropriate.
-Like all ``AliasAnalysis`` interfaces, the ``alias`` method requires that either
+Like all `AliasAnalysis` interfaces, the `alias` method requires that either
the two pointer values be defined within the same function, or at least one of
-the values is a :ref:`constant <constants>`.
+the values is a {ref}`constant <constants>`.
-.. _Must, May, or No:
+(Must, May, or No)=
-Must, May, and No Alias Responses
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Must, May, and No Alias Responses
-The ``NoAlias`` response may be used when there is never an immediate dependence
+The `NoAlias` response may be used when there is never an immediate dependence
between any memory reference *based* on one pointer and any memory reference
*based on* the other. The most obvious example is when the two pointers point to
non-overlapping memory ranges. Another is when the two pointers are only ever
used for reading memory. Another is when the memory is freed and reallocated
between accesses through one pointer and accesses through the other --- in this
case, there is a dependence, but it's mediated by the free and reallocation.
-An exception to this is with the :ref:`noalias <noalias>` keyword;
+An exception to this is with the {ref}`noalias <noalias>` keyword;
the "irrelevant" dependencies are ignored.
-The ``MayAlias`` response is used whenever the two pointers might refer to the
+The `MayAlias` response is used whenever the two pointers might refer to the
same object.
-The ``PartialAlias`` response is used when the two memory objects are known to
+The `PartialAlias` response is used when the two memory objects are known to
be overlapping in some way, regardless of whether they start at the same address
or not.
-The ``MustAlias`` response may only be returned if the two memory objects are
-guaranteed to always start at exactly the same location. A ``MustAlias``
+The `MustAlias` response may only be returned if the two memory objects are
+guaranteed to always start at exactly the same location. A `MustAlias`
response does not imply that the pointers compare equal.
-The ``getModRefInfo`` methods
------------------------------
+### The `getModRefInfo` methods
-The ``getModRefInfo`` methods return information about whether the execution of
+The `getModRefInfo` methods return information about whether the execution of
an instruction can read or modify a memory location. Mod/Ref information is
always conservative: if an instruction **might** read or write a location,
-``ModRef`` is returned.
-
-The ``AliasAnalysis`` class also provides a ``getModRefInfo`` method for testing
-dependencies between function calls. This method takes two call sites (``CS1``
-& ``CS2``), returns ``NoModRef`` if neither call writes to memory read or
-written by the other, ``Ref`` if ``CS1`` reads memory written by ``CS2``,
-``Mod`` if ``CS1`` writes to memory read or written by ``CS2``, or ``ModRef`` if
-``CS1`` might read or write memory written to by ``CS2``. Note that this
+`ModRef` is returned.
+
+The `AliasAnalysis` class also provides a `getModRefInfo` method for testing
+dependencies between function calls. This method takes two call sites (`CS1`
+& `CS2`), returns `NoModRef` if neither call writes to memory read or
+written by the other, `Ref` if `CS1` reads memory written by `CS2`,
+`Mod` if `CS1` writes to memory read or written by `CS2`, or `ModRef` if
+`CS1` might read or write memory written to by `CS2`. Note that this
relation is not commutative.
-Other useful ``AliasAnalysis`` methods
---------------------------------------
+### Other useful `AliasAnalysis` methods
Several other tidbits of information are often collected by various alias
analysis implementations and can be put to good use by various clients.
-The ``getModRefInfoMask`` method
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### The `getModRefInfoMask` method
-The ``getModRefInfoMask`` method returns a bound on Mod/Ref information for
+The `getModRefInfoMask` method returns a bound on Mod/Ref information for
the supplied pointer, based on knowledge about whether the pointer points to
-globally-constant memory (for which it returns ``NoModRef``) or
-locally-invariant memory (for which it returns ``Ref``). Globally-constant
+globally-constant memory (for which it returns `NoModRef`) or
+locally-invariant memory (for which it returns `Ref`). Globally-constant
memory includes functions, constant global variables, and the null pointer.
Locally-invariant memory is memory that we know is invariant for the lifetime
of its SSA value, but not necessarily for the life of the program: for example,
-the memory pointed to by ``readonly`` ``noalias`` parameters is known-invariant
+the memory pointed to by `readonly` `noalias` parameters is known-invariant
for the duration of the corresponding function call. Given Mod/Ref information
-``MRI`` for a memory location ``Loc``, ``MRI`` can be refined with a statement
-like ``MRI &= AA.getModRefInfoMask(Loc);``. Another useful idiom is
-``isModSet(AA.getModRefInfoMask(Loc))``; this checks to see if the given
+`MRI` for a memory location `Loc`, `MRI` can be refined with a statement
+like `MRI &= AA.getModRefInfoMask(Loc);`. Another useful idiom is
+`isModSet(AA.getModRefInfoMask(Loc))`; this checks to see if the given
location can be modified at all. For convenience, there is also a method
-``pointsToConstantMemory(Loc)``; this is synonymous with
-``isNoModRef(AA.getModRefInfoMask(Loc))``.
+`pointsToConstantMemory(Loc)`; this is synonymous with
+`isNoModRef(AA.getModRefInfoMask(Loc))`.
-.. _never access memory or only read memory:
+(never access memory or only read memory)=
-The ``doesNotAccessMemory`` and ``onlyReadsMemory`` methods
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### The `doesNotAccessMemory` and `onlyReadsMemory` methods
These methods are used to provide very simple mod/ref information for function
-calls. The ``doesNotAccessMemory`` method returns true for a function if the
+calls. The `doesNotAccessMemory` method returns true for a function if the
analysis can prove that the function never reads or writes to memory, or if the
function only reads from constant memory. Functions with this property are
side-effect free and only depend on their input arguments, allowing them to be
eliminated if they form common subexpressions or be hoisted out of loops. Many
-common functions behave this way (e.g., ``sin`` and ``cos``) but many others do
-not (e.g., ``acos``, which modifies the ``errno`` variable).
+common functions behave this way (e.g., `sin` and `cos`) but many others do
+not (e.g., `acos`, which modifies the `errno` variable).
-The ``onlyReadsMemory`` method returns true for a function if analysis can prove
+The `onlyReadsMemory` method returns true for a function if analysis can prove
that (at most) the function only reads from non-volatile memory. Functions with
this property are side-effect free, only depending on their input arguments and
the state of memory when they are called. This property allows calls to these
functions to be eliminated and moved around, as long as there is no store
instruction that changes the contents of memory. Note that all functions that
-satisfy the ``doesNotAccessMemory`` method also satisfy ``onlyReadsMemory``.
+satisfy the `doesNotAccessMemory` method also satisfy `onlyReadsMemory`.
-Writing a new ``AliasAnalysis`` Implementation
-==============================================
+## Writing a new `AliasAnalysis` Implementation
Writing a new alias analysis implementation for LLVM is quite straightforward.
There are already several implementations that you can use for examples, and the
following information should help fill in any details. For example, take a
-look at the `various alias analysis implementations`_ included with LLVM.
+look at the {ref}`various alias analysis implementations` included with LLVM.
-Different Pass styles
----------------------
+### Different Pass styles
-The first step is to determine what type of :doc:`LLVM pass <WritingAnLLVMPass>`
+The first step is to determine what type of {doc}`LLVM pass <WritingAnLLVMPass>`
you need to use for your Alias Analysis. As is the case with most other
analyses and transformations, the answer should be fairly obvious from what type
of problem you are trying to solve:
-#. If you require interprocedural analysis, it should be a ``Pass``.
-#. If you are a function-local analysis, subclass ``FunctionPass``.
-#. If you don't need to look at the program at all, subclass ``ImmutablePass``.
+1. If you require interprocedural analysis, it should be a `Pass`.
+1. If you are a function-local analysis, subclass `FunctionPass`.
+1. If you don't need to look at the program at all, subclass `ImmutablePass`.
In addition to the pass that you subclass, you should also inherit from the
-``AliasAnalysis`` interface, of course, and use the ``RegisterAnalysisGroup``
-template to register as an implementation of ``AliasAnalysis``.
+`AliasAnalysis` interface, of course, and use the `RegisterAnalysisGroup`
+template to register as an implementation of `AliasAnalysis`.
-Required initialization calls
------------------------------
+### Required initialization calls
-Your subclass of ``AliasAnalysis`` is required to invoke two methods on the
-``AliasAnalysis`` base class: ``getAnalysisUsage`` and
-``InitializeAliasAnalysis``. In particular, your implementation of
-``getAnalysisUsage`` should explicitly call into the
-``AliasAnalysis::getAnalysisUsage`` method in addition to declaring
+Your subclass of `AliasAnalysis` is required to invoke two methods on the
+`AliasAnalysis` base class: `getAnalysisUsage` and
+`InitializeAliasAnalysis`. In particular, your implementation of
+`getAnalysisUsage` should explicitly call into the
+`AliasAnalysis::getAnalysisUsage` method in addition to declaring
any pass dependencies your pass has. Thus you should have something like this:
-.. code-block:: c++
-
- void getAnalysisUsage(AnalysisUsage &AU) const {
- AliasAnalysis::getAnalysisUsage(AU);
- // declare your dependencies here.
- }
-
-Additionally, you must invoke the ``InitializeAliasAnalysis`` method from your
-analysis run method (``run`` for a ``Pass``, ``runOnFunction`` for a
-``FunctionPass``, or ``InitializePass`` for an ``ImmutablePass``). For example
-(as part of a ``Pass``):
-
-.. code-block:: c++
-
- bool run(Module &M) {
- InitializeAliasAnalysis(this);
- // Perform analysis here...
- return false;
- }
-
-Interfaces which may be specified
----------------------------------
-
-All of the `AliasAnalysis
-<https://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__ virtual methods
-default to providing :ref:`chaining <aliasanalysis-chaining>` to another alias
+```c++
+void getAnalysisUsage(AnalysisUsage &AU) const {
+ AliasAnalysis::getAnalysisUsage(AU);
+ // declare your dependencies here.
+}
+```
+
+Additionally, you must invoke the `InitializeAliasAnalysis` method from your
+analysis run method (`run` for a `Pass`, `runOnFunction` for a
+`FunctionPass`, or `InitializePass` for an `ImmutablePass`). For example
+(as part of a `Pass`):
+
+```c++
+bool run(Module &M) {
+ InitializeAliasAnalysis(this);
+ // Perform analysis here...
+ return false;
+}
+```
+
+### Interfaces which may be specified
+
+All of the [AliasAnalysis](https://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html) virtual methods
+default to providing {ref}`chaining <aliasanalysis-chaining>` to another alias
analysis implementation, which ends up returning conservatively correct
information (returning "May" Alias and "Mod/Ref" for alias and mod/ref queries
respectively). Depending on the capabilities of the analysis you are
implementing, you just override the interfaces you can improve.
-.. _aliasanalysis-chaining:
+(aliasanalysis-chaining)=
-``AliasAnalysis`` chaining behavior
------------------------------------
+### `AliasAnalysis` chaining behavior
Every alias analysis pass chains to another alias analysis implementation (for
-example, the user can specify "``-basic-aa -ds-aa -licm``" to get the maximum
+example, the user can specify "`-basic-aa -ds-aa -licm`" to get the maximum
----------------
boomanaiden154 wrote:
Irrelevant to this PR, but this and lots of other pieces of this document are kind of out of date.
https://github.com/llvm/llvm-project/pull/201465
More information about the llvm-branch-commits
mailing list