MDBuilder

public final class MDBuilder

An MDBuilder object provides a convenient way to build common metadata nodes.

  • The context used to intialize this metadata builder.

    Declaration

    Swift

    public let context: Context
  • Creates a metadata builder with the given context.

    Declaration

    Swift

    public init(in context: Context = .global)

    Parameters

    context

    The context in which to create metadata.

Floating Point Accuracy Metadata

  • Builds metadata describing the accuracy of a floating-point computation using the given accuracy value.

    Declaration

    Swift

    public func buildFloatingPointMathTag(_ accuracy: Float) -> MDNode?

    Parameters

    accuracy

    The accuracy value.

    Return Value

    A metadata node describing the accuracy of a floating-point computation.

Branch Prediction Metadata

  • Builds branch weight metadata for a set of branch targets of a branch, select, switch, or call instruction.

    Declaration

    Swift

    public func buildBranchWeights(_ weights: [Int]) -> MDNode

    Parameters

    weights

    The weights of the branches.

    Return Value

    A metadata node containing the given branch-weight information.

  • Builds branch metadata that expresses that the flow of control is unpredictable in a given branch or switch instruction.

    Declaration

    Swift

    public func buildUnpredictable() -> MDNode

    Return Value

    A metadata node representing unpredictable branch metadata.

Section Prefix Metadata

  • Builds section prefix metadata.

    LLVM allows an explicit section to be specified for functions. If the target supports it, it will emit functions to the section specified. Additionally, the function can be placed in a COMDAT.

    Declaration

    Swift

    public func buildFunctionSectionPrefix(_ section: String) -> MDNode

    Parameters

    section

    The section into which functions annotated with this metadata should be emitted.

    Return Value

    A metadata node representing the section prefix metadata.

Range Metadata

  • Builds range metadata.

    Range metadata may be attached only to load, call and invoke of integer types. It expresses the possible ranges the loaded value or the value returned by the called function at this call site is in. If the loaded or returned value is not in the specified range, the behavior is undefined.

    Declaration

    Swift

    public func buildRange(_ lo: APInt, _ hi: APInt) -> MDNode?

    Parameters

    lo

    The lower bound on the range.

    hi

    The upper bound on the range.

    Return Value

    A metadata node representing the newly created range metadata.

Callee Metadata

  • Build callees metadata.

    Callees metadata may be attached to indirect call sites. If callees metadata is attached to a call site, and any callee is not among the set of functions provided by the metadata, the behavior is undefined.

    Declaration

    Swift

    public func buildCallees(_ callees: [Function]) -> MDNode

    Parameters

    callees

    An array of callee function values.

    Return Value

    A metadata node representing the newly created callees metadata.

Callback Metadata

  • Build Callback metadata.

    Callback metadata may be attached to a function declaration, or definition. The metadata describes how the arguments of a call to a function are in turn passed to the callback function specified by the metadata. Thus, the callback metadata provides a partial description of a call site inside the function with regards to the arguments of a call to the function. The only semantic restriction on the function itself is that it is not allowed to inspect or modify arguments referenced in the callback metadata as pass-through to the callback function.

    Declaration

    Swift

    public func buildCallbackEncoding(
      _ callbackIndex: UInt, _ argumentIndices: [Int],
      passVariadicArguments: Bool = false
    ) -> MDNode

    Parameters

    callbackIndex

    The argument index of the callback.

    argumentIndices

    An array of argument indices in the caller that are passed to the callback function.

    passVariadicArguments

    If true, denotes that all variadic arguments of the function are passed to the callback.

    Return Value

    A metadata node representing the newly created callees metadata.

Function Entry Count Metadata

  • Build function entry count metadata.

    Function entry count metadata can be attached to function definitions to record the number of times the function is called. Used with block frequency information, it is also used to derive the basic block profile count.

    Declaration

    Swift

    public func buildFunctionEntryCount(
      _ count: UInt, imports: Set<UInt64> = [], synthetic: Bool = false
    ) -> MDNode

    Parameters

    count

    The number of times a function is called.

    imports

    The GUID of global values that should be imported along with this function when running PGO.

    synthetic

    Whether the entry count is synthetic. User-created metadata should not be synthetic outside of PGO passes.

    Return Value

    A metadata node representing the newly created entry count metadata.

