Initial documentation for the MIR serialization format.

[arphaman]

Summary

This patch contains an initial documentation for the MIR serialization format.

This initial document contains the 'Introduction', 'Overview' and the 'High Level Structure' sections,
which briefly describe the MIR serialization format. The follow up patches will expand on this initial
document and will describe the format using the appropriate level of detail.

[silvas]

LGTM, but a couple comments/questions.

docs/MachineIRRef.rst

41–42 ↗

(On Diff #31265)

Do you actually depend on it being a block literal string? I thought that that was just syntax sugar in the YAML language, so that really any string should be fine (although the block literal string is probably easiest to read)

83–94 ↗

(On Diff #31265)

Please add specific TODO's here for everything that is merely touched on (but that you know you eventually need to expand on) so that nothing falls through the cracks.

[arphaman]

docs/MachineIRRef.rst

41–42 ↗

(On Diff #31265)

Yes, right now this has to be an actual block literal scalar, as the YAML parser has a separate node class for block scalars, and the MIR parser looks for that node when looking for the embedded IR module.

[arphaman]

The updated patch fixes the style suggestions from Justin, adds TODOs, and renames the file to MIRLangRef.rst.

llvm/trunk/docs/MIRLangRef.rst

+========================================
+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.

llvm/trunk/docs/index.rst

.. toctree::
    StackMaps
    InAlloca
    BigEndianNEON
    CoverageMappingFormat
    Statepoints
    MergeFunctions
    BitSets
    FaultMaps
+   MIRLangRef
 
 :doc:`WritingAnLLVMPass`
    Information on how to write LLVM transformations and analyses.
 
 :doc:`WritingAnLLVMBackend`
    Information on how to write LLVM backends for machine targets.
 
 :doc:`CodeGenerator`
    The design and implementation of the LLVM code generator.  Useful if you are
    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.
 
 :doc:`AliasAnalysis`
    Information on how to write a new alias analysis implementation or how to
    use existing analyses.