[PATCH] D11736: Initial documentation for the MIR serialization format.

[Justin Bogner]

Alex Lorenz <arphaman at gmail.com> writes:
> arphaman created this revision.
> arphaman added reviewers: silvas, dexonsmith, bogner, bob.wilson.
> arphaman added a subscriber: llvm-commits.
> arphaman set the repository for this revision to rL LLVM.
>
> 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.

It's probably simpler to do these documentation reviews as post-commit,
rather than sending patches. In any case, a couple of sphinx syntax
nitpicks below, then LGTM.

> Repository:
>   rL LLVM
>
> http://reviews.llvm.org/D11736
>
> Files:
>   docs/MachineIRRef.rst
>   docs/index.rst
>
> Index: docs/index.rst
> ===================================================================
> --- docs/index.rst
> +++ docs/index.rst
> @@ -261,6 +261,7 @@
>     MergeFunctions
>     BitSets
>     FaultMaps
> +   MachineIRRef
>  
>  :doc:`WritingAnLLVMPass`
>     Information on how to write LLVM transformations and analyses.
> @@ -273,6 +274,10 @@
>     working on retargetting LLVM to a new architecture, designing a new codegen
>     pass, or enhancing existing components.
>  
> +:doc:`MIR Format Reference <MachineIRRef>`

This should probaly read "Machine IR (MIR) Format Reference Manual" to
match the title in the document.

> +   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.
> Index: docs/MachineIRRef.rst
> ===================================================================
> --- /dev/null
> +++ docs/MachineIRRef.rst
> @@ -0,0 +1,95 @@
> +========================================
> +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 `machine specific intermediate representation
> +<CodeGenerator.html#machine-code-description-classes>`_.

You should use :ref: to cross reference other llvm docs. I think you
mean :ref:`machine code representation` here.

> +
> +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
> +<http://www.yaml.org/spec/1.2/spec.html#id2800132>`_. The first document
> +can contain an optional embedded LLVM IR module, and the rest of the documents
> +contain the serialized machine functions.

I'd probably use out-of-line urls here, like:

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
> +<http://www.yaml.org/spec/1.2/spec.html#id2795688>`_, 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
> +       }
> +     ...
> +
> +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.
> +