SIL.rst: Describe the rest of the instructions

Also give some initial description of how functions and basic blocks work.

Swift SVN r3174

Author: jckarter

docs/SIL.rst

@@ -6,10 +6,21 @@ Abstract
 
 TODO: enable high-level optimization, interoperability, persistence, embedded interpreter, second coming, etc.
 
-General features
-----------------
-
-TODO: SSA, functional representation, all implicit Swift behavior is explicit in SIL, etc.
+Structure
+---------
+
+SIL is an SSA-form IR similar to LLVM assembly language. Values represent virtual registers and are
+immutable once instantiated. Mutation is represented by loading and storing to allocated memory as
+in LLVM. However, unlike LLVM, SIL represents branches using functional representation; rather than
+use phi nodes to reconcile values in branches, basic blocks resemble functions that implicitly close
+over their dominating blocks, and branch instructions look like function calls. Every SIL instruction
+also carries a reference back into the originating Swift AST for diagnostic purposes. The first
+basic block of a function takes the function's arguments as its own.
+
+In Swift, memory management is almost always implicit, but in SIL, it is always explicit. Allocation,
+deallocation, and reference counting have explicit instructions in SIL, and instructions such as tuple
+construction and function calls in SIL never implicitly retain or release objects even if the
+analogous high-level operations in Swift do.
 
 Types
 -----
@@ -32,26 +43,121 @@ SIL classifies types into two additional subgroups based on ABI stability:
   contains an address-only type may be referred to by an address, but those addresses cannot be
   directly loaded or stored.
 
-SIL adds some additional types of its own:
+SIL adds some additional types of its own, which are not first-class Swift types but are needed
+to :
 
 * The *address of T* ``Address<T>``, a pointer to memory containing a value of any reference or
   value type ``T``.  This can be an internal pointer into a data structure. Addresses of loadable
-  types can be loaded and stored to access values of those types. Addresses cannot be retained or
-  released.
+  types can be loaded and stored to access values of those types. Addresses of address-only types
+  can only be used with the ``copy``, ``destroy``, and ``dealloc`` instructions, or as arguments to
+  functions. Addresses cannot be retained or released.
 * The *object pointer* ``ObjectPointer`` is a generic pointer to a retainable block of memory, or
   *box*. An object pointer behaves like a reference type, but its contents are not accessible; it
   can only be retained, released, or passed around. Operations that allocate retainable memory
   generally return both an object pointer for the box and an address pointing to the object or
   objects inside the box.
+* Unlike Swift, unbound generic function types such as ``<T> (T) -> T`` can be expressed in SIL.
+  Accessing a generic function with ``constant_ref`` will give a value of that type. The generic
+  variables can be bound with a ``specialize`` instruction to give a callable function value.
+
+Functions
+---------
+::
+
+  func function_name [<T,U,V>] (T1, T2, ...) -> R {
+  entry(%a1:T1, %a2:T2, ...):
+    insn1
+    insn2
+    return
+  }
+
+A SIL function definition gives the function's name, its generic parameters (if any), and the types
+of its inputs and outputs. Implicit parameters for closures and curried functions in Swift are
+translated into explicit arguments.
+
+Basic blocks
+------------
+
+The body of a function consists of one or more basic blocks. Each basic block is introduced with a
+label and zero or more arguments and ends with a branch instruction.
 
 Instructions
 ------------
 
