Merge pull request #203 from CodaFi/doctor-my-eyes

[NFC] Improve Doc Comments For Major Components

Author: CodaFi

Sources/LLVM/Alias.swift

@@ -4,6 +4,29 @@ import cllvm
 
 /// An `Alias` represents a global alias in an LLVM module - a new symbol and
 /// corresponding metadata for an existing global value.
+///
+/// An `Alias`, unlike a function or global variable declaration, does not
+/// create any new data in the resulting object file.  It is merely a new name
+/// for an existing symbol or constant.  The aliased value (the aliasee) must
+/// be either another global value like a function, global variable, or even
+/// another alias, or it must be a constant expression.
+///
+/// Linkers make no guarantees that aliases will be preserved in the final
+/// object file.  Aliases where the address is known to be relevant should be
+/// marked with the appropriate `UnnamedAddressKind` value.  If this value is
+/// not `none`, the alias is guaranteed to have the same address as the aliasee.
+/// Else, the alias is guaranteed to point to the same content as the aliasee,
+/// but may reside at a different address.
+///
+/// If the aliasee is a constant value, LLVM places additional restrictions on
+/// its content in order to maintain compatibility with the expected behavior of
+/// most linkers:
+///
+/// - The constant expression may not involve aliases with weak linkage.  Such
+///   weak aliases cannot be guaranteed to be stable in the final object file.
+/// - The constant expression may not involve global values requiring a
+///   relocation such as a global function or global variable declared but not
+///   defined within its module.
 public struct Alias: IRGlobal {
   internal let llvm: LLVMValueRef
 
@@ -12,7 +35,9 @@ public struct Alias: IRGlobal {
     return llvm
   }
 
-  /// Access the target value of this alias.
+  /// The target value of this alias.
+  ///
+  /// The aliasee is required to be another global value or constant
   public var aliasee: IRValue {
     get { return LLVMAliasGetAliasee(llvm) }
     set { LLVMAliasSetAliasee(llvm, newValue.asLLVM()) }

Sources/LLVM/BasicBlock.swift

@@ -5,16 +5,72 @@ import cllvm
 /// A `BasicBlock` represents a basic block in an LLVM IR program.  A basic
 /// block contains a sequence of instructions, a pointer to its parent block and
 /// its follower block, and an optional label that gives the basic block an
-/// entry in the symbol table.
+/// entry in the symbol table.  Because of this label, the type of every basic
+/// block is `LabelType`.
 ///
 /// A basic block can be thought of as a sequence of instructions, and indeed
-/// its member instructions may be iterated over with a `for-in` loop.
+/// its member instructions may be iterated over with a `for-in` loop.  A well-
+/// formed basic block has as its last instruction a "terminator" that produces
+/// a transfer of control flow and possibly yields a value.  All other
+/// instructions in the middle of the basic block may not be "terminator"
+/// instructions.  Basic blocks are not required to be well-formed until
+/// code generation is complete.
 ///
-/// The first basic block in a function is special in two ways: it is
-/// immediately executed on entrance to the function, and it is not allowed to
-/// have predecessor basic blocks (i.e. there can not be any branches to the
-/// entry block of a function). Because the block can have no predecessors, it
-/// also cannot have any PHI nodes.
+/// Creating a Basic Block
+/// ======================
+///
+/// By default, the initializer for a basic block merely creates the block but
+/// does not associate it with a function.
+///
+///     let module = Module(name: "Example")
+///     let fun = builder.addFunction("example",
+///                                   type: FunctionType(argTypes: [],
+///                                                      returnType: VoidType()))
+///
+///     // This basic block is "floating" outside of a function.
+///     let floatingBB = BasicBlock(name: "floating")
+///     // Until we associate it with a function by calling `Function.append(_:)`.
+///     fun.append(floatingBB)
+///
+/// A basic block may be created and automatically inserted at the end of a
+/// function by calling `Function.appendBasicBlock(named:in:)`.
+///
+///     let module = Module(name: "Example")
+///     let fun = builder.addFunction("example",
+///                                   type: FunctionType(argTypes: [],
+///                                                      returnType: VoidType()))
+///
+///     // This basic block is "attached" to the example function.
+///     let attachedBB = fun.appendBasicBlock(named: "attached")
+///
+/// The Address of a Basic Block
+/// ============================
+///
+/// Basic blocks (except the entry block) may have their labels appear in the
+/// symbol table.  Naturally, these labels are associated with address values
+/// in the final object file.  The value of that address may be accessed for the
+/// purpose of an indirect call or a direct comparisson by calling
+/// `Function.address(of:)` and providing one of the function's child blocks as
+/// an argument.  Providing any other basic block outside of the function as an
+/// argument value is undefined.
+///
+/// The Entry Block
+/// ===============
+///
+/// The first basic block (the entry block) in a `Function` is special:
+///
+/// - The entry block is immediately executed when the flow of control enters
+///   its parent function.
+/// - The entry block is not allowed to have predecessor basic blocks
+///   (i.e. there cannot be any branches to the entry block of a function).
+/// - The address of the entry block is not a well-defined value.
+/// - The entry block cannot have PHI nodes.  This is enforced structurally,
+///   as the entry block can have no predecessor blocks to serve as operands
+///   to the PHI node.
+/// - Static `alloca` instructions situated in the entry block are treated
+///   specially by most LLVM backends.  For example, FastISel keeps track of
+///   static `alloca` values in the entry block to more efficiently reference
+///   them from the base pointer of the stack frame.
 public struct BasicBlock: IRValue {
   internal let llvm: LLVMBasicBlockRef
 

Sources/LLVM/Context.swift

@@ -0,0 +1,62 @@
+#if SWIFT_PACKAGE
+import cllvm
+#endif
+
+/// A `Context` is an LLVM compilation session environment.
+///
+/// A `Context` is a container for the global state of an execution of the
+/// LLVM environment and tooling.  It contains independent copies of global and
+/// module-level entities like types, metadata attachments, and constants.
+///
+/// An LLVM context is needed for interacting with LLVM in a concurrent
+/// environment. Because a context maintains state independent of any other
+/// context, it is recommended that each thread of execution be assigned a unique
+/// context.  LLVM's core infrastructure and API provides no locking guarantees
+/// and no atomicity guarantees.
+public class Context {
+  internal let llvm: LLVMContextRef
+  private let ownsContext: Bool
+
+  /// Retrieves the global context instance.
+  ///
+  /// The global context is an particularly convenient instance managed by LLVM
+  /// itself.  It is the default context provided for any operations that
+  /// require it.
+  ///
+  /// - WARNING: Failure to specify the correct context in concurrent
+  ///   environments can lead to data corruption.  In general, it is always
+  ///   recommended that each thread of execution attempting to access the LLVM
+  ///   API have its own `Context` instance, rather than rely on this global
+  ///   context.
+  public static let global = Context(llvm: LLVMGetGlobalContext()!)
+
+  /// Creates a new `Context` object.
+  public init() {
+    llvm = LLVMContextCreate()
+    ownsContext = true
+  }
+
+  /// Creates a `Context` object from an `LLVMContextRef` object.
+  public init(llvm: LLVMContextRef, ownsContext: Bool = false) {
+    self.llvm = llvm
+    self.ownsContext = ownsContext
+  }
+
+  /// Returns whether the given context is set to discard all value names.
+  ///
+  /// If true, only the names of GlobalValue objects will be available in
+  /// the IR.  This can be used to save memory and processing time, especially
+  /// in release environments.
+  public var discardValueNames: Bool {
+    get { return LLVMContextShouldDiscardValueNames(self.llvm) != 0 }
+    set { LLVMContextSetDiscardValueNames(self.llvm, newValue.llvm) }
+  }
+
+  /// Deinitialize this value and dispose of its resources.
+  deinit {
+    guard self.ownsContext else {
+      return
+    }
+    LLVMContextDispose(self.llvm)
+  }
+}

Sources/LLVM/Function.swift

@@ -1,10 +1,91 @@
 #if SWIFT_PACKAGE
 import cllvm
+import llvmshims
 #endif
 
 /// A `Function` represents a named function body in LLVM IR source.  Functions
 /// in LLVM IR encapsulate a list of parameters and a sequence of basic blocks
 /// and provide a way to append to that sequence to build out its body.
+///
+/// A LLVM function definition contains a list of basic blocks, starting with
+/// a privileged first block called the "entry block". After the entry blocks'
+/// terminating instruction come zero or more other basic blocks.  The path the
+/// flow of control can potentially take, from each block to its terminator
+/// and on to other blocks, forms the "Control Flow Graph" (CFG) for the
+/// function.  The nodes of the CFG are the basic blocks, and the edges are
+/// directed from the terminator instruction of one block to any number of
+/// potential target blocks.
+///
+/// Additional basic blocks may be created and appended to the function at
+/// any time.
+///
+///     let module = Module(name: "Example")
+///     let builder = IRBuilder(module: module)
+///     let fun = builder.addFunction("example",
+///                                   type: FunctionType(argTypes: [],
+///                                                      returnType: VoidType()))
+///     // Create and append the entry block
+///     let entryBB = fun.appendBasicBlock(named: "entry")
+///     // Create and append a standalone basic block
+///     let freestanding = BasicBlock(name: "freestanding")
+///     fun.append(freestanding)
+///
+/// An LLVM function always has the type `FunctionType`.  This type is used to
+/// determine the number and kind of parameters to the function as well as its
+/// return value, if any.  The parameter values, which would normally enter
+/// the entry block, are instead attached to the function and are accessible
+/// via the `parameters` property.
+///
+/// Calling Convention
+/// ==================
+///
+/// By default, all functions in LLVM are invoked with the C calling convention
+/// but the exact calling convention of both a function declaration and a
+/// `call` instruction are fully configurable.
+///
+///     let module = Module(name: "Example")
+///     let builder = IRBuilder(module: module)
+///     let fun = builder.addFunction("example",
+///                                   type: FunctionType(argTypes: [],
+///                                                      returnType: VoidType()))
+///     // Switch to swiftcc
+///     fun.callingConvention = .swift
+///
+/// The calling convention of a function and a corresponding call instruction
+/// must match or the result is undefined.
+///
+/// Sections
+/// ========
+///
+/// A function may optionally state the section in the object file it
+/// should reside in through the use of a metadata attachment.  This can be
+/// useful to satisfy target-specific data layout constraints, or to provide
+/// some hints to optimizers and linkers.  LLVMSwift provides a convenience
+/// object called an `MDBuilder` to assist in the creation of this metadata.
+///
+///     let mdBuilder = MDBuilder()
+///     // __attribute__((hot))
+///     let hotAttr = mdBuilder.buildFunctionSectionPrefix(".hot")
+///
+///     let module = Module(name: "Example")
+///     let builder = IRBuilder(module: module)
+///     let fun = builder.addFunction("example",
+///                                   type: FunctionType(argTypes: [],
+///                                                      returnType: VoidType()))
+///     // Attach the metadata
+///     fun.addMetadata(hotAttr, kind: .sectionPrefix)
+///
+/// For targets that support it, a function may also specify a COMDAT section.
+///
+///     fun.comdat = module.comdat(named: "example")
+///
+/// Debug Information
+/// =================
+///
+/// A function may also carry debug information through special subprogram
+/// nodes.  These nodes are intended to capture the structure of the function
+/// as it appears in the source so that it is available for inspection by a
+/// debugger.  See `DIBuilderr.buildFunction` for more information.
 public class Function: IRGlobal {
   internal let llvm: LLVMValueRef
   internal init(llvm: LLVMValueRef) {
@@ -26,17 +107,6 @@ public class Function: IRGlobal {
   }
 
   /// Retrieves the entry block of this function.
-  ///
-  /// The first basic block in a function is special in two ways: it is
-  /// immediately executed on entrance to the function, and it is not allowed to
-  /// have predecessor basic blocks (i.e. there can not be any branches to the
-  /// entry block of a function). Because the block can have no predecessors, it
-  /// also cannot have any PHI nodes.
-  ///
-  /// The entry block is also special in that any static allocas emitted into it
-  /// influence the layout of the stack frame of the function at code generation
-  /// time.  It is therefore often more efficient to emit static allocas in the
-  /// entry block than anywhere else in the function.
   public var entryBlock: BasicBlock? {
     guard let blockRef = LLVMGetEntryBasicBlock(llvm) else { return nil }
     return BasicBlock(llvm: blockRef)
@@ -78,7 +148,7 @@ public class Function: IRGlobal {
 
   /// Computes the address of the specified basic block in this function.
   ///
-  /// Taking the address of the entry block is illegal.
+  /// - WARNING: Taking the address of the entry block is illegal.
   ///
   /// This value only has defined behavior when used as an operand to the 
   /// `indirectbr` instruction, or for comparisons against null. Pointer 
@@ -170,6 +240,13 @@ public class Function: IRGlobal {
     return BasicBlock(llvm: block)
   }
 
+  /// Appends the named basic block to the body of this function.
+  ///
+  /// - parameter basicBlock: The block to append.
+  public func append(_ basicBlock: BasicBlock) {
+    LLVMAppendExistingBasicBlock(llvm, basicBlock.asLLVM())
+  }
+
   /// Deletes the function from its containing module.
   /// - note: This does not remove calls to this function from the
   ///         module. Ensure you have removed all instructions that reference