cmd/link: add comments for SymKind values

Change-Id: Ie297a19a59362e0f32eae20e511e298a0a87ab6b
Reviewed-on: https://go-review.googlesource.com/c/go/+/715540
Reviewed-by: Than McIntosh <thanm@golang.org>
Auto-Submit: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Cherry Mui <cherryyz@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Michael Pratt <mpratt@google.com>

diff --git a/src/cmd/link/internal/sym/symkind.go b/src/cmd/link/internal/sym/symkind.go
index 0671d9d724d25d38d1697b41a772da64f6819d46..031cc37c2e8740dff9eb7177db7ddd47137e3406 100644 (file)
--- a/src/cmd/link/internal/sym/symkind.go
+++ b/src/cmd/link/internal/sym/symkind.go
@@ -41,31 +41,32 @@ type SymKind uint8
 //
 //go:generate stringer -type=SymKind
 const (
+       // An otherwise invalid zero value for the type.
        Sxxx SymKind = iota
-       STEXT
-       STEXTFIPSSTART
-       STEXTFIPS
-       STEXTFIPSEND
-       STEXTEND
-       SELFRXSECT
-       SMACHOPLT
-
-       // Read-only sections.
-       STYPE
-       SSTRING
-       SGOSTRING
-       SGOFUNC
-       SGCBITS
-       SRODATA
-       SRODATAFIPSSTART
-       SRODATAFIPS
-       SRODATAFIPSEND
-       SRODATAEND
-       SFUNCTAB
-
-       SELFROSECT
-
-       // Read-only sections with relocations.
+       // The text segment, containing executable instructions.
+       STEXT          // General executable code.
+       STEXTFIPSSTART // Start of FIPS text section.
+       STEXTFIPS      // Instructions hashed for FIPS checks.
+       STEXTFIPSEND   // End of FIPS text section.
+       STEXTEND       // End of text section.
+       SELFRXSECT     // Executable PLT; PPC64 .glink.
+       SMACHOPLT      // Mach-O PLT.
+
+       // Read-only, non-executable, segment.
+       STYPE            // Type descriptors.
+       SSTRING          // Used only for XCOFF runtime.rodata symbol?
+       SGOSTRING        // Go string constants.
+       SGOFUNC          // Function descriptors and funcdata symbols.
+       SGCBITS          // GC bit masks and programs.
+       SRODATA          // General read-only data.
+       SRODATAFIPSSTART // Start of FIPS read-only data.
+       SRODATAFIPS      // FIPS read-only data.
+       SRODATAFIPSEND   // End of FIPS read-only data.
+       SRODATAEND       // End of read-only data.
+       SFUNCTAB         // Appears to be unused, except for runtime.etypes.
+       SELFROSECT       // ELF read-only data: relocs, dynamic linking info.
+
+       // Read-only, non-executable, dynamically relocatable segment.
        //
        // Types STYPE-SFUNCTAB above are written to the .rodata section by default.
        // When linking a shared object, some conceptually "read only" types need to
@@ -84,55 +85,59 @@ const (
        SGCBITSRELRO
        SRODATARELRO
        SFUNCTABRELRO
-       SELFRELROSECT
-       SMACHORELROSECT
 
-       // Part of .data.rel.ro if it exists, otherwise part of .rodata.
-       STYPELINK
-       SITABLINK
-       SSYMTAB
-       SPCLNTAB
+       SELFRELROSECT   // ELF-specific read-only relocatable: PLT, etc.
+       SMACHORELROSECT // Mach-O specific read-only relocatable.
 
-       // Writable sections.
+       STYPELINK // Type links.
+       SITABLINK // Itab links.
+       SSYMTAB   // Used for runtime.symtab, which is always empty.
+       SPCLNTAB  // Pclntab data.
+
+       // Allocated writable segment.
        SFirstWritable
-       SBUILDINFO
-       SFIPSINFO
-       SELFSECT
-       SMACHO
-       SMACHOGOT
-       SWINDOWS
-       SELFGOT
-       SNOPTRDATA
-       SNOPTRDATAFIPSSTART
-       SNOPTRDATAFIPS
-       SNOPTRDATAFIPSEND
-       SNOPTRDATAEND
-       SINITARR
-       SDATA
-       SDATAFIPSSTART
-       SDATAFIPS
-       SDATAFIPSEND
-       SDATAEND
-       SXCOFFTOC
-       SBSS
-       SNOPTRBSS
-       SLIBFUZZER_8BIT_COUNTER
-       SCOVERAGE_COUNTER
-       SCOVERAGE_AUXVAR
-       STLSBSS
-       SXREF
-       SMACHOSYMSTR
-       SMACHOSYMTAB
-       SMACHOINDIRECTPLT
-       SMACHOINDIRECTGOT
-       SFILEPATH
-       SDYNIMPORT
-       SHOSTOBJ
-       SUNDEFEXT // Undefined symbol for resolution by external linker
-
-       // Sections for debugging information
+       SBUILDINFO          // debug/buildinfo data (why is this writable?).
+       SFIPSINFO           // go:fipsinfo aka crypto/internal/fips140/check.Linkinfo (why is this writable)?
+       SELFSECT            // .got.plt, .plt, .dynamic where appropriate.
+       SMACHO              // Used only for .llvmasm?
+       SMACHOGOT           // Mach-O GOT.
+       SWINDOWS            // Windows dynamic symbols.
+       SELFGOT             // Writable ELF GOT section.
+       SNOPTRDATA          // Data with no heap pointers.
+       SNOPTRDATAFIPSSTART // Start of FIPS non-pointer writable data.
+       SNOPTRDATAFIPS      // FIPS non-pointer writable data.
+       SNOPTRDATAFIPSEND   // End of FIPS non-pointer writable data.
+       SNOPTRDATAEND       // End of data with no heap pointers.
+       SINITARR            // ELF .init_array section.
+       SDATA               // Data that may have heap pointers.
+       SDATAFIPSSTART      // Start of FIPS writable data.
+       SDATAFIPS           // FIPS writable data.
+       SDATAFIPSEND        // End of FIPS writable data.
+       SDATAEND            // End of data that may have heap pointers.
+       SXCOFFTOC           // AIX TOC entries.
+
+       // Allocated zero-initialized segment.
+       SBSS                    // Zeroed data that may have heap pointers.
+       SNOPTRBSS               // Zeroed data with no heap pointers.
+       SLIBFUZZER_8BIT_COUNTER // Fuzzer counters.
+       SCOVERAGE_COUNTER       // Coverage counters.
+       SCOVERAGE_AUXVAR        // Compiler generated coverage symbols.
+       STLSBSS                 // Thread-local zeroed data.
+
+       // Unallocated segment.
+       SXREF             // Reference from non-Go object file.
+       SMACHOSYMSTR      // Mach-O string table.
+       SMACHOSYMTAB      // Mach-O symbol table.
+       SMACHOINDIRECTPLT // Mach-O indirect PLT.
+       SMACHOINDIRECTGOT // Mach-O indirect GOT.
+       SFILEPATH         // Unused?
+       SDYNIMPORT        // Reference to symbol defined in shared library.
+       SHOSTOBJ          // Symbol defined in non-Go object file.
+       SUNDEFEXT         // Undefined symbol for resolution by external linker.
+
+       // Unallocated DWARF debugging segment.
        SDWARFSECT
-       // DWARF symbol types
+       // DWARF symbol types created by compiler or linker.
        SDWARFCUINFO
        SDWARFCONST
        SDWARFFCN
@@ -144,9 +149,9 @@ const (
        SDWARFLINES
        SDWARFADDR
 
-       // SEH symbol types
-       SSEHUNWINDINFO
-       SSEHSECT
+       // SEH symbol types. These are probably allocated at run time.
+       SSEHUNWINDINFO // Compiler generated Windows SEH info.
+       SSEHSECT       // Windows SEH data.
 )
 
 // AbiSymKindToSymKind maps values read from object files (which are