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>

diff --git a/src/cmd/compile/internal/noder/doc.go b/src/cmd/compile/internal/noder/doc.go
index 3c34c416808b2b6f3b969e29070872b3a118442f..96ef8c8c77041225fb4df71e7b282b8dcc79b8d4 100644 (file)
--- 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