+If a package has any .s files, then go build will direct
+the compiler to emit a special header called go_asm.h,
+which the .s files can then #include.
+The file contains symbolic #define constants for the
+offsets of Go struct fields, the sizes of Go struct types, and most
+Go const declarations defined in the current package.
+Go assembly should avoid making assumptions about the layout of Go
+types and instead use these constants.
+This improves the readability of assembly code, and keeps it robust to
+changes in data layout either in the Go type definitions or in the
+layout rules used by the Go compiler.
+
+Constants are of the form const_name.
+For example, given the Go declaration const bufSize =
+1024, assembly code can refer to the value of this constant
+as const_bufSize.
+
+Field offsets are of the form type_field.
+Struct sizes are of the form type__size.
+For example, consider the following Go definition:
+
+type reader struct {
+ buf [bufSize]byte
+ r int
+}
+
+
+
+Assembly can refer to the size of this struct
+as reader__size and the offsets of the two fields
+as reader_buf and reader_r.
+Hence, if register R1 contains a pointer to
+a reader, assembly can reference the r field
+as reader_r(R1).
+
+If any of these #define names are ambiguous (for example,
+a struct with a _size field), #include
+"go_asm.h" will fail with a "redefinition of macro" error.
+
@@ -615,21 +666,15 @@ Here follow some descriptions of key Go-specific details for the supported archi
The runtime pointer to the g structure is maintained
through the value of an otherwise unused (as far as Go is concerned) register in the MMU.
-An OS-dependent macro get_tls is defined for the assembler if the source is
-in the runtime package and includes a special header, go_tls.h:
+In the runtime package, assembly code can include go_tls.h, which defines
+an OS- and architecture-dependent macro get_tls for accessing this register.
+The get_tls macro takes one argument, which is the register to load the
+g pointer into.
-#include "go_tls.h" --
-Within the runtime, the get_tls macro loads its argument register
-with a pointer to the g pointer, and the g struct
-contains the m pointer.
-There's another special header containing the offsets for each
-element of g, called go_asm.h.
-The sequence to load g and m using CX looks like this:
+For example, the sequence to load g and m
+using CX looks like this:
@@ -642,8 +687,7 @@ MOVL g_m(AX), BX // Move g.m into BX.
-Note: The code above works only in the runtime package, while go_tls.h also
-applies to arm, amd64 and amd64p32, and go_asm.h applies to all architectures.
+The get_tls macro is also defined on amd64.
diff --git a/doc/go1.16.html b/doc/go1.16.html
index d7714888f2..3a45940479 100644
--- a/doc/go1.16.html
+++ b/doc/go1.16.html
@@ -275,7 +275,7 @@ Do not send CLs removing the interior tags from such phrases.
When the -export flag is specified, the BuildID
field is now set to the build ID of the compiled package. This is equivalent
to running go tool buildid on
- go list -exported -f {{.Export},
+ go list -exported -f {{.Export}},
but without the extra step.
The new io/fs package
- defines an abstraction for read-only trees of files,
- the fs.FS interface,
- and the standard library packages have
- been adapted to make use of the interface as appropriate.
+ defines the fs.FS interface,
+ an abstraction for read-only trees of files.
+ The standard library packages have been adapted to make use
+ of the interface as appropriate.
@@ -499,6 +499,44 @@ func TestFoo(t *testing.T) { implementations.
+
+ The io/ioutil package has
+ turned out to be a poorly defined and hard to understand collection
+ of things. All functionality provided by the package has been moved
+ to other packages. The io/ioutil package remains and
+ will continue to work as before, but we encourage new code to use
+ the new definitions in the io and
+ os packages.
+
+ Here is a list of the new locations of the names exported
+ by io/ioutil:
+
Discard
+ => io.DiscardNopCloser
+ => io.NopCloserReadAll
+ => io.ReadAllReadDir
+ => os.ReadDir
+ (note: returns a slice of
+ os.DirEntry
+ rather than a slice of
+ fs.FileInfo)
+ ReadFile
+ => os.ReadFileTempDir
+ => os.MkdirTempTempFile
+ => os.CreateTempWriteFile
+ => os.WriteFilecrypto/x509 package is now more
+ efficient in how it stores its copy of the system cert pool.
+ Programs that use only a small number of roots will use around a
+ half megabyte less memory.
+
+
@@ -685,6 +731,37 @@ func TestFoo(t *testing.T) {
+
+ The Package
+ struct has new fields that report information
+ about //go:embed directives in the package:
+ EmbedPatterns,
+ EmbedPatternPos,
+ TestEmbedPatterns,
+ TestEmbedPatternPos,
+ XTestEmbedPatterns,
+ XTestEmbedPatternPos.
+
+ The Package field
+ IgnoredGoFiles
+ will no longer include files that start with "_" or ".",
+ as those files are always ignored.
+ IgnoredGoFiles is for files ignored because of
+ build constraints.
+
+ The new Package
+ field IgnoredOtherFiles
+ has a list of non-Go files ignored because of build constraints.
+
@@ -703,6 +780,15 @@ func TestFoo(t *testing.T) {
The package now defines a
ReadSeekCloser interface.
+ The package now defines
+ Discard,
+ NopCloser, and
+ ReadAll,
+ to be used instead of the same names in the
+ io/ioutil package.
+
errFinished when the process has
already finished.
+
+
+ The package defines a new type
+ DirEntry
+ as an alias for fs.DirEntry.
+ The new ReadDir
+ function and the new
+ File.ReadDir
+ method can be used to read the contents of a directory into a
+ slice of DirEntry.
+ The File.Readdir
+ method (note the lower case d in dir)
+ still exists, returning a slice of
+ FileInfo, but for
+ most programs it will be more efficient to switch to
+ File.ReadDir.
+
+ The package now defines
+ CreateTemp,
+ MkdirTemp,
+ ReadFile, and
+ WriteFile,
+ to be used instead of functions defined in the
+ io/ioutil package.
+
+ The types FileInfo,
+ FileMode, and
+ PathError
+ are now aliases for types of the same name in the
+ io/fs package.
+ Function signatures in the os
+ package have been updated to refer to the names in the
+ io/fs package.
+ This should not affect any existing code.
+
+ The new DirFS function
+ provides an implementation of
+ fs.FS backed by a tree
+ of operating system files.
+
The new function
- WalkDir
+ WalkDir
is similar to
- Walk,
+ Walk,
but is typically more efficient.
The function passed to WalkDir receives a
fs.DirEntry
@@ -975,6 +1107,25 @@ func TestFoo(t *testing.T) {
+ The new
+ ErrReader
+ function returns an
+ io.Reader that always
+ returns an error.
+
+ The new
+ TestReader
+ function tests that an io.Reader
+ behaves correctly.
+