[nasm:master] docs: Update comdat section attribute

[nasm-bot for Igor Glucksmann]

Commit-ID:  3f9fc2a3a7134936cbbae5780beb4319694f702a
Gitweb:     http://repo.or.cz/w/nasm.git?a=commitdiff;h=3f9fc2a3a7134936cbbae5780beb4319694f702a
Author:     Igor Glucksmann <33635651+igg0 at users.noreply.github.com>
AuthorDate: Fri, 17 Sep 2021 16:54:03 +0200
Committer:  Cyrill Gorcunov <gorcunov at gmail.com>
CommitDate: Fri, 17 Dec 2021 23:45:51 +0300

docs: Update comdat section attribute

Signed-off-by: "Glücksmann, Igor" <igor.glucksmann at avast.com>
Signed-off-by: Cyrill Gorcunov <gorcunov at gmail.com>


---
 doc/nasmdoc.src | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index 3c4f2093..91b4cf7c 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -5896,6 +5896,44 @@ for data (and BSS) sections.
 Informational sections get a default alignment of 1 byte (no
 alignment), though the value does not matter.
 
+\b \I{comdat, win32 attribute}\c{comdat=}, followed by a number
+("selection"), colon (acting as a separator) and a name,
+marks the section as a \I{COMDAT section, in win32}"COMDAT section".
+It allows Microsoft linkers to perform function-level linking,
+to deal with multiply defined symbols, to eliminate dead code/data.
+The "selection" number should be one of the
+\c{IMAGE_COMDAT_SELECT_*} constants from
+\W{https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src/Debug/pe-format.md#comdat-sections-object-only}\c{COFF format specification};
+this value controls if the linker allows multiply defined symbols
+and how it handles them.
+The name is the \I{COMDAT symbol, in win32}"COMDAT symbol"
+- basically a new name for the section. So even though you have one
+section given by the main name (e.g. \c{.text}), it can actually
+consist of hundreds of COMDAT sections having their own name
+(and alignment).
+When the "selection" is IMAGE_COMDAT_SELECT_ASSOCIATIVE (5),
+the following name is the "COMDAT symbol" of the associated COMDAT
+section; this way you can link a piece of code or data only when
+another piece of code or data gets actually linked.
+
+\> So, when linking a NASM-compiled file with some C code,
+the source may be structured as follows.
+Note that the default \c{.text} section in handled in a special
+way and it doesn't work well with \c{comdat}; you may want to append
+a \c{$} character and an arbitrary suffix to the section name.
+It will get linked into the \c{.text} section anyway - see the info on
+\W{https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src/Debug/pe-format.md#grouped-sections-object-only}\c{Grouped Sections}.
+
+\c    section .text$1 align=16 comdat=1:FirstFnc
+\c       ...                                        ; Code linked only if referenced from C
+\c
+\c    section .text$1 align=16 comdat=1:SecondFnc
+\c       ...                                        ; Code linked only if referenced from C
+\c
+\c    section .rdata align=32 comdat=5:FirstFnc
+\c       ...                                        ; Data linked only if the related code (FirstFnc) is linked
+\c
+
 The defaults assumed by NASM if you do not specify the above
 qualifiers are: