[docs] Update some obsolete information in BitCodeFormat docs.

[ibadawi]

Summary

• Describe new (3.3) parameter attribute group encoding, leaving old encoding there with a note about legacy
• Bring TYPE_BLOCK docs up to date
• Remove docs about obsolete (pre 3.0) TYPE_SYMTAB_BLOCK, TST_CODE_ENTRY
• Fix a couple of incorrect comments and remove one unused enum definition along the way

This addresses https://llvm.org/bugs/show_bug.cgi?id=28941.

[mehdi_amini]

This a very nice contribution, thanks a lot for this!

See two nits inline, otherwise LGTM.

docs/BitCodeFormat.rst

898 ↗

(On Diff #74692)

Support will be preserved in 4.0 (and likely 5.0 and future, until we decide explicitly otherwise). See: http://llvm.org/docs/DeveloperPolicy.html#ir-backwards-compatibility

1142 ↗

(On Diff #74692)

(Same remark)

[ibadawi]

Update legacy notices to point to IR backwards compatibility policy.

[ibadawi]

I've updated the legacy notices with a reference to that backwards compatibility policy.

If this looks fine, can you commit it for me? I don't have commit access. Thanks!

llvm/trunk/docs/BitCodeFormat.rst

 
 LLVM IR is defined with the following blocks:
 
 * 8 --- `MODULE_BLOCK`_ --- This is the top-level block that contains the entire
   module, and describes a variety of per-module information.
 
 * 9 --- `PARAMATTR_BLOCK`_ --- This enumerates the parameter attributes.
 
-* 10 --- `TYPE_BLOCK`_ --- This describes all of the types in the module.
+* 10 --- `PARAMATTR_GROUP_BLOCK`_ --- This describes the attribute group table.
 
 * 11 --- `CONSTANTS_BLOCK`_ --- This describes constants for a module or
   function.
 
 * 12 --- `FUNCTION_BLOCK`_ --- This describes a function body.
 
-* 13 --- `TYPE_SYMTAB_BLOCK`_ --- This describes the type symbol table.
-
 * 14 --- `VALUE_SYMTAB_BLOCK`_ --- This describes a value symbol table.
 
 * 15 --- `METADATA_BLOCK`_ --- This describes metadata items.
 
 * 16 --- `METADATA_ATTACHMENT`_ --- This contains records associating metadata
   with function instruction values.
 
+* 17 --- `TYPE_BLOCK`_ --- This describes all of the types in the module.
+
 .. _MODULE_BLOCK:
 
 MODULE_BLOCK Contents
 ---------------------
 
 The ``MODULE_BLOCK`` block (id 8) is the top-level block for LLVM bitcode files,
 and each bitcode file must contain exactly one. In addition to records
 (described below) containing information about the module, a ``MODULE_BLOCK``
 block may contain the following sub-blocks:
 
 * `BLOCKINFO`_
 * `PARAMATTR_BLOCK`_
+* `PARAMATTR_GROUP_BLOCK`_
 * `TYPE_BLOCK`_
-* `TYPE_SYMTAB_BLOCK`_
 * `VALUE_SYMTAB_BLOCK`_
 * `CONSTANTS_BLOCK`_
 * `FUNCTION_BLOCK`_
 * `METADATA_BLOCK`_
 
 .. _MODULE_CODE_VERSION:
 
 MODULE_CODE_VERSION Record

 Entries within ``PARAMATTR_BLOCK`` are constructed to ensure that each is unique
 (i.e., no two indices represent equivalent attribute lists).
 
 .. _PARAMATTR_CODE_ENTRY:
 
 PARAMATTR_CODE_ENTRY Record
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+``[ENTRY, attrgrp0, attrgrp1, ...]``
+
+The ``ENTRY`` record (code 2) contains a variable number of values describing a
+unique set of function parameter attributes. Each *attrgrp* value is used as a
+key with which to look up an entry in the the attribute group table described
+in the ``PARAMATTR_GROUP_BLOCK`` block.
+
+.. _PARAMATTR_CODE_ENTRY_OLD:
+
+PARAMATTR_CODE_ENTRY_OLD Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+  This is a legacy encoding for attributes, produced by LLVM versions 3.2 and
+  earlier. It is guaranteed to be understood by the current LLVM version, as
+  specified in the :ref:`IR backwards compatibility` policy.
+
 ``[ENTRY, paramidx0, attr0, paramidx1, attr1...]``
 
 The ``ENTRY`` record (code 1) contains an even number of values describing a
 unique set of function parameter attributes. Each *paramidx* value indicates
 which set of attributes is represented, with 0 representing the return value
 attributes, 0xFFFFFFFF representing function attributes, and other values
 representing 1-based function parameters. Each *attr* value is a bitmap with the
 following interpretation:

 * bit 32: ``nocapture``
 * bit 33: ``noredzone``
 * bit 34: ``noimplicitfloat``
 * bit 35: ``naked``
 * bit 36: ``inlinehint``
 * bits 37-39: ``alignstack n``, represented as the logarithm
   base 2 of the requested alignment, plus 1
 
+.. _PARAMATTR_GROUP_BLOCK:
+
+PARAMATTR_GROUP_BLOCK Contents
+------------------------------
+
+The ``PARAMATTR_GROUP_BLOCK`` block (id 10) contains a table of entries
+describing the attribute groups present in the module. These entries can be
+referenced within ``PARAMATTR_CODE_ENTRY`` entries.
+
+.. _PARAMATTR_GRP_CODE_ENTRY:
+
+PARAMATTR_GRP_CODE_ENTRY Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[ENTRY, grpid, paramidx, attr0, attr1, ...]``
+
+The ``ENTRY`` record (code 3) contains *grpid* and *paramidx* values, followed
+by a variable number of values describing a unique group of attributes. The
+*grpid* value is a unique key for the attribute group, which can be referenced
+within ``PARAMATTR_CODE_ENTRY`` entries. The *paramidx* value indicates which
+set of attributes is represented, with 0 representing the return value
+attributes, 0xFFFFFFFF representing function attributes, and other values
+representing 1-based function parameters.
+
+Each *attr* is itself represented as a variable number of values:
+
+``kind, key [, ...], [value [, ...]]``
+
+Each attribute is either a well-known LLVM attribute (possibly with an integer
+value associated with it), or an arbitrary string (possibly with an arbitrary
+string value associated with it). The *kind* value is an integer code
+distinguishing between these possibilities:
+
+* code 0: well-known attribute
+* code 1: well-known attribute with an integer value
+* code 3: string attribute
+* code 4: string attribute with a string value
+
+For well-known attributes (code 0 or 1), the *key* value is an integer code
+identifying the attribute. For attributes with an integer argument (code 1),
+the *value* value indicates the argument.
+
+For string attributes (code 3 or 4), the *key* value is actually a variable
+number of values representing the bytes of a null-terminated string. For
+attributes with a string argument (code 4), the *value* value is similarly a
+variable number of values representing the bytes of a null-terminated string.
+
+The integer codes are mapped to well-known attributes as follows.
+
+* code 1: ``align(<n>)``
+* code 2: ``alwaysinline``
+* code 3: ``byval``
+* code 4: ``inlinehint``
+* code 5: ``inreg``
+* code 6: ``minsize``
+* code 7: ``naked``
+* code 8: ``nest``
+* code 9: ``noalias``
+* code 10: ``nobuiltin``
+* code 11: ``nocapture``
+* code 12: ``noduplicates``
+* code 13: ``noimplicitfloat``
+* code 14: ``noinline``
+* code 15: ``nonlazybind``
+* code 16: ``noredzone``
+* code 17: ``noreturn``
+* code 18: ``nounwind``
+* code 19: ``optsize``
+* code 20: ``readnone``
+* code 21: ``readonly``
+* code 22: ``returned``
+* code 23: ``returns_twice``
+* code 24: ``signext``
+* code 25: ``alignstack(<n>)``
+* code 26: ``ssp``
+* code 27: ``sspreq``
+* code 28: ``sspstrong``
+* code 29: ``sret``
+* code 30: ``sanitize_address``
+* code 31: ``sanitize_thread``
+* code 32: ``sanitize_memory``
+* code 33: ``uwtable``
+* code 34: ``zeroext``
+* code 35: ``builtin``
+* code 36: ``cold``
+* code 37: ``optnone``
+* code 38: ``inalloca``
+* code 39: ``nonnull``
+* code 40: ``jumptable``
+* code 41: ``dereferenceable(<n>)``
+* code 42: ``dereferenceable_or_null(<n>)``
+* code 43: ``convergent``
+* code 44: ``safestack``
+* code 45: ``argmemonly``
+* code 46: ``swiftself``
+* code 47: ``swifterror``
+* code 48: ``norecurse``
+* code 49: ``inaccessiblememonly``
+* code 50: ``inaccessiblememonly_or_argmemonly``
+* code 51: ``allocsize(<EltSizeParam>[, <NumEltsParam>])``
+* code 52: ``writeonly``
+
+.. note::
+  The ``allocsize`` attribute has a special encoding for its arguments. Its two
+  arguments, which are 32-bit integers, are packed into one 64-bit integer value
+  (i.e. ``(EltSizeParam << 32) | NumEltsParam``), with ``NumEltsParam`` taking on
+  the sentinel value -1 if it is not specified.
+
 .. _TYPE_BLOCK:
 
 TYPE_BLOCK Contents
 -------------------
 
-The ``TYPE_BLOCK`` block (id 10) contains records which constitute a table of
+The ``TYPE_BLOCK`` block (id 17) contains records which constitute a table of
 type operator entries used to represent types referenced within an LLVM
 module. Each record (with the exception of `NUMENTRY`_) generates a single type
 table entry, which may be referenced by 0-based index from instructions,
 constants, metadata, type symbol table entries, or other type operator records.
 
 Entries within ``TYPE_BLOCK`` are constructed to ensure that each entry is
 unique (i.e., no two indices represent structurally equivalent types).
 

 
 The ``LABEL`` record (code 5) adds a ``label`` type to the type table.
 
 TYPE_CODE_OPAQUE Record
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 ``[OPAQUE]``
 
-The ``OPAQUE`` record (code 6) adds an ``opaque`` type to the type table. Note
-that distinct ``opaque`` types are not unified.
+The ``OPAQUE`` record (code 6) adds an ``opaque`` type to the type table, with
+a name defined by a previously encountered ``STRUCT_NAME`` record. Note that
+distinct ``opaque`` types are not unified.
 
 TYPE_CODE_INTEGER Record
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``[INTEGER, width]``
 
 The ``INTEGER`` record (code 7) adds an integer type to the type table. The
 single *width* field indicates the width of the integer type.
 
 TYPE_CODE_POINTER Record
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``[POINTER, pointee type, address space]``
 
 The ``POINTER`` record (code 8) adds a pointer type to the type table. The
 operand fields are
 
 * *pointee type*: The type index of the pointed-to type
 
 * *address space*: If supplied, the target-specific numbered address space where
   the pointed-to object resides. Otherwise, the default address space is zero.
 
-TYPE_CODE_FUNCTION Record
-^^^^^^^^^^^^^^^^^^^^^^^^^
+TYPE_CODE_FUNCTION_OLD Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``[FUNCTION, vararg, ignored, retty, ...paramty... ]``
+.. note::
+  This is a legacy encoding for functions, produced by LLVM versions 3.0 and
+  earlier. It is guaranteed to be understood by the current LLVM version, as
+  specified in the :ref:`IR backwards compatibility` policy.
 
-The ``FUNCTION`` record (code 9) adds a function type to the type table. The
-operand fields are
+``[FUNCTION_OLD, vararg, ignored, retty, ...paramty... ]``
+
+The ``FUNCTION_OLD`` record (code 9) adds a function type to the type table.
+The operand fields are
 
 * *vararg*: Non-zero if the type represents a varargs function
 
 * *ignored*: This value field is present for backward compatibility only, and is
   ignored
 
 * *retty*: The type index of the function's return type
 
 * *paramty*: Zero or more type indices representing the parameter types of the
   function
 
-TYPE_CODE_STRUCT Record
-^^^^^^^^^^^^^^^^^^^^^^^
-
-``[STRUCT, ispacked, ...eltty...]``
-
-The ``STRUCT`` record (code 10) adds a struct type to the type table. The
-operand fields are
-
-* *ispacked*: Non-zero if the type represents a packed structure
-
-* *eltty*: Zero or more type indices representing the element types of the
-  structure
-
 TYPE_CODE_ARRAY Record
 ^^^^^^^^^^^^^^^^^^^^^^
 
 ``[ARRAY, numelts, eltty]``
 
 The ``ARRAY`` record (code 11) adds an array type to the type table.  The
 operand fields are
 

 
 TYPE_CODE_METADATA Record
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``[METADATA]``
 
 The ``METADATA`` record (code 16) adds a ``metadata`` type to the type table.
 
+TYPE_CODE_X86_MMX Record
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[X86_MMX]``
+
+The ``X86_MMX`` record (code 17) adds an ``x86_mmx`` type to the type table.
+
+TYPE_CODE_STRUCT_ANON Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[STRUCT_ANON, ispacked, ...eltty...]``
+
+The ``STRUCT_ANON`` record (code 18) adds a literal struct type to the type
+table. The operand fields are
+
+* *ispacked*: Non-zero if the type represents a packed structure
+
+* *eltty*: Zero or more type indices representing the element types of the
+  structure
+
+TYPE_CODE_STRUCT_NAME Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[STRUCT_NAME, ...string...]``
+
+The ``STRUCT_NAME`` record (code 19) contains a variable number of values
+representing the bytes of a struct name. The next ``OPAQUE`` or
+``STRUCT_NAMED`` record will use this name.
+
+TYPE_CODE_STRUCT_NAMED Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[STRUCT_NAMED, ispacked, ...eltty...]``
+
+The ``STRUCT_NAMED`` record (code 20) adds an identified struct type to the
+type table, with a name defined by a previously encountered ``STRUCT_NAME``
+record. The operand fields are
+
+* *ispacked*: Non-zero if the type represents a packed structure
+
+* *eltty*: Zero or more type indices representing the element types of the
+  structure
+
+TYPE_CODE_FUNCTION Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[FUNCTION, vararg, retty, ...paramty... ]``
+
+The ``FUNCTION`` record (code 21) adds a function type to the type table. The
+operand fields are
+
+* *vararg*: Non-zero if the type represents a varargs function
+
+* *retty*: The type index of the function's return type
+
+* *paramty*: Zero or more type indices representing the parameter types of the
+  function
+
 .. _CONSTANTS_BLOCK:
 
 CONSTANTS_BLOCK Contents
 ------------------------
 
 The ``CONSTANTS_BLOCK`` block (id 11) ...
 
 .. _FUNCTION_BLOCK:
 
 FUNCTION_BLOCK Contents
 -----------------------
 
 The ``FUNCTION_BLOCK`` block (id 12) ...
 
 In addition to the record types described below, a ``FUNCTION_BLOCK`` block may
 contain the following sub-blocks:
 
 * `CONSTANTS_BLOCK`_
 * `VALUE_SYMTAB_BLOCK`_
 * `METADATA_ATTACHMENT`_
 
-.. _TYPE_SYMTAB_BLOCK:
-
-TYPE_SYMTAB_BLOCK Contents
---------------------------
-
-The ``TYPE_SYMTAB_BLOCK`` block (id 13) contains entries which map between
-module-level named types and their corresponding type indices.
-
-.. _TST_CODE_ENTRY:
-
-TST_CODE_ENTRY Record
-^^^^^^^^^^^^^^^^^^^^^
-
-``[ENTRY, typeid, ...string...]``
-
-The ``ENTRY`` record (code 1) contains a variable number of values, with the
-first giving the type index of the designated type, and the remaining values
-giving the character codes of the type name. Each entry corresponds to a single
-named type.
-
 .. _VALUE_SYMTAB_BLOCK:
 
 VALUE_SYMTAB_BLOCK Contents
 ---------------------------
 
 The ``VALUE_SYMTAB_BLOCK`` block (id 14) ...
 
 .. _METADATA_BLOCK:

llvm/trunk/include/llvm/Bitcode/LLVMBitCodes.h

enum ModuleCodes {
   MODULE_CODE_IFUNC = 18,
 };
 
 /// PARAMATTR blocks have code for defining a parameter attribute set.
 enum AttributeCodes {
   // FIXME: Remove `PARAMATTR_CODE_ENTRY_OLD' in 4.0
   PARAMATTR_CODE_ENTRY_OLD = 1, // ENTRY: [paramidx0, attr0,
                                 //         paramidx1, attr1...]
-  PARAMATTR_CODE_ENTRY = 2,     // ENTRY: [paramidx0, attrgrp0,
-                                //         paramidx1, attrgrp1, ...]
-  PARAMATTR_GRP_CODE_ENTRY = 3  // ENTRY: [id, attr0, att1, ...]
+  PARAMATTR_CODE_ENTRY = 2,     // ENTRY: [attrgrp0, attrgrp1, ...]
+  PARAMATTR_GRP_CODE_ENTRY = 3  // ENTRY: [grpid, idx, attr0, attr1, ...]
 };
 
 /// TYPE blocks have codes for each type primitive they use.
 enum TypeCodes {
   TYPE_CODE_NUMENTRY = 1, // NUMENTRY: [numentries]
 
   // Type Codes
   TYPE_CODE_VOID = 2,    // VOID
enum TypeCodes {
 
   TYPE_CODE_TOKEN = 22 // TOKEN
 };
 
 enum OperandBundleTagCode {
   OPERAND_BUNDLE_TAG = 1, // TAG: [strchr x N]
 };
 
-// The type symbol table only has one code (TST_ENTRY_CODE).
-enum TypeSymtabCodes {
-  TST_CODE_ENTRY = 1 // TST_ENTRY: [typeid, namechar x N]
-};
-
 // Value symbol table codes.
 enum ValueSymtabCodes {
   VST_CODE_ENTRY = 1,   // VST_ENTRY: [valueid, namechar x N]
   VST_CODE_BBENTRY = 2, // VST_BBENTRY: [bbid, namechar x N]
   VST_CODE_FNENTRY = 3, // VST_FNENTRY: [valueid, offset, namechar x N]
   // VST_COMBINED_ENTRY: [valueid, refguid]
   VST_CODE_COMBINED_ENTRY = 5
 };