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