+TODO: formalize SIL notation
+
+Literal values
+~~~~~~~~~~~~~~
+
+constant_ref
+````````````
+::
+
+  %1 = constant_ref T identifier
+
+Loads a reference to the global object of type ``T`` represented by the declaration ``identifier``,
+such as a function, method, constructor, or property declaration. If the definition is generic, the
+result will be of a generic function type; the generic variables of such a result will need to be
+bound with a ``specialize`` instruction before the object can be ``apply``-ed.
+
+zerovalue
+`````````
+::
+
+  %1 = zerovalue T
+
+Creates a "zero" value of type ``T``. This value represents the uninitialized state of a value. This
+may not be a semantically valid value of type ``T``, but will at least give predictable results.
+
+integer_literal
+```````````````
+::
+
+  %1:T = integer_literal T 123
+
+Creates an integer literal value. The result will be of type ``T``, which must be a builtin
+integer type.
+
+float_literal
+`````````````
+::
+
+  %1:T = float_literal T 1.23
+
+Creates a floating-point literal value. The result will be of type ``T``, which must be a builtin
+floating-point type.
+
+char_literal
+`````````````````
+::
+
+  %1:T = char_literal T 'x'
+
+Creates a Unicode code point literal value. The result will be of type ``T``, which must be of a
+builtin integer type.
+
+TODO: same as integer_literal?
+
+string_literal
+``````````````
+::
+
+  %1:RawPointer = string_literal {ascii|utf8} "asdf"
+
+Retrieves a pointer to a string literal in the string table. The result will be of the builtin
+``RawPointer`` type.
+
+metatype
+````````
+::
+
+  %1:T.metatype = metatype T
+
+Retrieves the metatype object for type ``T``.
+
 Memory Management
 ~~~~~~~~~~~~~~~~~
 
-TODO: formalize SIL source notation
-
 alloc_var
 `````````
 ::
@@ -182,11 +288,6 @@ except that ``copy`` must be used if ``T`` is an address-only type. The operands
 be given the ``take`` and ``initialize`` attributes to indicate respectively whether the source may be
 destroyed and whether the destination must be initialized.
 
-Literal values
-~~~~~~~~~~~~~~
-
-TODO
-
 Data manipulation
 ~~~~~~~~~~~~~~~~~
 
@@ -215,15 +316,18 @@ index_address
 
 Returns the address of the ``%1``-th element relative to ``%0``.
 
-TODO: could it also index into tuples and structs like GEP?
+TODO: could it also index into tuples and structs and into multilevel structures like GEP?
 
 convert
 ```````
 ::
 
   %1:U = convert %0:T -> U
 
-Performs an implicit conversion from ``T`` to ``U``.
+Performs an implicit conversion from ``T`` to ``U``. This instruction is limited to conversions that
+will not affect how the value will codegen.
+
+TODO: what does that mean in practical terms?
 
 Functions
 ~~~~~~~~~
@@ -244,7 +348,8 @@ specialize
 
   %1:F1 = specialize %0:F0 -> F1
 
-Specializes a generic function of function type ``F0`` 
+Specializes a generic function of generic function type ``F0`` to generic or concrete function
+type ``F1``, binding some or all of its generic type variables.
 
 apply
 `````
@@ -255,15 +360,57 @@ apply
 Transfers control to function ``%0``, passing in the given arguments. The ``apply`` instruction does no retaining or
 releasing of its arguments by itself; the calling convention's retain/release policy must be handled
 by separate explicit ``retain`` and ``release`` instructions. The return value will likewise not be
-implicitly retained or released.
+implicitly retained or released. ``%0`` must be an object of a concrete function type; generic
+functions must have all of their generic parameters bound with ``specialize`` instructions before
+they can be applied.
 
-TODO: should have normal/unwind branch targets like ``invoke``
+TODO: should have normal/unwind branch targets like LLVM ``invoke``
 
 Branching
 ~~~~~~~~~
 
-TODO
+Branching instructions terminate a basic block.
+
+unreachable
+```````````
+::
+
+  unreachable
+
+Instruction indicates that control flow must not reach the end of the current
+basic block.
+
+return
+``````
+::
+
+  return %0:T
+
+Exits the current function and returns control to the calling function. The result of the ``apply``
+instruction that invoked the current function will be the operand of this ``return`` instruction.
+``return`` does not retain or release its operand or any other values.
+
+branch
+``````
+::
+
+  branch label (%1:T1, %2:T2, ...)
+
+Unconditionally transfers control from the current basic block to the block
+labeled ``label``, passing the given values as arguments to ``label``.
+
+cond_branch
+```````````
+::
+
+  cond_branch %0:Int1, true_label (%T1:T1, %T2:T2, ...),
+                       false_label (%F1:F1, %F2:F2, ...)
+
+Conditionally branches to ``true_label`` if ``%0`` is equal to one or to ``false_label`` if ``%0``
+is equal to zero, passing the corresponding set of values as arguments to the chosen block. ``%0``
+must be of the builtin ``Int1`` type.
 
+TODO: throw
 
 Examples
 --------