From 901ac46df8e742369e4b79c41e739eb3d7ffc7e5 Mon Sep 17 00:00:00 2001 From: Josh Bleecher Snyder Date: Mon, 20 Sep 2021 14:13:07 -0700 Subject: [PATCH] cmd/link: document generator symbols more And make the existing docs easier to parse. In particular, document the interaction with relocations. Change-Id: I97579f88d9248c12e64af723a946959b88d4b674 Reviewed-on: https://go-review.googlesource.com/c/go/+/351112 Trust: Josh Bleecher Snyder Run-TryBot: Josh Bleecher Snyder TryBot-Result: Go Bot Reviewed-by: Cherry Mui --- src/cmd/link/internal/ld/link.go | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/cmd/link/internal/ld/link.go b/src/cmd/link/internal/ld/link.go index 13618beff9..64d18bd62c 100644 --- a/src/cmd/link/internal/ld/link.go +++ b/src/cmd/link/internal/ld/link.go @@ -148,12 +148,18 @@ func (ctxt *Link) MaxVersion() int { } // generatorFunc is a convenience type. -// Linker created symbols that are large, and shouldn't really live in the -// heap can define a generator function, and their bytes can be generated +// Some linker-created Symbols are large and shouldn't really live in the heap. +// Such Symbols can define a generator function. Their bytes can be generated // directly in the output mmap. // -// Generator symbols shouldn't grow the symbol size, and might be called in -// parallel in the future. +// Relocations are applied prior to emitting generator Symbol contents. +// Generator Symbols that require relocations can be written in two passes. +// The first pass, at Symbol creation time, adds only relocations. +// The second pass, at content generation time, adds the rest. +// See generateFunctab for an example. +// +// Generator functions shouldn't grow the Symbol size. +// Generator functions must be safe for concurrent use. // // Generator Symbols have their Data set to the mmapped area when the // generator is called. -- 2.50.0