github.com/kdevb0x/go@v0.0.0-20180115030120-39687051e9e7/src/cmd/internal/objabi/doc.go (about)

     1  // Copyright 2013 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  // NOTE: There are *three* independent implementations of this object
     6  // file format in the Go source tree:
     7  //
     8  //	- cmd/internal/goobj/read.go (used by cmd/addr2line, cmd/nm, cmd/objdump, cmd/pprof)
     9  //	- cmd/internal/obj/objfile.go (used by cmd/asm and cmd/compile)
    10  //	- cmd/link/internal/objfile.go (used by cmd/link)
    11  //
    12  // When changing the object file format, remember to change all three.
    13  
    14  // Originally, Go object files were Plan 9 object files, but no longer.
    15  // Now they are more like standard object files, in that each symbol is defined
    16  // by an associated memory image (bytes) and a list of relocations to apply
    17  // during linking. We do not (yet?) use a standard file format, however.
    18  // For now, the format is chosen to be as simple as possible to read and write.
    19  // It may change for reasons of efficiency, or we may even switch to a
    20  // standard file format if there are compelling benefits to doing so.
    21  // See golang.org/s/go13linker for more background.
    22  //
    23  // The file format is:
    24  //
    25  //	- magic header: "\x00\x00go19ld"
    26  //	- byte 1 - version number
    27  //	- sequence of strings giving dependencies (imported packages)
    28  //	- empty string (marks end of sequence)
    29  //	- sequence of symbol references used by the defined symbols
    30  //	- byte 0xff (marks end of sequence)
    31  //	- sequence of integer lengths:
    32  //		- total data length
    33  //		- total number of relocations
    34  //		- total number of pcdata
    35  //		- total number of automatics
    36  //		- total number of funcdata
    37  //		- total number of files
    38  //	- data, the content of the defined symbols
    39  //	- sequence of defined symbols
    40  //	- byte 0xff (marks end of sequence)
    41  //	- magic footer: "\xff\xffgo19ld"
    42  //
    43  // All integers are stored in a zigzag varint format.
    44  // See golang.org/s/go12symtab for a definition.
    45  //
    46  // Data blocks and strings are both stored as an integer
    47  // followed by that many bytes.
    48  //
    49  // A symbol reference is a string name followed by a version.
    50  //
    51  // A symbol points to other symbols using an index into the symbol
    52  // reference sequence. Index 0 corresponds to a nil symbol pointer.
    53  // In the symbol layout described below "symref index" stands for this
    54  // index.
    55  //
    56  // Each symbol is laid out as the following fields:
    57  //
    58  //	- byte 0xfe (sanity check for synchronization)
    59  //	- type [byte]
    60  //	- name & version [symref index]
    61  //	- flags [int]
    62  //		1<<0 dupok
    63  //		1<<1 local
    64  //		1<<2 add to typelink table
    65  //	- size [int]
    66  //	- gotype [symref index]
    67  //	- p [data block]
    68  //	- nr [int]
    69  //	- r [nr relocations, sorted by off]
    70  //
    71  // If type == STEXT, there are a few more fields:
    72  //
    73  //	- args [int]
    74  //	- locals [int]
    75  //	- nosplit [int]
    76  //	- flags [int]
    77  //		1<<0 leaf
    78  //		1<<1 C function
    79  //		1<<2 function may call reflect.Type.Method
    80  //		1<<3 function compiled with -shared
    81  //	- nlocal [int]
    82  //	- local [nlocal automatics]
    83  //	- pcln [pcln table]
    84  //
    85  // Each relocation has the encoding:
    86  //
    87  //	- off [int]
    88  //	- siz [int]
    89  //	- type [int]
    90  //	- add [int]
    91  //	- sym [symref index]
    92  //
    93  // Each local has the encoding:
    94  //
    95  //	- asym [symref index]
    96  //	- offset [int]
    97  //	- type [int]
    98  //	- gotype [symref index]
    99  //
   100  // The pcln table has the encoding:
   101  //
   102  //	- pcsp [data block]
   103  //	- pcfile [data block]
   104  //	- pcline [data block]
   105  //	- pcinline [data block]
   106  //	- npcdata [int]
   107  //	- pcdata [npcdata data blocks]
   108  //	- nfuncdata [int]
   109  //	- funcdata [nfuncdata symref index]
   110  //	- funcdatasym [nfuncdata ints]
   111  //	- nfile [int]
   112  //	- file [nfile symref index]
   113  //	- ninlinedcall [int]
   114  //	- inlinedcall [ninlinedcall int symref int symref]
   115  //
   116  // The file layout and meaning of type integers are architecture-independent.
   117  //
   118  // TODO(rsc): The file format is good for a first pass but needs work.
   119  //	- There are SymID in the object file that should really just be strings.
   120  package objabi