From bd978a4d2009fe4358d5baab4072585558048dd8 Mon Sep 17 00:00:00 2001 From: Alex Lorenz Date: Sat, 15 Aug 2015 01:06:06 +0000 Subject: [PATCH] MIRLangRef: Describe the syntax that is used to represent machine basic blocks. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@245138 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/MIRLangRef.rst | 113 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 111 insertions(+), 2 deletions(-) diff --git a/docs/MIRLangRef.rst b/docs/MIRLangRef.rst index b3bf3294ef7..b3d558a9a5e 100644 --- a/docs/MIRLangRef.rst +++ b/docs/MIRLangRef.rst @@ -90,6 +90,117 @@ name of a function that this machine function is based on. 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: + + bb.1: + + +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" + + +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.[.] + +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 + + bb.1.then: + + bb.2.else: + + +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): + + bb.2.else (align 4): + + bb.3(landing-pad, align 4): + + +.. 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 their machine instructions. 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. -- 2.34.1