[llvm] r245138 - MIRLangRef: Describe the syntax that is used to represent machine basic blocks.

[Alex Lorenz via llvm-commits]

Author: arphaman
Date: Fri Aug 14 20:06:06 2015
New Revision: 245138

URL: http://llvm.org/viewvc/llvm-project?rev=245138&view=rev
Log:
MIRLangRef: Describe the syntax that is used to represent machine basic blocks.

Modified:
    llvm/trunk/docs/MIRLangRef.rst

Modified: llvm/trunk/docs/MIRLangRef.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/MIRLangRef.rst?rev=245138&r1=245137&r2=245138&view=diff
==============================================================================
--- llvm/trunk/docs/MIRLangRef.rst (original)
+++ llvm/trunk/docs/MIRLangRef.rst Fri Aug 14 20:06:06 2015
@@ -90,6 +90,117 @@ name of a function that this machine fun
 The attribute ``body`` is a `YAML block literal string`_. Its value represents
 the function's machine basic blocks and their machine instructions.
 
+Machine Instructions Format Reference
+=====================================
+
+The machine basic blocks and their instructions are represented using a custom,
+human readable serialization language. This language is used in the
+`YAML block literal string`_ that corresponds to the machine function's body.
+
+A source string that uses this language contains a list of machine basic
+blocks, which are described in the section below.
+
+Machine Basic Blocks
+--------------------
+
+A machine basic block is defined in a single block definition source construct
+that contains the block's ID.
+The example below defines two blocks that have an ID of zero and one:
+
+.. code-block:: llvm
+
+    bb.0:
+      <instructions>
+    bb.1:
+      <instructions>
+
+A machine basic block can also have a name. It should be specified after the ID
+in the block's definition:
+
+.. code-block:: llvm
+
+    bb.0.entry:       ; This block's name is "entry"
+       <instructions>
+
+The block's name should be identical to the name of the IR block that this
+machine block is based on.
+
+Block References
+^^^^^^^^^^^^^^^^
+
+The machine basic blocks are identified by their ID numbers. Individual
+blocks are referenced using the following syntax:
+
+.. code-block:: llvm
+
+    %bb.<id>[.<name>]
+
+Examples:
+
+.. code-block:: llvm
+
+    %bb.0
+    %bb.1.then
+
+Successors
+^^^^^^^^^^
+
+The machine basic block's successors have to be specified before any of the
+instructions:
+
+.. code-block:: llvm
+
+    bb.0.entry:
+      successors: %bb.1.then, %bb.2.else
+      <instructions>
+    bb.1.then:
+      <instructions>
+    bb.2.else:
+      <instructions>
+
+The branch weights can be specified in brackets after the successor blocks.
+The example below defines a block that has two successors with branch weights
+of 32 and 16:
+
+.. code-block:: llvm
+
+    bb.0.entry:
+      successors: %bb.1.then(32), %bb.2.else(16)
+
+Live In Registers
+^^^^^^^^^^^^^^^^^
+
+The machine basic block's live in registers have to be specified before any of
+the instructions:
+
+.. code-block:: llvm
+
+    bb.0.entry:
+      liveins: %edi, %esi
+
+The list of live in registers and successors can be empty. The language also
+allows multiple live in register and successor lists - they are combined into
+one list by the parser.
+
+Miscellaneous Attributes
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The attributes ``IsAddressTaken``, ``IsLandingPad`` and ``Alignment`` can be
+specified in brackets after the block's definition:
+
+.. code-block:: llvm
+
+    bb.0.entry (address-taken):
+      <instructions>
+    bb.2.else (align 4):
+      <instructions>
+    bb.3(landing-pad, align 4):
+      <instructions>
+
+.. TODO: Describe the way the reference to an unnamed LLVM IR block can be
+   preserved.
+
+
 .. TODO: Describe the parsers default behaviour when optional YAML attributes
    are missing.
 .. TODO: Describe the syntax of the machine instructions.
@@ -99,8 +210,6 @@ the function's machine basic blocks and
    definitions.
 .. TODO: Describe the syntax of the register operand flags and the subregisters.
 .. TODO: Describe the machine function's YAML flag attributes.
-.. TODO: Describe the machine basic block's YAML flag, successors and livein
-   attributes. Describe the syntax for the machine basic block operands.
 .. TODO: Describe the syntax for the global value, external symbol and register
    mask machine operands.
 .. TODO: Describe the frame information YAML mapping.