From d73aa535ded764933aa63e4c2c8fb34e479270cb Mon Sep 17 00:00:00 2001
From: Mark Freeman <mark@golang.org>
Date: Wed, 7 May 2025 16:49:02 -0400
Subject: [PATCH] cmd/compile/internal/noder: begin documenting meta section
Meta is the most fundamental section. To flesh this out, we discuss references. Primitives are briefly mentioned by pointing to pkgbits,
where they will be defined using a similar grammar.
Change-Id: I7abd899f38fad4cc5caf87ebfc7aa1b1985b17d4
Reviewed-on: https://go-review.googlesource.com/c/go/+/671176
Auto-Submit: Mark Freeman <mark@golang.org>
TryBot-Bypass: Mark Freeman <mark@golang.org>
Reviewed-by: Robert Griesemer <gri@google.com>
---
src/cmd/compile/internal/noder/doc.go | 91 ++++++++++++++++++++++-----
1 file changed, 77 insertions(+), 14 deletions(-)
diff --git a/src/cmd/compile/internal/noder/doc.go b/src/cmd/compile/internal/noder/doc.go
index 3c34c416808..96ef8c8c770 100644
--- a/src/cmd/compile/internal/noder/doc.go
+++ b/src/cmd/compile/internal/noder/doc.go
@@ -16,22 +16,85 @@ sectionEnds = [10]uint32 . // defines section boundaries
elementEnds = []uint32 . // defines element boundaries
fingerprint = [8]byte . // sha256 fingerprint
-The payload has a structure as well. It is a series of sections, which
-contain elements of the same type. Go constructs are mapped onto
-(potentially multiple) elements. It is represented as below.
+The payload is a series of sections. Each section has a kind which determines
+its index in the series.
+SectionKind = Uint64 .
TODO(markfreeman): Update when we rename RelocFoo to SectionFoo.
-Payload = RelocString
- RelocMeta
- RelocPosBase
- RelocPkg
- RelocName
- RelocType
- RelocObj
- RelocObjExt
- RelocObjDict
- RelocBody
- .
+Payload = RelocString // TODO(markfreeman) Define.
+ RelocMeta
+ RelocPosBase // TODO(markfreeman) Define.
+ RelocPkg // TODO(markfreeman) Define.
+ RelocName // TODO(markfreeman) Define.
+ RelocType // TODO(markfreeman) Define.
+ RelocObj // TODO(markfreeman) Define.
+ RelocObjExt // TODO(markfreeman) Define.
+ RelocObjDict // TODO(markfreeman) Define.
+ RelocBody // TODO(markfreeman) Define.
+ .
+
+# Sections
+A section is a series of elements of a type determined by the section's kind.
+Go constructs are mapped onto (potentially multiple) elements. Elements are
+accessed using an index relative to the start of the section.
+
+// TODO(markfreeman): Rename to SectionIndex.
+RelIndex = Uint64 .
+
+## Meta Section
+The meta section provides fundamental information for a package. It contains
+exactly two elements — a public root and a private root.
+
+RelocMeta = PublicRoot
+ PrivateRoot // TODO(markfreeman): Define.
+ .
+
+The public root element identifies the package and provides references for all
+exported objects it contains.
+
+PublicRoot = Relocs
+ [ SyncPublic ] // TODO(markfreeman): Define.
+ PackageRef // TODO(markfreeman): Define.
+ [ HasInit ]
+ ObjectRefCount // TODO(markfreeman): Define.
+ { ObjectRef } // TODO(markfreeman): Define.
+ .
+HasInit = Bool . // Whether the package uses any initialization
+ // functions.
+
+# References
+A reference table precedes every element. Each entry in the table contains a
+section / index pair denoting the location of the referenced element.
+
+// TODO(markfreeman): Rename to RefTable.
+Relocs = [ SyncRelocs ] // TODO(markfreeman): Define.
+ RelocCount
+ { Reloc }
+ .
+// TODO(markfreeman): Rename to RefTableEntryCount.
+RelocCount = Uint64 .
+// TODO(markfreeman): Rename to RefTableEntry.
+Reloc = [ SyncReloc ] // TODO(markfreeman): Define.
+ SectionKind
+ RelIndex
+ .
+
+Elements encode references to other elements as an index in the reference
+table — not the location of the referenced element directly.
+
+// TODO(markfreeman): Rename to RefUse.
+UseReloc = [ SyncUseReloc ] // TODO(markfreeman): Define.
+ RelIndex
+ .
+
+# Primitives
+Primitive encoding is handled separately by the pkgbits package. Check there
+for definitions of the below productions.
+
+ * Bool
+ * Int64
+ * Uint64
+ * String
*/
package noder
--
GitLab