[llvm] r244292 - Add initial documentation for the MIR serialization format.
Alex Lorenz via llvm-commits
llvm-commits at lists.llvm.org
Thu Aug 6 15:55:19 PDT 2015
Author: arphaman
Date: Thu Aug 6 17:55:19 2015
New Revision: 244292
URL: http://llvm.org/viewvc/llvm-project?rev=244292&view=rev
Log:
Add initial documentation for the MIR serialization format.
Differential Revision: http://reviews.llvm.org/D11736
Added:
llvm/trunk/docs/MIRLangRef.rst
Modified:
llvm/trunk/docs/index.rst
Added: llvm/trunk/docs/MIRLangRef.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/MIRLangRef.rst?rev=244292&view=auto
==============================================================================
--- llvm/trunk/docs/MIRLangRef.rst (added)
+++ llvm/trunk/docs/MIRLangRef.rst Thu Aug 6 17:55:19 2015
@@ -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.
Modified: llvm/trunk/docs/index.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=244292&r1=244291&r2=244292&view=diff
==============================================================================
--- llvm/trunk/docs/index.rst (original)
+++ llvm/trunk/docs/index.rst Thu Aug 6 17:55:19 2015
@@ -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.
More information about the llvm-commits
mailing list