From d5401315cd29b67607b5914997c99d34427ac354 Mon Sep 17 00:00:00 2001 From: Fangrui Song Date: Fri, 23 Jul 2021 16:33:06 -0700 Subject: [PATCH] [LangRef] Clarify comdat * ELF supports `nodeduplicate`. * ELF calls the concept "section group". `GRP_COMDAT` emulates the PE COMDAT deduplication feature. * "COMDAT group" is an ELF term. Avoid it for PE/COFF. * WebAssembly supports comdat but only supports the `any` selection kind. https://bugs.llvm.org/show_bug.cgi?id=50531 * A comdat must be included or omitted as a unit. Both the compiler and the linker must obey this rule. * A global object can be a member of at most one comdat. * COFF requires a non-local linkage for non-`nodeduplicate` selection kinds. * llvm.global_ctors/.llvm.global_dtors: if the third field is used on ELF, it must reference a global variable or function in a comdat Reviewed By: rnk Differential Revision: https://reviews.llvm.org/D106300 --- llvm/docs/LangRef.rst | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index 9996568..beeffeb 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -915,21 +915,24 @@ Syntax:: 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:: $ = 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. @@ -944,10 +947,13 @@ The selection kind must be one of the following: 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 @@ -966,7 +972,7 @@ the global name: $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 @@ -7737,6 +7743,7 @@ functions with the same priority is not defined. 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: @@ -7757,6 +7764,7 @@ order of functions with the same priority is not defined. 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 ===================== -- 2.7.4