cmd/internal/objabi: delete doc.go
cmd/internal/objabi/doc.go has comments decribing the (old)
object file format. But cmd/internal/objabi has nothing to do
with object files, and never did. Delete.
Move some comment to cmd/internal/goobj, where the (new) object
file format is actually defined, and update to reflect the
current status.
Change-Id: Ied96089df4be35e5d259a572ed60ee00f2cd0d1d
Reviewed-on: https://go-review.googlesource.com/c/go/+/249958
Reviewed-by: Than McIntosh <thanm@google.com>
diff --git a/src/cmd/internal/goobj/objfile.go b/src/cmd/internal/goobj/objfile.go
index 5d4a253..8ec7c48 100644
--- a/src/cmd/internal/goobj/objfile.go
+++ b/src/cmd/internal/goobj/objfile.go
@@ -2,7 +2,19 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Go new object file format, reading and writing.
+// This package defines the Go object file format, and provide "low-level" functions
+// for reading and writing object files.
+
+// The object file is understood by the compiler, assembler, linker, and tools. They
+// have "high level" code that operates on object files, handling application-specific
+// logics, and use this package for the actual reading and writing. Specifically, the
+// code below:
+//
+// - cmd/internal/obj/objfile.go (used by cmd/asm and cmd/compile)
+// - cmd/internal/objfile/goobj.go (used cmd/nm, cmd/objdump)
+// - cmd/link/internal/loader package (used by cmd/link)
+//
+// If the object file format changes, they may (or may not) need to change.
package goobj
diff --git a/src/cmd/internal/objabi/doc.go b/src/cmd/internal/objabi/doc.go
deleted file mode 100644
index 08e922b..0000000
--- a/src/cmd/internal/objabi/doc.go
+++ /dev/null
@@ -1,122 +0,0 @@
-// Copyright 2013 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.
-
-// NOTE: There are *three* independent implementations of this object
-// file format in the Go source tree:
-//
-// - cmd/internal/goobj/read.go (used by cmd/addr2line, cmd/nm, cmd/objdump, cmd/pprof)
-// - cmd/internal/obj/objfile.go (used by cmd/asm and cmd/compile)
-// - cmd/link/internal/objfile.go (used by cmd/link)
-//
-// When changing the object file format, remember to change all three.
-
-// Originally, Go object files were Plan 9 object files, but no longer.
-// Now they are more like standard object files, in that each symbol is defined
-// by an associated memory image (bytes) and a list of relocations to apply
-// during linking. We do not (yet?) use a standard file format, however.
-// For now, the format is chosen to be as simple as possible to read and write.
-// It may change for reasons of efficiency, or we may even switch to a
-// standard file format if there are compelling benefits to doing so.
-// See golang.org/s/go13linker for more background.
-//
-// The file format is:
-//
-// - magic header: "\x00go114ld"
-// - byte 1 - version number
-// - sequence of strings giving dependencies (imported packages)
-// - empty string (marks end of sequence)
-// - number of entries in the following sequence
-// - sequence of filename strings to generate debug information
-// - sequence of symbol references used by the defined symbols
-// - byte 0xff (marks end of sequence)
-// - sequence of integer lengths:
-// - total data length
-// - total number of relocations
-// - total number of pcdata
-// - total number of automatics
-// - total number of funcdata
-// - total number of files
-// - data, the content of the defined symbols
-// - sequence of defined symbols
-// - byte 0xff (marks end of sequence)
-// - magic footer: "\xffgo114ld"
-//
-// All integers are stored in a zigzag varint format.
-// See golang.org/s/go12symtab for a definition.
-//
-// Data blocks and strings are both stored as an integer
-// followed by that many bytes.
-//
-// A symbol reference is a string name followed by an ABI or -1 for static.
-//
-// A symbol points to other symbols using an index into the symbol
-// reference sequence. Index 0 corresponds to a nil symbol pointer.
-// In the symbol layout described below "symref index" stands for this
-// index.
-//
-// Each symbol is laid out as the following fields:
-//
-// - byte 0xfe (sanity check for synchronization)
-// - type [byte]
-// - name & ABI [symref index]
-// - flags [int]
-// 1<<0 dupok
-// 1<<1 local
-// 1<<2 add to typelink table
-// - size [int]
-// - gotype [symref index]
-// - p [data block]
-// - nr [int]
-// - r [nr relocations, sorted by off]
-//
-// If type == STEXT, there are a few more fields:
-//
-// - args [int]
-// - locals [int]
-// - nosplit [int]
-// - flags [int]
-// 1<<0 leaf
-// 1<<1 C function
-// 1<<2 function may call reflect.Type.Method
-// 1<<3 function compiled with -shared
-// - nlocal [int]
-// - local [nlocal automatics]
-// - pcln [pcln table]
-//
-// Each relocation has the encoding:
-//
-// - off [int]
-// - siz [int]
-// - type [int]
-// - add [int]
-// - sym [symref index]
-//
-// Each local has the encoding:
-//
-// - asym [symref index]
-// - offset [int]
-// - type [int]
-// - gotype [symref index]
-//
-// The pcln table has the encoding:
-//
-// - pcsp [data block]
-// - pcfile [data block]
-// - pcline [data block]
-// - pcinline [data block]
-// - npcdata [int]
-// - pcdata [npcdata data blocks]
-// - nfuncdata [int]
-// - funcdata [nfuncdata symref index]
-// - funcdatasym [nfuncdata ints]
-// - nfile [int]
-// - file [nfile symref index]
-// - ninlinedcall [int]
-// - inlinedcall [ninlinedcall int symref int symref]
-//
-// The file layout and meaning of type integers are architecture-independent.
-//
-// TODO(rsc): The file format is good for a first pass but needs work.
-// - There are SymID in the object file that should really just be strings.
-package objabi
