[LangRef] Clarify comdat

[MaskRay]

Summary

• 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.

[MaskRay]

llvm/docs/LangRef.rst

953

I'll move WebAssembly to a separate list item.

[dschuff]

llvm/docs/LangRef.rst

944–945

This wording is confusing: the term "noduplicates" seems to be in conflict with the idea that no deduplication is performed (which could result in there being duplicates in the output). Is that intentional? Does it mean that the compiler must ensure that there are no duplicates (which would allow the linker to skip deduplication)? If so, I think ti would be good to clarify.

[MaskRay]

llvm/docs/LangRef.rst

944–945

I agree that noduplicates is confusing. The word says the opposite to that the implementation actually does...

I will send a patch to renaming it...

[dschuff]

llvm/docs/LangRef.rst

944–945

Sounds good. I don't think that needs to block this CL though, if it describes the current situation accurately. I'll let @sbc100 take a look from the wasm side too though.

[MaskRay]

llvm/docs/LangRef.rst

944–945

Sent D106319 to rename noduplicates to nodeduplicate.

The IR name has the PE origin IMAGE_COMDAT_SELECT_NODUPLICATES which IMHO is not an ideal name.

[MaskRay]

rebase after noduplicates->nodeduplicate renaming

[MaskRay]

Clarify llvm.global_ctors

[MaskRay]

Drop llvm.global_ctors change

ELF probably should use SHF_LINK_ORDER instead to avoid the ldc compiler's confusion

[rnk]

Looks good to me

llvm/docs/LangRef.rst

Syntax::
     @<Name> = [Linkage] [Visibility] ifunc <IFuncTy>, <ResolverTy>* @<Resolver>
 
 
 .. _langref_comdats:
 
 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.
 ``exactmatch``
     The linker may choose any COMDAT key but the sections must contain the
     same data.
 ``largest``
     The linker will choose the section containing the largest COMDAT key.
 ``nodeduplicate``
     No deduplication is performed.
 ``samesize``
     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 largest
    @foo = global i32 2, comdat($foo)
 
    define void @bar() comdat($foo) {
      ret void
    }
 
 As a syntactic sugar the ``$name`` can be omitted if the name is the same as
 the global name:
 
 .. code-block:: llvm
 
   $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
 and another COMDAT section with selection kind
 ``IMAGE_COMDAT_SELECT_ASSOCIATIVE`` which is associated with the first COMDAT
 section and contains the contents of the ``@bar`` symbol.
 
 There are some restrictions on the properties of the global object.

 functions, priorities, and an associated global or function.
 The functions referenced by this array will be called in ascending order
 of priority (i.e. lowest first) when the module is loaded. The 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 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:
 
 The '``llvm.global_dtors``' Global Variable
 -------------------------------------------
 
 .. code-block:: llvm
 
     %0 = type { i32, void ()*, i8* }
     @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor, i8* @data }]
 
 The ``@llvm.global_dtors`` array contains a list of destructor
 functions, priorities, and an associated global or function.
 The functions referenced by this array will be called in descending
 order of priority (i.e. highest first) when the module is unloaded. The
 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
 =====================
 
 The LLVM instruction set consists of several different classifications
 of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary
 instructions <binaryops>`, :ref:`bitwise binary
 instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and