From: Alex Lorenz Date: Thu, 6 Aug 2015 22:55:19 +0000 (+0000) Subject: Add initial documentation for the MIR serialization format. X-Git-Tag: studio-1.4~628 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=3d311776fbeb0455d9f7535104cf88ddbdb9c8d4;p=platform%2Fupstream%2Fllvm.git Add initial documentation for the MIR serialization format. Differential Revision: http://reviews.llvm.org/D11736 llvm-svn: 244292 --- diff --git a/llvm/docs/MIRLangRef.rst b/llvm/docs/MIRLangRef.rst new file mode 100644 index 0000000..845b2b7 --- /dev/null +++ b/llvm/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 +`. + +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 +`_. + +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. diff --git a/llvm/docs/index.rst b/llvm/docs/index.rst index fcdea03..eea41aa 100644 --- a/llvm/docs/index.rst +++ b/llvm/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 ` + A reference manual for the MIR serialization format, which is used to test + LLVM's code generation passes. + :doc:`TableGen ` Describes the TableGen tool, which is used heavily by the LLVM code generator.