cmd/compile/internal/noder: begin a formal UIR grammar.

The UIR export data format can be reasonably expressed using EBNF.
The noder owns the definition of the export data format, so this
seems like a reasonable place to put this.

Change-Id: I0205ab29a3c5e57d670d7fd3164a8bd604ab8e59
Reviewed-on: https://go-review.googlesource.com/c/go/+/670616
Reviewed-by: Robert Griesemer <gri@google.com>
TryBot-Bypass: Mark Freeman <mark@golang.org>
Auto-Submit: Mark Freeman <mark@golang.org>

1 files changed, 37 insertions, 0 deletions

diff --git a/src/cmd/compile/internal/noder/doc.go b/src/cmd/compile/internal/noder/doc.go
new file mode 100644
index 0000000000..3c34c41680
--- /dev/null
+++ b/src/cmd/compile/internal/noder/doc.go
@@ -0,0 +1,37 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+The Unified IR (UIR) format is implicitly defined by the package noder.
+
+At the highest level, a package encoded in UIR follows the grammar below.
+
+File        = Header Payload fingerprint .
+Header      = version [ flags ] sectionEnds elementEnds .
+
+version     = uint32 .     // used for backward compatibility
+flags       = uint32 .     // feature flags used across versions
+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.
+
+TODO(markfreeman): Update when we rename RelocFoo to SectionFoo.
+Payload = RelocString
+          RelocMeta
+          RelocPosBase
+          RelocPkg
+          RelocName
+          RelocType
+          RelocObj
+          RelocObjExt
+          RelocObjDict
+          RelocBody
+          .
+*/
+
+package noder