doc.go

     1  // Copyright 2025 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  The Unified IR (UIR) format is implicitly defined by the package noder.
     7  
     8  At the highest level, a package encoded in UIR follows the grammar below.
     9  
    10  File        = Header Payload fingerprint .
    11  Header      = version [ flags ] sectionEnds elementEnds .
    12  
    13  version     = uint32 .     // used for backward compatibility
    14  flags       = uint32 .     // feature flags used across versions
    15  sectionEnds = [10]uint32 . // defines section boundaries
    16  elementEnds = []uint32 .   // defines element boundaries
    17  fingerprint = [8]byte .    // sha256 fingerprint
    18  
    19  The payload is a series of sections. Each section has a kind which determines
    20  its index in the series.
    21  
    22  SectionKind = Uint64 .
    23  TODO(markfreeman): Update when we rename RelocFoo to SectionFoo.
    24  Payload     = RelocString  // TODO(markfreeman) Define.
    25                RelocMeta
    26                RelocPosBase // TODO(markfreeman) Define.
    27                RelocPkg     // TODO(markfreeman) Define.
    28                RelocName    // TODO(markfreeman) Define.
    29                RelocType    // TODO(markfreeman) Define.
    30                RelocObj     // TODO(markfreeman) Define.
    31                RelocObjExt  // TODO(markfreeman) Define.
    32                RelocObjDict // TODO(markfreeman) Define.
    33                RelocBody    // TODO(markfreeman) Define.
    34                .
    35  
    36  # Sections
    37  A section is a series of elements of a type determined by the section's kind.
    38  Go constructs are mapped onto (potentially multiple) elements. Elements are
    39  accessed using an index relative to the start of the section.
    40  
    41  // TODO(markfreeman): Rename to SectionIndex.
    42  RelIndex = Uint64 .
    43  
    44  ## Meta Section
    45  The meta section provides fundamental information for a package. It contains
    46  exactly two elements — a public root and a private root.
    47  
    48  RelocMeta  = PublicRoot
    49               PrivateRoot     // TODO(markfreeman): Define.
    50               .
    51  
    52  The public root element identifies the package and provides references for all
    53  exported objects it contains.
    54  
    55  PublicRoot = Relocs
    56               [ SyncPublic ] // TODO(markfreeman): Define.
    57               PackageRef     // TODO(markfreeman): Define.
    58               [ HasInit ]
    59               ObjectRefCount // TODO(markfreeman): Define.
    60               { ObjectRef }  // TODO(markfreeman): Define.
    61               .
    62  HasInit    = Bool .         // Whether the package uses any initialization
    63                              // functions.
    64  
    65  # References
    66  A reference table precedes every element. Each entry in the table contains a
    67  section / index pair denoting the location of the referenced element.
    68  
    69  // TODO(markfreeman): Rename to RefTable.
    70  Relocs     = [ SyncRelocs ]   // TODO(markfreeman): Define.
    71               RelocCount
    72               { Reloc }
    73               .
    74  // TODO(markfreeman): Rename to RefTableEntryCount.
    75  RelocCount = Uint64 .
    76  // TODO(markfreeman): Rename to RefTableEntry.
    77  Reloc      = [ SyncReloc ]    // TODO(markfreeman): Define.
    78               SectionKind
    79               RelIndex
    80               .
    81  
    82  Elements encode references to other elements as an index in the reference
    83  table — not the location of the referenced element directly.
    84  
    85  // TODO(markfreeman): Rename to RefUse.
    86  UseReloc   = [ SyncUseReloc ] // TODO(markfreeman): Define.
    87               RelIndex
    88               .
    89  
    90  # Primitives
    91  Primitive encoding is handled separately by the pkgbits package. Check there
    92  for definitions of the below productions.
    93  
    94      * Bool
    95      * Int64
    96      * Uint64
    97      * String
    98  */
    99  
   100  package noder
   101
View as plain text