TBAA Metadata

  • 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.

    Declaration

    Swift

    public func buildTBAARoot(_ name: String = "") -> MDNode

    Parameters

    name

    The name of the TBAA root node.

    Return Value

    A metadata node representing a TBAA hierarchy root.

  • Build a metadata node suitable for an alias.scope metadata attachment.

    When evaluating an aliasing query, if for some domain, the set of scopes with that domain in one instruction’s alias.scope list is a subset of (or equal to) the set of scopes for that domain in another instruction’s noalias list, then the two memory accesses are assumed not to alias.

    Because scopes in one domain don’t affect scopes in other domains, separate domains can be used to compose multiple independent noalias sets. This is used for example during inlining. As the noalias function parameters are turned into noalias scope metadata, a new domain is used every time the function is inlined.

    Declaration

    Swift

    public func buildAliasScopeDomain(_ name: String = "", _ domain: MDNode? = nil) -> MDNode

    Parameters

    name

    The name of the alias scope domain.

    domain

    The domain of the alias scope, if any.

    Return Value

    A metadata node representing a TBAA alias scope.

  • Builds a metadata node suitable for a tbaa.struct metadata attachment.

    tbaa.struct metadata can describe which memory subregions in a memcpy are padding and what the TBAA tags of the struct are.

    Note that the fields need not be contiguous. In the following example, there is a 4 byte gap between the two fields. This gap represents padding which does not carry useful data and need not be preserved.

    !4 = !{ i64 0, i64 4, !1, i64 8, i64 4, !2 }
    

    Declaration

    Swift

    public func buildTBAAStructNode(_ fields: [TBAAStructField]) -> MDNode

    Parameters

    fields

    The fields of the struct.

    Return Value

    A metadata node representing a TBAA struct descriptor.

  • Builds a TBAA Type Descriptor.

    Type descriptors describe the type system of the higher level language 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 +----+
                     |       |
                     +-------+
    

    Declaration

    Swift

    public func buildTBAATypeNode(
      _ id: IRMetadata, parent: MDNode, size: Size, fields: [TBAAStructField] = []
    ) -> MDNode

    Parameters

    parent

    The parent type node of this type node or the TBAA root node if it is a top-level entity.

    size

    The size of the type in bytes.

    id

    The metadata node whose identity uniquely identifies this node as well. These are often MDString values.

    fields

    The fields of the type, if any.

    Return Value

    A metadata node representing a TBAA type descriptor.

  • Builds a TBAA Access Tag.

    Access tags are metadata nodes attached to load and store instructions. Access tags use type descriptors to describe the location being accessed in terms of the type system of the higher level language. Access tags are tuples consisting of a base type, an access type and an offset. The base type is a scalar type descriptor or a struct type descriptor, the access type is a scalar type descriptor, and the offset is a constant integer.

    Tag Structure

    The access tag (BaseTy, AccessTy, Offset) can describe one of two things:

    • If BaseTy is a struct type, the tag describes a memory access (load or store) of a value of type AccessTy contained in the struct type BaseTy at offset Offset.
    • If BaseTy is a scalar type, Offset must be 0 and BaseTy and AccessTy must be the same; and the access tag describes a scalar access with scalar type AccessTy.

    Declaration

    Swift

    public func buildTBAAAccessTag(
      baseType: MDNode, accessType: MDNode,
      offset: Size, size: Size, immutable: Bool = false
    ) -> MDNode

    Parameters

    baseType

    The base type of the access. This is the structure or scalar type that corresponds to the type of the source value in a load instruction, or the type of the destination value in a store instruction.

    accessType

    The type of the accessed value. This is the type that corresponds to the type of the destination value in a load instruction, or the type of the source value in a store instruction.

    offset

    The ofset of the memory access into the base type. If the base type is scalar, this value must be 0.

    size

    The size of the access in bytes.

    immutable

    If true, accesses to this memory are never writes. This corresponds to the const memory qualifier in C and C++.

    Return Value

    A metadata node representing a TBAA access tag.

Irreducible Loop Metadata

  • Builds irreducible loop metadata.

    Declaration

    Swift

    public func buildIrreducibleLoopHeaderWeight(_ weight: UInt) -> MDNode

    Parameters

    weight

    The weight of a loop header.

    Return Value

    A metadata node representing the newly created irreducible loop metadata.