doc: update /doc/asm compiler output example
The compiler output shown in the doc is now quite old
(most of the changes happened in Go 1.5).
Update it to be more like what users will actually see.
Also explain how to get literal machine code again.
Prompted by #30968.
Change-Id: I0ce139c3fe299ccc43e85b6aca81c6e0aac1a2df
Reviewed-on: https://go-review.googlesource.com/c/go/+/175757
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
diff --git a/doc/asm.html b/doc/asm.html
index debb1e2..77defdb 100644
--- a/doc/asm.html
+++ b/doc/asm.html
@@ -57,59 +57,66 @@
println(3)
}
$ GOOS=linux GOARCH=amd64 go tool compile -S x.go # or: go build -gcflags -S x.go
-
---- prog list "main" ---
-0000 (x.go:3) TEXT main+0(SB),$8-0
-0001 (x.go:3) FUNCDATA $0,gcargs·0+0(SB)
-0002 (x.go:3) FUNCDATA $1,gclocals·0+0(SB)
-0003 (x.go:4) MOVQ $3,(SP)
-0004 (x.go:4) PCDATA $0,$8
-0005 (x.go:4) CALL ,runtime.printint+0(SB)
-0006 (x.go:4) PCDATA $0,$-1
-0007 (x.go:4) PCDATA $0,$0
-0008 (x.go:4) CALL ,runtime.printnl+0(SB)
-0009 (x.go:4) PCDATA $0,$-1
-0010 (x.go:5) RET ,
+"".main STEXT size=74 args=0x0 locals=0x10
+ 0x0000 00000 (x.go:3) TEXT "".main(SB), $16-0
+ 0x0000 00000 (x.go:3) MOVQ (TLS), CX
+ 0x0009 00009 (x.go:3) CMPQ SP, 16(CX)
+ 0x000d 00013 (x.go:3) JLS 67
+ 0x000f 00015 (x.go:3) SUBQ $16, SP
+ 0x0013 00019 (x.go:3) MOVQ BP, 8(SP)
+ 0x0018 00024 (x.go:3) LEAQ 8(SP), BP
+ 0x001d 00029 (x.go:3) FUNCDATA $0, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)
+ 0x001d 00029 (x.go:3) FUNCDATA $1, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)
+ 0x001d 00029 (x.go:3) FUNCDATA $2, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)
+ 0x001d 00029 (x.go:4) PCDATA $0, $0
+ 0x001d 00029 (x.go:4) PCDATA $1, $0
+ 0x001d 00029 (x.go:4) CALL runtime.printlock(SB)
+ 0x0022 00034 (x.go:4) MOVQ $3, (SP)
+ 0x002a 00042 (x.go:4) CALL runtime.printint(SB)
+ 0x002f 00047 (x.go:4) CALL runtime.printnl(SB)
+ 0x0034 00052 (x.go:4) CALL runtime.printunlock(SB)
+ 0x0039 00057 (x.go:5) MOVQ 8(SP), BP
+ 0x003e 00062 (x.go:5) ADDQ $16, SP
+ 0x0042 00066 (x.go:5) RET
+ 0x0043 00067 (x.go:5) NOP
+ 0x0043 00067 (x.go:3) PCDATA $1, $-1
+ 0x0043 00067 (x.go:3) PCDATA $0, $-1
+ 0x0043 00067 (x.go:3) CALL runtime.morestack_noctxt(SB)
+ 0x0048 00072 (x.go:3) JMP 0
...
</pre>
<p>
The <code>FUNCDATA</code> and <code>PCDATA</code> directives contain information
for use by the garbage collector; they are introduced by the compiler.
-</p>
-
-<!-- Commenting out because the feature is gone but it's popular and may come back.
+</p>
<p>
-To see what gets put in the binary after linking, add the <code>-a</code> flag to the linker:
+To see what gets put in the binary after linking, use <code>go tool objdump</code>:
</p>
<pre>
-$ go tool 6l -a x.6 # or: go build -ldflags -a x.go
-codeblk [0x2000,0x1d059) at offset 0x1000
-002000 main.main | (3) TEXT main.main+0(SB),$8
-002000 65488b0c25a0080000 | (3) MOVQ 2208(GS),CX
-002009 483b21 | (3) CMPQ SP,(CX)
-00200c 7707 | (3) JHI ,2015
-00200e e83da20100 | (3) CALL ,1c250+runtime.morestack00
-002013 ebeb | (3) JMP ,2000
-002015 4883ec08 | (3) SUBQ $8,SP
-002019 | (3) FUNCDATA $0,main.gcargs·0+0(SB)
-002019 | (3) FUNCDATA $1,main.gclocals·0+0(SB)
-002019 48c7042403000000 | (4) MOVQ $3,(SP)
-002021 | (4) PCDATA $0,$8
-002021 e8aad20000 | (4) CALL ,f2d0+runtime.printint
-002026 | (4) PCDATA $0,$-1
-002026 | (4) PCDATA $0,$0
-002026 e865d40000 | (4) CALL ,f490+runtime.printnl
-00202b | (4) PCDATA $0,$-1
-00202b 4883c408 | (5) ADDQ $8,SP
-00202f c3 | (5) RET ,
-...
+$ go build -o x.exe x.go
+$ go tool objdump -s main.main x.exe
+TEXT main.main(SB) /tmp/x.go
+ x.go:3 0x10501c0 65488b0c2530000000 MOVQ GS:0x30, CX
+ x.go:3 0x10501c9 483b6110 CMPQ 0x10(CX), SP
+ x.go:3 0x10501cd 7634 JBE 0x1050203
+ x.go:3 0x10501cf 4883ec10 SUBQ $0x10, SP
+ x.go:3 0x10501d3 48896c2408 MOVQ BP, 0x8(SP)
+ x.go:3 0x10501d8 488d6c2408 LEAQ 0x8(SP), BP
+ x.go:4 0x10501dd e86e45fdff CALL runtime.printlock(SB)
+ x.go:4 0x10501e2 48c7042403000000 MOVQ $0x3, 0(SP)
+ x.go:4 0x10501ea e8e14cfdff CALL runtime.printint(SB)
+ x.go:4 0x10501ef e8ec47fdff CALL runtime.printnl(SB)
+ x.go:4 0x10501f4 e8d745fdff CALL runtime.printunlock(SB)
+ x.go:5 0x10501f9 488b6c2408 MOVQ 0x8(SP), BP
+ x.go:5 0x10501fe 4883c410 ADDQ $0x10, SP
+ x.go:5 0x1050202 c3 RET
+ x.go:3 0x1050203 e83882ffff CALL runtime.morestack_noctxt(SB)
+ x.go:3 0x1050208 ebb6 JMP main.main(SB)
</pre>
--->
-
<h3 id="constants">Constants</h3>
<p>
@@ -266,7 +273,7 @@
</p>
<p>
-In Go object files and binaries, the full name of a symbol is the
+In Go object files and binaries, the full name of a symbol is the
package path followed by a period and the symbol name:
<code>fmt.Printf</code> or <code>math/rand.Int</code>.
Because the assembler's parser treats period and slash as punctuation,
@@ -485,7 +492,7 @@
At the start of the function, the arguments are assumed
to be initialized but the results are assumed uninitialized.
If the results will hold live pointers during a call instruction,
-the function should start by zeroing the results and then
+the function should start by zeroing the results and then
executing the pseudo-instruction <code>GO_RESULTS_INITIALIZED</code>.
This instruction records that the results are now initialized
and should be scanned during stack movement and garbage collection.
@@ -503,7 +510,7 @@
The pointer information can also be omitted if the
function contains no call instructions.
Otherwise, the local stack frame must not contain pointers,
-and the assembly must confirm this fact by executing the
+and the assembly must confirm this fact by executing the
pseudo-instruction <code>NO_LOCAL_POINTERS</code>.
Because stack resizing is implemented by moving the stack,
the stack pointer may change during any function call:
