Add initial documentation for the MIR serialization format.

Differential Revision: http://reviews.llvm.org/D11736

llvm-svn: 244292

docs/MIRLangRef.rst

@@ -0,0 +1,124 @@
+========================================
+Machine IR (MIR) Format Reference Manual
+========================================
+
+.. contents::
+   :local:
+
+.. warning::
+  This is a work in progress.
+
+Introduction
+============
+
+This document is a reference manual for the Machine IR (MIR) serialization
+format. MIR is a human readable serialization format that is used to represent
+LLVM's :ref:`machine specific intermediate representation
+<machine code representation>`.
+
+The MIR serialization format is designed to be used for testing the code
+generation passes in LLVM.
+
+Overview
+========
+
+The MIR serialization format uses a YAML container. YAML is a standard
+data serialization language, and the full YAML language spec can be read at
+`yaml.org
+<http://www.yaml.org/spec/1.2/spec.html#Introduction>`_.
+
+A MIR file is split up into a series of `YAML documents`_. The first document
+can contain an optional embedded LLVM IR module, and the rest of the documents
+contain the serialized machine functions.
+
+.. _YAML documents: http://www.yaml.org/spec/1.2/spec.html#id2800132
+
+High Level Structure
+====================
+
+Embedded Module
+---------------
+
+When the first YAML document contains a `YAML block literal string`_, the MIR
+parser will treat this string as an LLVM assembly language string that
+represents an embedded LLVM IR module.
+Here is an example of a YAML document that contains an LLVM module:
+
+.. code-block:: llvm
+
+     --- |
+       define i32 @inc(i32* %x) {
+       entry:
+         %0 = load i32, i32* %x
+         %1 = add i32 %0, 1
+         store i32 %1, i32* %x
+         ret i32 %1
+       }
+     ...
+
+.. _YAML block literal string: http://www.yaml.org/spec/1.2/spec.html#id2795688
+
+Machine Functions
+-----------------
+
+The remaining YAML documents contain the machine functions. This is an example
+of such YAML document:
+
+.. code-block:: yaml
+
+     ---
+     name:            inc
+     tracksRegLiveness: true
+     liveins:
+       - { reg: '%rdi' }
+     body:
+       - id:              0
+         name:            entry
+         liveins:         [ '%rdi' ]
+         instructions:
+           - '%eax = MOV32rm %rdi, 1, _, 0, _'
+           - '%eax = INC32r killed %eax, implicit-def dead %eflags'
+           - 'MOV32mr killed %rdi, 1, _, 0, _, %eax'
+           - 'RETQ %eax'
+     ...
+
+The document above consists of attributes that represent the various
+properties and data structures in a machine function.
+
+The attribute ``name`` is required, and its value should be identical to the
+name of a function that this machine function is based on.
+
+The attribute ``body`` contains a list of YAML mappings that represent the
+function's machine basic blocks.
+
+The first machine basic block in the ``body`` list above contains the attribute
+``instructions``. This attribute stores a list of string literals which
+represent the machine instructions for that basic block.
+
+.. TODO: Describe the parsers default behaviour when optional YAML attributes
+   are missing.
+.. TODO: Describe the syntax of the machine instructions.
+.. TODO: Describe the syntax of the immediate machine operands.
+.. TODO: Describe the syntax of the register machine operands.
+.. TODO: Describe the syntax of the virtual register operands and their YAML
+   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.
+.. TODO: Describe the syntax of the stack object machine operands and their
+   YAML definitions.
+.. TODO: Describe the syntax of the constant pool machine operands and their
+   YAML definitions.
+.. TODO: Describe the syntax of the jump table machine operands and their
+   YAML definitions.
+.. TODO: Describe the syntax of the block address machine operands.
+.. TODO: Describe the syntax of the CFI index machine operands.
+.. TODO: Describe the syntax of the metadata machine operands, and the
+   instructions debug location attribute.
+.. TODO: Describe the syntax of the target index machine operands.
+.. TODO: Describe the syntax of the register live out machine operands.
+.. TODO: Describe the syntax of the machine memory operands.

docs/index.rst

@@ -261,6 +261,7 @@ For API clients and LLVM developers.
    MergeFunctions
    BitSets
    FaultMaps
+   MIRLangRef
 
 :doc:`WritingAnLLVMPass`
    Information on how to write LLVM transformations and analyses.
@@ -273,6 +274,10 @@ For API clients and LLVM developers.
    working on retargetting LLVM to a new architecture, designing a new codegen
    pass, or enhancing existing components.
 
+:doc:`Machine IR (MIR) Format Reference Manual <MIRLangRef>`
+   A reference manual for the MIR serialization format, which is used to test
+   LLVM's code generation passes.
+
 :doc:`TableGen <TableGen/index>`
    Describes the TableGen tool, which is used heavily by the LLVM code
    generator.