diff options
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/Remarks.rst | 245 |
1 files changed, 245 insertions, 0 deletions
diff --git a/llvm/docs/Remarks.rst b/llvm/docs/Remarks.rst index f4e5d8f45e6..8dba1947d70 100644 --- a/llvm/docs/Remarks.rst +++ b/llvm/docs/Remarks.rst @@ -113,6 +113,7 @@ following options: * :ref:`yaml <yamlremarks>` (default) * :ref:`yaml-strtab <yamlstrtabremarks>` + * :ref:`bitstream <bitstreamremarks>` ``Content configuration`` @@ -260,6 +261,250 @@ should be present and point to the file where the remarks are serialized to. In case the metadata only acts as a header to the remarks, the file path can be omitted. +.. _bitstreamremarks: + +LLVM bitstream remarks +====================== + +This format is using :doc:`LLVM bitstream <BitCodeFormat>` to serialize remarks +and their associated metadata. + +A bitstream remark stream can be identified by the magic number ``"RMRK"`` that +is placed at the very beginning. + +The format for serializing remarks is composed of two different block types: + +.. _bitstreamremarksmetablock: + +META_BLOCK +---------- + +The block providing information about the rest of the content in the stream. + +Exactly one block is expected. Having multiple metadata blocks is an error. + +This block can contain the following records: + +.. _bitstreamremarksrecordmetacontainerinfo: + +``RECORD_META_CONTAINER_INFO`` + + The container version and type. + + Version: u32 + + Type: u2 + +.. _bitstreamremarksrecordmetaremarkversion: + +``RECORD_META_REMARK_VERSION`` + + The version of the remark entries. This can change independently from the + container version. + + Version: u32 + +.. _bitstreamremarksrecordmetastrtab: + +``RECORD_META_STRTAB`` + + The string table used by the remark entries. The format of the string table + is a sequence of strings separated by ``\0``. + +.. _bitstreamremarksrecordmetaexternalfile: + +``RECORD_META_EXTERNAL_FILE`` + + The external remark file path that contains the remark blocks associated + with this metadata. This is an absolute path. + +.. _bitstreamremarksremarkblock: + +REMARK_BLOCK +------------ + +The block describing a remark entry. + +0 or more blocks per file are allowed. Each block will depend on the +:ref:`META_BLOCK <bitstreamremarksmetablock>` in order to be parsed correctly. + +This block can contain the following records: + +``RECORD_REMARK_HEADER`` + + The header of the remark. This contains all the mandatory information about + a remark. + + +---------------+---------------------------+ + | Type | u3 | + +---------------+---------------------------+ + | Remark name | VBR6 (string table index) | + +---------------+---------------------------+ + | Pass name | VBR6 (string table index) | + +---------------+---------------------------+ + | Function name | VBR6 (string table index) | + +---------------+---------------------------+ + +``RECORD_REMARK_DEBUG_LOC`` + + The source location for the corresponding remark. This record is optional. + + +--------+---------------------------+ + | File | VBR7 (string table index) | + +--------+---------------------------+ + | Line | u32 | + +--------+---------------------------+ + | Column | u32 | + +--------+---------------------------+ + +``RECORD_REMARK_HOTNESS`` + + The hotness of the remark. This record is optional. + + +---------------+---------------------+ + | Hotness | VBR8 (string table index) | + +---------------+---------------------+ + +``RECORD_REMARK_ARG_WITH_DEBUGLOC`` + + A remark argument with an associated debug location. + + +--------+---------------------------+ + | Key | VBR7 (string table index) | + +--------+---------------------------+ + | Value | VBR7 (string table index) | + +--------+---------------------------+ + | File | VBR7 (string table index) | + +--------+---------------------------+ + | Line | u32 | + +--------+---------------------------+ + | Column | u32 | + +--------+---------------------------+ + +``RECORD_REMARK_ARG_WITHOUT_DEBUGLOC`` + + A remark argument with an associated debug location. + + +--------+---------------------------+ + | Key | VBR7 (string table index) | + +--------+---------------------------+ + | Value | VBR7 (string table index) | + +--------+---------------------------+ + +The remark container +-------------------- + +Bitstream remarks are designed to be used in two different modes: + +``The separate mode`` + + The separate mode is the mode that is typically used during compilation. It + provides a way to serialize the remark entries to a stream while some + metadata is kept in memory to be emitted in the product of the compilation + (typically, an object file). + +``The standalone mode`` + + The standalone mode is typically stored and used after the distribution of + a program. It contains all the information that allows the parsing of all + the remarks without having any external dependencies. + +In order to support multiple modes, the format introduces the concept of a +bitstream remark container type. + +.. _bitstreamremarksseparateremarksmeta: + +``SeparateRemarksMeta: the metadata emitted separately`` + + This container type expects only a :ref:`META_BLOCK <bitstreamremarksmetablock>` containing only: + + * :ref:`RECORD_META_CONTAINER_INFO <bitstreamremarksrecordmetacontainerinfo>` + * :ref:`RECORD_META_STRTAB <bitstreamremarksrecordmetastrtab>` + * :ref:`RECORD_META_EXTERNAL_FILE <bitstreamremarksrecordmetaexternalfile>` + + Typically, this is emitted in a section in the object files, allowing + clients to retrieve remarks and their associated metadata directly from + intermediate products. + +``SeparateRemarksFile: the remark entries emitted separately`` + + This container type expects only a :ref:`META_BLOCK <bitstreamremarksmetablock>` containing only: + + * :ref:`RECORD_META_CONTAINER_INFO <bitstreamremarksrecordmetacontainerinfo>` + * :ref:`RECORD_META_REMARK_VERSION <bitstreamremarksrecordmetaremarkversion>` + + This container type expects 0 or more :ref:`REMARK_BLOCK <bitstreamremarksremarkblock>`. + + Typically, this is emitted in a side-file alongside an object file, and is + made to be able to stream to without increasing the memory consumption of + the compiler. This is referenced by the :ref:`RECORD_META_EXTERNAL_FILE + <bitstreamremarksrecordmetaexternalfile>` entry in the + :ref:`SeparateRemarksMeta <bitstreamremarksseparateremarksmeta>` container. + +When the parser tries to parse a container that contains the metadata for the +separate remarks, it should parse the version and type, then keep the string +table in memory while opening the external file, validating its metadata and +parsing the remark entries. + +The container versions from the separate container should match in order to +have a well-formed file. + +``Standalone: the metadata and the remark entries emitted together`` + + This container type expects only a :ref:`META_BLOCK <bitstreamremarksmetablock>` containing only: + + * :ref:`RECORD_META_CONTAINER_INFO <bitstreamremarksrecordmetacontainerinfo>` + * :ref:`RECORD_META_REMARK_VERSION <bitstreamremarksrecordmetaremarkversion>` + * :ref:`RECORD_META_STRTAB <bitstreamremarksrecordmetastrtab>` + + This container type expects 0 or more :ref:`REMARK_BLOCK <bitstreamremarksremarkblock>`. + +A complete output of :program:`llvm-bcanalyzer` on the different container types: + +``SeparateRemarksMeta`` + +.. code-block:: none + + <BLOCKINFO_BLOCK/> + <Meta BlockID=8 NumWords=13 BlockCodeSize=3> + <Container info codeid=1 abbrevid=4 op0=5 op1=0/> + <String table codeid=3 abbrevid=5/> blob data = 'pass\\x00key\\x00value\\x00' + <External File codeid=4 abbrevid=6/> blob data = '/path/to/file/name' + </Meta> + +``SeparateRemarksFile`` + +.. code-block:: none + + <BLOCKINFO_BLOCK/> + <Meta BlockID=8 NumWords=3 BlockCodeSize=3> + <Container info codeid=1 abbrevid=4 op0=0 op1=1/> + <Remark version codeid=2 abbrevid=5 op0=0/> + </Meta> + <Remark BlockID=9 NumWords=8 BlockCodeSize=4> + <Remark header codeid=5 abbrevid=4 op0=2 op1=0 op2=1 op3=2/> + <Remark debug location codeid=6 abbrevid=5 op0=3 op1=99 op2=55/> + <Remark hotness codeid=7 abbrevid=6 op0=999999999/> + <Argument with debug location codeid=8 abbrevid=7 op0=4 op1=5 op2=6 op3=11 op4=66/> + </Remark> + +``Standalone`` + +.. code-block:: none + + <BLOCKINFO_BLOCK/> + <Meta BlockID=8 NumWords=15 BlockCodeSize=3> + <Container info codeid=1 abbrevid=4 op0=5 op1=2/> + <Remark version codeid=2 abbrevid=5 op0=30/> + <String table codeid=3 abbrevid=6/> blob data = 'pass\\x00remark\\x00function\\x00path\\x00key\\x00value\\x00argpath\\x00' + </Meta> + <Remark BlockID=9 NumWords=8 BlockCodeSize=4> + <Remark header codeid=5 abbrevid=4 op0=2 op1=1 op2=0 op3=2/> + <Remark debug location codeid=6 abbrevid=5 op0=3 op1=99 op2=55/> + <Remark hotness codeid=7 abbrevid=6 op0=999999999/> + <Argument with debug location codeid=8 abbrevid=7 op0=4 op1=5 op2=6 op3=11 op4=66/> + </Remark> + opt-viewer ========== |
