Comdats
-------
-Comdat IR provides access to COFF and ELF object file COMDAT functionality.
+Comdat IR provides access to object file COMDAT/section group functionality
+which represents interrelated sections.
-Comdats have a name which represents the COMDAT key. All global objects that
-specify this key will only end up in the final object file if the linker chooses
-that key over some other key. Aliases are placed in the same COMDAT that their
-aliasee computes to, if any.
+Comdats have a name which represents the COMDAT key and a selection kind to
+provide input on how the linker deduplicates comdats with the same key in two
+different object files. A comdat must be included or omitted as a unit.
+Discarding the whole comdat is allowed but discarding a subset is not.
-Comdats have a selection kind to provide input on how the linker should
-choose between keys in two different object files.
+A global object may be a member of at most one comdat. Aliases are placed in the
+same COMDAT that their aliasee computes to, if any.
Syntax::
$<Name> = comdat SelectionKind
-The selection kind must be one of the following:
+For selection kinds other than ``nodeduplicate``, only one of the duplicate
+comdats may be retained by the linker and the members of the remaining comdats
+must be discarded. The following selection kinds are supported:
``any``
The linker may choose any COMDAT key, the choice is arbitrary.
The linker may choose any COMDAT key but the sections must contain the
same amount of data.
-Note that XCOFF and the Mach-O platform don't support COMDATs, and ELF and
-WebAssembly only support ``any`` as a selection kind.
+- XCOFF and Mach-O don't support COMDATs.
+- COFF supports all selection kinds. Non-``nodeduplicate`` selection kinds need
+ a non-local linkage COMDAT symbol.
+- ELF supports ``any`` and ``nodeduplicate``.
+- WebAssembly only supports ``any``.
-Here is an example of a COMDAT group where a function will only be selected if
+Here is an example of a COFF COMDAT where a function will only be selected if
the COMDAT key's section is the largest:
.. code-block:: text
$foo = comdat any
@foo = global i32 2, comdat
-
+ @bar = global i32 3, comdat($foo)
In a COFF object file, this will create a COMDAT section with selection kind
``IMAGE_COMDAT_SELECT_LARGEST`` containing the contents of the ``@foo`` symbol
If the third field is non-null, and points to a global variable
or function, the initializer function will only run if the associated
data from the current module is not discarded.
+On ELF the referenced global variable or function must be in a comdat.
.. _llvmglobaldtors:
If the third field is non-null, and points to a global variable
or function, the destructor function will only run if the associated
data from the current module is not discarded.
+On ELF the referenced global variable or function must be in a comdat.
Instruction Reference
=====================