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
     9  below.
    10  
    11      File        = Header Payload fingerprint .
    12      Header      = version [ flags ] sectionEnds elementEnds .
    13  
    14      version     = uint32 .     // used for backward compatibility
    15      flags       = uint32 .     // feature flags used across versions
    16      sectionEnds = [10]uint32 . // defines section boundaries
    17      elementEnds = []uint32 .   // defines element boundaries
    18      fingerprint = [8]byte .    // sha256 fingerprint
    19  
    20  The payload is a series of sections. Each section has a kind which
    21  determines its index in the series.
    22  
    23      SectionKind = Uint64 .
    24      Payload     = SectionString
    25                    SectionMeta
    26                    SectionPosBase
    27                    SectionPkg
    28                    SectionName
    29                    SectionType
    30                    SectionObj
    31                    SectionObjExt  // TODO(markfreeman) Define.
    32                    SectionObjDict // TODO(markfreeman) Define.
    33                    SectionBody    // TODO(markfreeman) Define.
    34                    .
    35  
    36  # Sections
    37  A section is a series of elements of a type determined by the section's
    38  kind. Go constructs are mapped onto one or more elements with possibly
    39  different types; in that case, the elements are in different sections.
    40  
    41  Elements are accessed using an element index relative to the start of
    42  the section.
    43  
    44      RelElemIdx = Uint64 .
    45  
    46  ## String Section
    47  String values are stored as elements in the string section. Elements
    48  outside the string section access string values by reference.
    49  
    50      SectionString = { String } .
    51  
    52  Note that despite being an element, a string does not begin with a
    53  reference table.
    54  
    55  ## Meta Section
    56  The meta section provides fundamental information for a package. It
    57  contains exactly two elements — a public root and a private root.
    58  
    59      SectionMeta = PublicRoot
    60                    PrivateRoot     // TODO(markfreeman): Define.
    61                    .
    62  
    63  The public root element identifies the package and provides references
    64  for all exported objects it contains.
    65  
    66      PublicRoot  = RefTable
    67                    [ Sync ]
    68                    PkgRef
    69                    [ HasInit ]
    70                    ObjectRefCount // TODO(markfreeman): Define.
    71                    { ObjectRef }  // TODO(markfreeman): Define.
    72                    .
    73      HasInit     = Bool .         // Whether the package uses any
    74                                   // initialization functions.
    75  
    76  ## PosBase Section
    77  This section provides position information. It is a series of PosBase
    78  elements.
    79  
    80      SectionPosBase = { PosBase } .
    81  
    82  A base is either a file base or line base (produced by a line
    83  directive). Every base has a position, line, and column; these are
    84  constant for file bases and hence not encoded.
    85  
    86      PosBase = RefTable
    87                [ Sync ]
    88                StringRef       // the (absolute) file name for the base
    89                Bool            // true if a file base, else a line base
    90                // The below is ommitted for file bases.
    91                [ Pos
    92                  Uint64        // line
    93                  Uint64 ]      // column
    94                .
    95  
    96  A source position Pos represents a file-absolute (line, column) pair
    97  and a PosBase indicating the position Pos is relative to. Positions
    98  without a PosBase have no line or column.
    99  
   100      Pos     = [ Sync ]
   101                Bool             // true if the position has a base
   102                // The below is ommitted if the position has no base.
   103                [ Ref[PosBase]
   104                  Uint64         // line
   105                  Uint64 ]       // column
   106                .
   107  
   108  ## Package Section
   109  The package section holds package information. It is a series of Pkg
   110  elements.
   111  
   112      SectionPkg = { Pkg } .
   113  
   114  A Pkg element contains a (path, name) pair and a series of imported
   115  packages. The below package paths have special meaning.
   116  
   117      +--------------+-----------------------------------+
   118      | package path |             indicates             |
   119      +--------------+-----------------------------------+
   120      | ""           | the current package               |
   121      | "builtin"    | the fake builtin package          |
   122      | "unsafe"     | the compiler-known unsafe package |
   123      +--------------+-----------------------------------+
   124  
   125      Pkg        = RefTable
   126                   [ Sync ]
   127                   StringRef      // path
   128                   // The below is ommitted for the special package paths
   129                   // "builtin" and "unsafe".
   130                   [ StringRef    // name
   131                     Imports ]
   132                   .
   133      Imports    = Uint64         // the number of declared imports
   134                   { PkgRef }     // references to declared imports
   135                   .
   136  
   137  Note, a PkgRef is *not* equivalent to Ref[Pkg] due to an extra marker.
   138  
   139      PkgRef     = [ Sync ]
   140                   Ref[Pkg]
   141                   .
   142  
   143  ## Type Section
   144  The type section is a series of type definition elements.
   145  
   146      SectionType = { TypeDef } .
   147  
   148  A type definition can be in one of several formats, which are identified
   149  by their TypeSpec code.
   150  
   151      TypeDef     = RefTable
   152                    [ Sync ]
   153                    [ Sync ]
   154                    Uint64            // denotes which TypeSpec to use
   155                    TypeSpec
   156                    .
   157  
   158      TypeSpec    = TypeSpecBasic     // TODO(markfreeman): Define.
   159                  | TypeSpecNamed     // TODO(markfreeman): Define.
   160                  | TypeSpecPointer   // TODO(markfreeman): Define.
   161                  | TypeSpecSlice     // TODO(markfreeman): Define.
   162                  | TypeSpecArray     // TODO(markfreeman): Define.
   163                  | TypeSpecChan      // TODO(markfreeman): Define.
   164                  | TypeSpecMap       // TODO(markfreeman): Define.
   165                  | TypeSpecSignature // TODO(markfreeman): Define.
   166                  | TypeSpecStruct    // TODO(markfreeman): Define.
   167                  | TypeSpecInterface // TODO(markfreeman): Define.
   168                  | TypeSpecUnion     // TODO(markfreeman): Define.
   169                  | TypeSpecTypeParam // TODO(markfreeman): Define.
   170                    .
   171  
   172  // TODO(markfreeman): Document the reader dictionary once we understand it more.
   173  To use a type elsewhere, a TypeUse is encoded.
   174  
   175      TypeUse     = [ Sync ]
   176                    Bool              // whether it is a derived type
   177                    [ Uint64 ]        // if derived, an index into the reader dictionary
   178                    [ Ref[TypeDef] ]  // else, a reference to the type
   179                    .
   180  
   181  ## Object Sections
   182  Information about an object (e.g. variable, function, type name, etc.)
   183  is split into multiple elements in different sections. Those elements
   184  have the same section-relative element index.
   185  
   186  ### Name Section
   187  The name section holds a series of names.
   188  
   189      SectionName = { Name } .
   190  
   191  Names are elements holding qualified identifiers and type information
   192  for objects.
   193  
   194      Name        = RefTable
   195                    [ Sync ]
   196                    [ Sync ]
   197                    PkgRef    // the object's package
   198                    StringRef // the object's package-local name
   199                    [ Sync ]
   200                    Uint64    // the object's type (e.g. Var, Func, etc.)
   201                    .
   202  
   203  ### Definition Section
   204  The definition section holds definitions for objects defined by the target
   205  package; it does not contain definitions for imported objects.
   206  
   207      SectionObj = { ObjectDef } .
   208  
   209  Object definitions can be in one of several formats. To determine the correct
   210  format, the name section must be referenced; it contains a code indicating
   211  the object's type.
   212  
   213      ObjectDef = RefTable
   214                  [ Sync ]
   215                  ObjectSpec
   216                  .
   217  
   218      ObjectSpec = ObjectSpecConst     // TODO(markfreeman) Define.
   219                 | ObjectSpecFunc      // TODO(markfreeman) Define.
   220                 | ObjectSpecAlias     // TODO(markfreeman) Define.
   221                 | ObjectSpecNamedType // TODO(markfreeman) Define.
   222                 | ObjectSpecVar       // TODO(markfreeman) Define.
   223                   .
   224  
   225  To use an object definition elsewhere, an ObjectUse is encoded.
   226  
   227      ObjectUse  = [ Sync ]
   228                   [ Bool ]
   229                   Ref[ObjectDef]
   230                   Uint64              // the number of type arguments
   231                   { TypeUse }         // references to the type arguments
   232                   .
   233  
   234  # References
   235  A reference table precedes every element. Each entry in the table
   236  contains a (section, index) pair denoting the location of the
   237  referenced element.
   238  
   239      RefTable      = [ Sync ]
   240                      Uint64            // the number of table entries
   241                      { RefTableEntry }
   242                      .
   243      RefTableEntry = [ Sync ]
   244                      SectionKind
   245                      RelElemIdx
   246                      .
   247  
   248  Elements encode references to other elements as an index in the
   249  reference table — not the location of the referenced element directly.
   250  
   251      RefTableIdx   = Uint64 .
   252  
   253  To do this, the Ref[T] primitive is used as below; note that this is
   254  the same shape as provided by package pkgbits, just with new
   255  interpretation applied.
   256  
   257      Ref[T]        = [ Sync ]
   258                      RefTableIdx       // the Uint64
   259                      .
   260  
   261  # Primitives
   262  Primitive encoding is handled separately by the pkgbits package. Check
   263  there for definitions of the below productions.
   264  
   265      * Bool
   266      * Int64
   267      * Uint64
   268      * String
   269      * Ref[T]
   270      * Sync
   271  */
   272  
   273  package noder
   274
View as plain text