Improve AA docs

Better describe TBAA tree systems and the broad mechanisms behind a few different alias analysis passes and how they differ.

Author: CodaFi

Sources/LLVM/MDBuilder.swift

@@ -234,7 +234,12 @@ public struct TBAAStructField {
 }
 
 extension MDBuilder {
-  /// Build a metadata node for the root of a TBAA hierarchy with the given name.
+  /// Build a metadata node for the root of a TBAA hierarchy with the given
+  /// name.
+  ///
+  /// The root node of a TBAA hierarchy describes a boundary for a source
+  /// language's type system.  For the purposes of optimization, a TBAA analysis
+  /// pass must consider ancestors of two different root systems `mayalias`.
   ///
   /// - Parameters:
   ///   - name: The name of the TBAA root node.
@@ -306,13 +311,51 @@ extension MDBuilder {
   /// Builds a TBAA Type Descriptor.
   ///
   /// Type descriptors describe the type system of the higher level language
-  /// being compiled. Scalar type descriptors describe types that do not
-  /// contain other types. Each scalar type has a parent type, which must also
-  /// be a scalar type or the TBAA root. Via this parent relation, scalar types
-  /// within a TBAA root form a tree. Struct type descriptors denote types that
-  /// contain a sequence of other type descriptors, at known offsets. These
-  /// contained type descriptors can either be struct type descriptors
-  /// themselves or scalar type descriptors.
+  /// being compiled and come in two variants:
+  ///
+  /// Scalar Type Descriptors
+  /// =======================
+  ///
+  /// Scalar type descriptors describe types that do not contain other types,
+  /// such as fixed-width integral and floating-point types.  A scalar type
+  /// has a single parent, which is required to be another scalar type or
+  /// the TBAA root node.  For example, in C, `int32_t` would be described be
+  /// a scalar type node with a parent pointer to `unsigned char` which, in
+  /// turn, points to the root for C.
+  ///
+  /// ```
+  /// +----------+   +------+   +-----------+
+  /// |          |   |      |   |           |
+  /// | uint32_t +---> char +---> TBAA Root |
+  /// |          |   |      |   |           |
+  /// +----------+   +------+   +-----------+
+  /// ```
+  ///
+  /// Struct Type Descriptors
+  /// =======================
+  ///
+  /// Struct type descriptors describe types that contain a sequence of other
+  /// type descriptors, at known offsets, as fields. These field type
+  /// descriptors can either be struct type descriptors themselves or scalar
+  /// type descriptors.
+  ///
+  /// ```
+  ///               +----------+
+  ///               |          |
+  ///       +-------> uint32_t +----+
+  ///       |       |          |    |
+  ///       |       +----------+    |
+  /// +------------+            +---v--+   +-----------+
+  /// |            |            |      |   |           |
+  /// | SomeStruct |            | char +---> TBAA Root |
+  /// |            |            |      |   |           |
+  /// +------------+            +---^--+   +-----------+
+  ///       |          +-------+    |
+  ///       |          |       |    |
+  ///       +----------> float +----+
+  ///                  |       |
+  ///                  +-------+
+  /// ```
   ///
   /// - Parameters:
   ///   - parent: The parent type node of this type node or the TBAA root node

Sources/LLVM/PassManager.swift

@@ -134,12 +134,36 @@ public enum Pass {
   case earlyCSE
   ///  Removes `llvm.expect` intrinsics and creates "block_weights" metadata.
   case lowerExpectIntrinsic
-  /// Adds metadata to LLVM IR types and performs metadata-based TBAA.
+  /// Adds metadata to LLVM IR types and performs metadata-based
+  /// Type-Based Alias Analysis (TBAA).
+  ///
+  /// TBAA requires that two pointers to objects of different types must never
+  /// alias.  Because memory in LLVM is typeless, TBAA is performed using
+  /// special metadata nodes describing aliasing relationships between types
+  /// in the source language(s).
+  ///
+  /// To construct this metadata, see `MDBuilder`.
   case typeBasedAliasAnalysis
   /// Adds metadata to LLVM IR types and performs metadata-based scoped no-alias
   /// analysis.
   case scopedNoAliasAA
   /// LLVM's primary stateless and local alias analysis.
+  ///
+  /// Given a pointer value, walk the use-def chain to find out how that
+  /// pointer is used.  The traversal terminates at global variables and
+  /// aliases, stack allocations, and values of non-pointer types - referred
+  /// to as "underlying objects". Analysis may reach multiple underlying object
+  /// values because of branching control flow.  If the set of underlying
+  /// objects for one pointer has a non-empty intersection with another, those
+  /// two pointers are deemed `mayalias`.  Else, an empty intersection deems
+  /// those pointers `noalias`.
+  ///
+  /// Basic Alias Analysis should generally be scheduled ahead of other
+  /// AA passes.  This is because it is more conservative than other passes
+  /// about declaring two pointers `mustalias`, and does so fairly efficiently.
+  /// For example, loads through two members of a union with distinct types are
+  /// declared by TBAA to be `noalias`, where BasicAA considers them
+  /// `mustalias`.
   case basicAliasAnalysis
   /// Performs alias and mod/ref analysis for internal global values that
   /// do not have their address taken.