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>

Author: ianlancetaylor

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