// 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 is a series of sections. Each section has a kind which determines
its index in the series.

SectionKind = Uint64 .
Payload     = SectionString  // TODO(markfreeman) Define.
              SectionMeta
              SectionPosBase // TODO(markfreeman) Define.
              SectionPkg     // TODO(markfreeman) Define.
              SectionName    // TODO(markfreeman) Define.
              SectionType    // TODO(markfreeman) Define.
              SectionObj     // TODO(markfreeman) Define.
              SectionObjExt  // TODO(markfreeman) Define.
              SectionObjDict // TODO(markfreeman) Define.
              SectionBody    // 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.

SectionMeta = 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