2 "Title": "A Quick Guide to Go's Assembler",
6 <h2 id="introduction">A Quick Guide to Go's Assembler</h2>
9 This document is a quick outline of the unusual form of assembly language used by the <code>gc</code> Go compiler.
10 The document is not comprehensive.
14 The assembler is based on the input style of the Plan 9 assemblers, which is documented in detail
15 <a href="https://9p.io/sys/doc/asm.html">elsewhere</a>.
16 If you plan to write assembly language, you should read that document although much of it is Plan 9-specific.
17 The current document provides a summary of the syntax and the differences with
18 what is explained in that document, and
19 describes the peculiarities that apply when writing assembly code to interact with Go.
23 The most important thing to know about Go's assembler is that it is not a direct representation of the underlying machine.
24 Some of the details map precisely to the machine, but some do not.
25 This is because the compiler suite (see
26 <a href="https://9p.io/sys/doc/compiler.html">this description</a>)
27 needs no assembler pass in the usual pipeline.
28 Instead, the compiler operates on a kind of semi-abstract instruction set,
29 and instruction selection occurs partly after code generation.
30 The assembler works on the semi-abstract form, so
31 when you see an instruction like <code>MOV</code>
32 what the toolchain actually generates for that operation might
33 not be a move instruction at all, perhaps a clear or load.
34 Or it might correspond exactly to the machine instruction with that name.
35 In general, machine-specific operations tend to appear as themselves, while more general concepts like
36 memory move and subroutine call and return are more abstract.
37 The details vary with architecture, and we apologize for the imprecision; the situation is not well-defined.
41 The assembler program is a way to parse a description of that
42 semi-abstract instruction set and turn it into instructions to be
44 If you want to see what the instructions look like in assembly for a given architecture, say amd64, there
45 are many examples in the sources of the standard library, in packages such as
46 <a href="/pkg/runtime/"><code>runtime</code></a> and
47 <a href="/pkg/math/big/"><code>math/big</code></a>.
48 You can also examine what the compiler emits as assembly code
49 (the actual output may differ from what you see here):
59 $ GOOS=linux GOARCH=amd64 go tool compile -S x.go # or: go build -gcflags -S x.go
60 "".main STEXT size=74 args=0x0 locals=0x10
61 0x0000 00000 (x.go:3) TEXT "".main(SB), $16-0
62 0x0000 00000 (x.go:3) MOVQ (TLS), CX
63 0x0009 00009 (x.go:3) CMPQ SP, 16(CX)
64 0x000d 00013 (x.go:3) JLS 67
65 0x000f 00015 (x.go:3) SUBQ $16, SP
66 0x0013 00019 (x.go:3) MOVQ BP, 8(SP)
67 0x0018 00024 (x.go:3) LEAQ 8(SP), BP
68 0x001d 00029 (x.go:3) FUNCDATA $0, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)
69 0x001d 00029 (x.go:3) FUNCDATA $1, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)
70 0x001d 00029 (x.go:3) FUNCDATA $2, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)
71 0x001d 00029 (x.go:4) PCDATA $0, $0
72 0x001d 00029 (x.go:4) PCDATA $1, $0
73 0x001d 00029 (x.go:4) CALL runtime.printlock(SB)
74 0x0022 00034 (x.go:4) MOVQ $3, (SP)
75 0x002a 00042 (x.go:4) CALL runtime.printint(SB)
76 0x002f 00047 (x.go:4) CALL runtime.printnl(SB)
77 0x0034 00052 (x.go:4) CALL runtime.printunlock(SB)
78 0x0039 00057 (x.go:5) MOVQ 8(SP), BP
79 0x003e 00062 (x.go:5) ADDQ $16, SP
80 0x0042 00066 (x.go:5) RET
81 0x0043 00067 (x.go:5) NOP
82 0x0043 00067 (x.go:3) PCDATA $1, $-1
83 0x0043 00067 (x.go:3) PCDATA $0, $-1
84 0x0043 00067 (x.go:3) CALL runtime.morestack_noctxt(SB)
85 0x0048 00072 (x.go:3) JMP 0
90 The <code>FUNCDATA</code> and <code>PCDATA</code> directives contain information
91 for use by the garbage collector; they are introduced by the compiler.
95 To see what gets put in the binary after linking, use <code>go tool objdump</code>:
99 $ go build -o x.exe x.go
100 $ go tool objdump -s main.main x.exe
101 TEXT main.main(SB) /tmp/x.go
102 x.go:3 0x10501c0 65488b0c2530000000 MOVQ GS:0x30, CX
103 x.go:3 0x10501c9 483b6110 CMPQ 0x10(CX), SP
104 x.go:3 0x10501cd 7634 JBE 0x1050203
105 x.go:3 0x10501cf 4883ec10 SUBQ $0x10, SP
106 x.go:3 0x10501d3 48896c2408 MOVQ BP, 0x8(SP)
107 x.go:3 0x10501d8 488d6c2408 LEAQ 0x8(SP), BP
108 x.go:4 0x10501dd e86e45fdff CALL runtime.printlock(SB)
109 x.go:4 0x10501e2 48c7042403000000 MOVQ $0x3, 0(SP)
110 x.go:4 0x10501ea e8e14cfdff CALL runtime.printint(SB)
111 x.go:4 0x10501ef e8ec47fdff CALL runtime.printnl(SB)
112 x.go:4 0x10501f4 e8d745fdff CALL runtime.printunlock(SB)
113 x.go:5 0x10501f9 488b6c2408 MOVQ 0x8(SP), BP
114 x.go:5 0x10501fe 4883c410 ADDQ $0x10, SP
115 x.go:5 0x1050202 c3 RET
116 x.go:3 0x1050203 e83882ffff CALL runtime.morestack_noctxt(SB)
117 x.go:3 0x1050208 ebb6 JMP main.main(SB)
120 <h3 id="constants">Constants</h3>
123 Although the assembler takes its guidance from the Plan 9 assemblers,
124 it is a distinct program, so there are some differences.
125 One is in constant evaluation.
126 Constant expressions in the assembler are parsed using Go's operator
127 precedence, not the C-like precedence of the original.
128 Thus <code>3&1<<2</code> is 4, not 0—it parses as <code>(3&1)<<2</code>
129 not <code>3&(1<<2)</code>.
130 Also, constants are always evaluated as 64-bit unsigned integers.
131 Thus <code>-2</code> is not the integer value minus two,
132 but the unsigned 64-bit integer with the same bit pattern.
133 The distinction rarely matters but
134 to avoid ambiguity, division or right shift where the right operand's
135 high bit is set is rejected.
138 <h3 id="symbols">Symbols</h3>
141 Some symbols, such as <code>R1</code> or <code>LR</code>,
142 are predefined and refer to registers.
143 The exact set depends on the architecture.
147 There are four predeclared symbols that refer to pseudo-registers.
148 These are not real registers, but rather virtual registers maintained by
149 the toolchain, such as a frame pointer.
150 The set of pseudo-registers is the same for all architectures:
156 <code>FP</code>: Frame pointer: arguments and locals.
160 <code>PC</code>: Program counter:
165 <code>SB</code>: Static base pointer: global symbols.
169 <code>SP</code>: Stack pointer: top of stack.
175 All user-defined symbols are written as offsets to the pseudo-registers
176 <code>FP</code> (arguments and locals) and <code>SB</code> (globals).
180 The <code>SB</code> pseudo-register can be thought of as the origin of memory, so the symbol <code>foo(SB)</code>
181 is the name <code>foo</code> as an address in memory.
182 This form is used to name global functions and data.
183 Adding <code><></code> to the name, as in <span style="white-space: nowrap"><code>foo<>(SB)</code></span>, makes the name
184 visible only in the current source file, like a top-level <code>static</code> declaration in a C file.
185 Adding an offset to the name refers to that offset from the symbol's address, so
186 <code>foo+4(SB)</code> is four bytes past the start of <code>foo</code>.
190 The <code>FP</code> pseudo-register is a virtual frame pointer
191 used to refer to function arguments.
192 The compilers maintain a virtual frame pointer and refer to the arguments on the stack as offsets from that pseudo-register.
193 Thus <code>0(FP)</code> is the first argument to the function,
194 <code>8(FP)</code> is the second (on a 64-bit machine), and so on.
195 However, when referring to a function argument this way, it is necessary to place a name
196 at the beginning, as in <code>first_arg+0(FP)</code> and <code>second_arg+8(FP)</code>.
197 (The meaning of the offset—offset from the frame pointer—distinct
198 from its use with <code>SB</code>, where it is an offset from the symbol.)
199 The assembler enforces this convention, rejecting plain <code>0(FP)</code> and <code>8(FP)</code>.
200 The actual name is semantically irrelevant but should be used to document
202 It is worth stressing that <code>FP</code> is always a
203 pseudo-register, not a hardware
204 register, even on architectures with a hardware frame pointer.
208 For assembly functions with Go prototypes, <code>go</code> <code>vet</code> will check that the argument names
210 On 32-bit systems, the low and high 32 bits of a 64-bit value are distinguished by adding
211 a <code>_lo</code> or <code>_hi</code> suffix to the name, as in <code>arg_lo+0(FP)</code> or <code>arg_hi+4(FP)</code>.
212 If a Go prototype does not name its result, the expected assembly name is <code>ret</code>.
216 The <code>SP</code> pseudo-register is a virtual stack pointer
217 used to refer to frame-local variables and the arguments being
218 prepared for function calls.
219 It points to the top of the local stack frame, so references should use negative offsets
220 in the range [−framesize, 0):
221 <code>x-8(SP)</code>, <code>y-4(SP)</code>, and so on.
225 On architectures with a hardware register named <code>SP</code>,
226 the name prefix distinguishes
227 references to the virtual stack pointer from references to the architectural
228 <code>SP</code> register.
229 That is, <code>x-8(SP)</code> and <code>-8(SP)</code>
230 are different memory locations:
231 the first refers to the virtual stack pointer pseudo-register,
232 while the second refers to the
233 hardware's <code>SP</code> register.
237 On machines where <code>SP</code> and <code>PC</code> are
238 traditionally aliases for a physical, numbered register,
239 in the Go assembler the names <code>SP</code> and <code>PC</code>
240 are still treated specially;
241 for instance, references to <code>SP</code> require a symbol,
242 much like <code>FP</code>.
243 To access the actual hardware register use the true <code>R</code> name.
244 For example, on the ARM architecture the hardware
245 <code>SP</code> and <code>PC</code> are accessible as
246 <code>R13</code> and <code>R15</code>.
250 Branches and direct jumps are always written as offsets to the PC, or as
261 Each label is visible only within the function in which it is defined.
262 It is therefore permitted for multiple functions in a file to define
263 and use the same label names.
264 Direct jumps and call instructions can target text symbols,
265 such as <code>name(SB)</code>, but not offsets from symbols,
266 such as <code>name+4(SB)</code>.
270 Instructions, registers, and assembler directives are always in UPPER CASE to remind you
271 that assembly programming is a fraught endeavor.
272 (Exception: the <code>g</code> register renaming on ARM.)
276 In Go object files and binaries, the full name of a symbol is the
277 package path followed by a period and the symbol name:
278 <code>fmt.Printf</code> or <code>math/rand.Int</code>.
279 Because the assembler's parser treats period and slash as punctuation,
280 those strings cannot be used directly as identifier names.
281 Instead, the assembler allows the middle dot character U+00B7
282 and the division slash U+2215 in identifiers and rewrites them to
283 plain period and slash.
284 Within an assembler source file, the symbols above are written as
285 <code>fmt·Printf</code> and <code>math∕rand·Int</code>.
286 The assembly listings generated by the compilers when using the <code>-S</code> flag
287 show the period and slash directly instead of the Unicode replacements
288 required by the assemblers.
292 Most hand-written assembly files do not include the full package path
293 in symbol names, because the linker inserts the package path of the current
294 object file at the beginning of any name starting with a period:
295 in an assembly source file within the math/rand package implementation,
296 the package's Int function can be referred to as <code>·Int</code>.
297 This convention avoids the need to hard-code a package's import path in its
298 own source code, making it easier to move the code from one location to another.
301 <h3 id="directives">Directives</h3>
304 The assembler uses various directives to bind text and data to symbol names.
305 For example, here is a simple complete function definition. The <code>TEXT</code>
306 directive declares the symbol <code>runtime·profileloop</code> and the instructions
307 that follow form the body of the function.
308 The last instruction in a <code>TEXT</code> block must be some sort of jump, usually a <code>RET</code> (pseudo-)instruction.
309 (If it's not, the linker will append a jump-to-itself instruction; there is no fallthrough in <code>TEXTs</code>.)
310 After the symbol, the arguments are flags (see below)
311 and the frame size, a constant (but see below):
315 TEXT runtime·profileloop(SB),NOSPLIT,$8
316 MOVQ $runtime·profileloop1(SB), CX
318 CALL runtime·externalthreadhandler(SB)
323 In the general case, the frame size is followed by an argument size, separated by a minus sign.
324 (It's not a subtraction, just idiosyncratic syntax.)
325 The frame size <code>$24-8</code> states that the function has a 24-byte frame
326 and is called with 8 bytes of argument, which live on the caller's frame.
327 If <code>NOSPLIT</code> is not specified for the <code>TEXT</code>,
328 the argument size must be provided.
329 For assembly functions with Go prototypes, <code>go</code> <code>vet</code> will check that the
330 argument size is correct.
334 Note that the symbol name uses a middle dot to separate the components and is specified as an offset from the
335 static base pseudo-register <code>SB</code>.
336 This function would be called from Go source for package <code>runtime</code> using the
337 simple name <code>profileloop</code>.
341 Global data symbols are defined by a sequence of initializing
342 <code>DATA</code> directives followed by a <code>GLOBL</code> directive.
343 Each <code>DATA</code> directive initializes a section of the
344 corresponding memory.
345 The memory not explicitly initialized is zeroed.
346 The general form of the <code>DATA</code> directive is
349 DATA symbol+offset(SB)/width, value
353 which initializes the symbol memory at the given offset and width with the given value.
354 The <code>DATA</code> directives for a given symbol must be written with increasing offsets.
358 The <code>GLOBL</code> directive declares a symbol to be global.
359 The arguments are optional flags and the size of the data being declared as a global,
360 which will have initial value all zeros unless a <code>DATA</code> directive
362 The <code>GLOBL</code> directive must follow any corresponding <code>DATA</code> directives.
370 DATA divtab<>+0x00(SB)/4, $0xf4f8fcff
371 DATA divtab<>+0x04(SB)/4, $0xe6eaedf0
373 DATA divtab<>+0x3c(SB)/4, $0x81828384
374 GLOBL divtab<>(SB), RODATA, $64
376 GLOBL runtime·tlsoffset(SB), NOPTR, $4
380 declares and initializes <code>divtab<></code>, a read-only 64-byte table of 4-byte integer values,
381 and declares <code>runtime·tlsoffset</code>, a 4-byte, implicitly zeroed variable that
382 contains no pointers.
386 There may be one or two arguments to the directives.
387 If there are two, the first is a bit mask of flags,
388 which can be written as numeric expressions, added or or-ed together,
389 or can be set symbolically for easier absorption by a human.
390 Their values, defined in the standard <code>#include</code> file <code>textflag.h</code>, are:
395 <code>NOPROF</code> = 1
397 (For <code>TEXT</code> items.)
398 Don't profile the marked function. This flag is deprecated.
401 <code>DUPOK</code> = 2
403 It is legal to have multiple instances of this symbol in a single binary.
404 The linker will choose one of the duplicates to use.
407 <code>NOSPLIT</code> = 4
409 (For <code>TEXT</code> items.)
410 Don't insert the preamble to check if the stack must be split.
411 The frame for the routine, plus anything it calls, must fit in the
412 spare space at the top of the stack segment.
413 Used to protect routines such as the stack splitting code itself.
416 <code>RODATA</code> = 8
418 (For <code>DATA</code> and <code>GLOBL</code> items.)
419 Put this data in a read-only section.
422 <code>NOPTR</code> = 16
424 (For <code>DATA</code> and <code>GLOBL</code> items.)
425 This data contains no pointers and therefore does not need to be
426 scanned by the garbage collector.
429 <code>WRAPPER</code> = 32
431 (For <code>TEXT</code> items.)
432 This is a wrapper function and should not count as disabling <code>recover</code>.
435 <code>NEEDCTXT</code> = 64
437 (For <code>TEXT</code> items.)
438 This function is a closure so it uses its incoming context register.
441 <code>LOCAL</code> = 128
443 This symbol is local to the dynamic shared object.
446 <code>TLSBSS</code> = 256
448 (For <code>DATA</code> and <code>GLOBL</code> items.)
449 Put this data in thread local storage.
452 <code>NOFRAME</code> = 512
454 (For <code>TEXT</code> items.)
455 Do not insert instructions to allocate a stack frame and save/restore the return
456 address, even if this is not a leaf function.
457 Only valid on functions that declare a frame size of 0.
460 <code>TOPFRAME</code> = 2048
462 (For <code>TEXT</code> items.)
463 Function is the top of the call stack. Traceback should stop at this function.
467 <h3 id="runtime">Runtime Coordination</h3>
470 For garbage collection to run correctly, the runtime must know the
471 location of pointers in all global data and in most stack frames.
472 The Go compiler emits this information when compiling Go source files,
473 but assembly programs must define it explicitly.
477 A data symbol marked with the <code>NOPTR</code> flag (see above)
478 is treated as containing no pointers to runtime-allocated data.
479 A data symbol with the <code>RODATA</code> flag
480 is allocated in read-only memory and is therefore treated
481 as implicitly marked <code>NOPTR</code>.
482 A data symbol with a total size smaller than a pointer
483 is also treated as implicitly marked <code>NOPTR</code>.
484 It is not possible to define a symbol containing pointers in an assembly source file;
485 such a symbol must be defined in a Go source file instead.
486 Assembly source can still refer to the symbol by name
487 even without <code>DATA</code> and <code>GLOBL</code> directives.
488 A good general rule of thumb is to define all non-<code>RODATA</code>
489 symbols in Go instead of in assembly.
493 Each function also needs annotations giving the location of
494 live pointers in its arguments, results, and local stack frame.
495 For an assembly function with no pointer results and
496 either no local stack frame or no function calls,
497 the only requirement is to define a Go prototype for the function
498 in a Go source file in the same package. The name of the assembly
499 function must not contain the package name component (for example,
500 function <code>Syscall</code> in package <code>syscall</code> should
501 use the name <code>·Syscall</code> instead of the equivalent name
502 <code>syscall·Syscall</code> in its <code>TEXT</code> directive).
503 For more complex situations, explicit annotation is needed.
504 These annotations use pseudo-instructions defined in the standard
505 <code>#include</code> file <code>funcdata.h</code>.
509 If a function has no arguments and no results,
510 the pointer information can be omitted.
511 This is indicated by an argument size annotation of <code>$<i>n</i>-0</code>
512 on the <code>TEXT</code> instruction.
513 Otherwise, pointer information must be provided by
514 a Go prototype for the function in a Go source file,
515 even for assembly functions not called directly from Go.
516 (The prototype will also let <code>go</code> <code>vet</code> check the argument references.)
517 At the start of the function, the arguments are assumed
518 to be initialized but the results are assumed uninitialized.
519 If the results will hold live pointers during a call instruction,
520 the function should start by zeroing the results and then
521 executing the pseudo-instruction <code>GO_RESULTS_INITIALIZED</code>.
522 This instruction records that the results are now initialized
523 and should be scanned during stack movement and garbage collection.
524 It is typically easier to arrange that assembly functions do not
525 return pointers or do not contain call instructions;
526 no assembly functions in the standard library use
527 <code>GO_RESULTS_INITIALIZED</code>.
531 If a function has no local stack frame,
532 the pointer information can be omitted.
533 This is indicated by a local frame size annotation of <code>$0-<i>n</i></code>
534 on the <code>TEXT</code> instruction.
535 The pointer information can also be omitted if the
536 function contains no call instructions.
537 Otherwise, the local stack frame must not contain pointers,
538 and the assembly must confirm this fact by executing the
539 pseudo-instruction <code>NO_LOCAL_POINTERS</code>.
540 Because stack resizing is implemented by moving the stack,
541 the stack pointer may change during any function call:
542 even pointers to stack data must not be kept in local variables.
546 Assembly functions should always be given Go prototypes,
547 both to provide pointer information for the arguments and results
548 and to let <code>go</code> <code>vet</code> check that
549 the offsets being used to access them are correct.
552 <h2 id="architectures">Architecture-specific details</h2>
555 It is impractical to list all the instructions and other details for each machine.
556 To see what instructions are defined for a given machine, say ARM,
557 look in the source for the <code>obj</code> support library for
558 that architecture, located in the directory <code>src/cmd/internal/obj/arm</code>.
559 In that directory is a file <code>a.out.go</code>; it contains
560 a long list of constants starting with <code>A</code>, like this:
565 AAND = obj.ABaseARM + obj.A_ARCHSPECIFIC + iota
574 This is the list of instructions and their spellings as known to the assembler and linker for that architecture.
575 Each instruction begins with an initial capital <code>A</code> in this list, so <code>AAND</code>
576 represents the bitwise and instruction,
577 <code>AND</code> (without the leading <code>A</code>),
578 and is written in assembly source as <code>AND</code>.
579 The enumeration is mostly in alphabetical order.
580 (The architecture-independent <code>AXXX</code>, defined in the
581 <code>cmd/internal/obj</code> package,
582 represents an invalid instruction).
583 The sequence of the <code>A</code> names has nothing to do with the actual
584 encoding of the machine instructions.
585 The <code>cmd/internal/obj</code> package takes care of that detail.
589 The instructions for both the 386 and AMD64 architectures are listed in
590 <code>cmd/internal/obj/x86/a.out.go</code>.
594 The architectures share syntax for common addressing modes such as
595 <code>(R1)</code> (register indirect),
596 <code>4(R1)</code> (register indirect with offset), and
597 <code>$foo(SB)</code> (absolute address).
598 The assembler also supports some (not necessarily all) addressing modes
599 specific to each architecture.
600 The sections below list these.
604 One detail evident in the examples from the previous sections is that data in the instructions flows from left to right:
605 <code>MOVQ</code> <code>$0,</code> <code>CX</code> clears <code>CX</code>.
606 This rule applies even on architectures where the conventional notation uses the opposite direction.
610 Here follow some descriptions of key Go-specific details for the supported architectures.
613 <h3 id="x86">32-bit Intel 386</h3>
616 The runtime pointer to the <code>g</code> structure is maintained
617 through the value of an otherwise unused (as far as Go is concerned) register in the MMU.
618 An OS-dependent macro <code>get_tls</code> is defined for the assembler if the source is
619 in the <code>runtime</code> package and includes a special header, <code>go_tls.h</code>:
627 Within the runtime, the <code>get_tls</code> macro loads its argument register
628 with a pointer to the <code>g</code> pointer, and the <code>g</code> struct
629 contains the <code>m</code> pointer.
630 There's another special header containing the offsets for each
631 element of <code>g</code>, called <code>go_asm.h</code>.
632 The sequence to load <code>g</code> and <code>m</code> using <code>CX</code> looks like this:
640 MOVL g(CX), AX // Move g into AX.
641 MOVL g_m(AX), BX // Move g.m into BX.
645 Note: The code above works only in the <code>runtime</code> package, while <code>go_tls.h</code> also
646 applies to <a href="#arm">arm</a>, <a href="#amd64">amd64</a> and amd64p32, and <code>go_asm.h</code> applies to all architectures.
656 <code>(DI)(BX*2)</code>: The location at address <code>DI</code> plus <code>BX*2</code>.
660 <code>64(DI)(BX*2)</code>: The location at address <code>DI</code> plus <code>BX*2</code> plus 64.
661 These modes accept only 1, 2, 4, and 8 as scale factors.
667 When using the compiler and assembler's
668 <code>-dynlink</code> or <code>-shared</code> modes,
669 any load or store of a fixed memory location such as a global variable
670 must be assumed to overwrite <code>CX</code>.
671 Therefore, to be safe for use with these modes,
672 assembly sources should typically avoid CX except between memory references.
675 <h3 id="amd64">64-bit Intel 386 (a.k.a. amd64)</h3>
678 The two architectures behave largely the same at the assembler level.
679 Assembly code to access the <code>m</code> and <code>g</code>
680 pointers on the 64-bit version is the same as on the 32-bit 386,
681 except it uses <code>MOVQ</code> rather than <code>MOVL</code>:
686 MOVQ g(CX), AX // Move g into AX.
687 MOVQ g_m(AX), BX // Move g.m into BX.
691 Register <code>BP</code> is callee-save.
692 The assembler automatically inserts <code>BP</code> save/restore when frame size is larger than zero.
693 Using <code>BP</code> as a general purpose register is allowed,
694 however it can interfere with sampling-based profiling.
697 <h3 id="arm">ARM</h3>
700 The registers <code>R10</code> and <code>R11</code>
701 are reserved by the compiler and linker.
705 <code>R10</code> points to the <code>g</code> (goroutine) structure.
706 Within assembler source code, this pointer must be referred to as <code>g</code>;
707 the name <code>R10</code> is not recognized.
711 To make it easier for people and compilers to write assembly, the ARM linker
712 allows general addressing forms and pseudo-operations like <code>DIV</code> or <code>MOD</code>
713 that may not be expressible using a single hardware instruction.
714 It implements these forms as multiple instructions, often using the <code>R11</code> register
715 to hold temporary values.
716 Hand-written assembly can use <code>R11</code>, but doing so requires
717 being sure that the linker is not also using it to implement any of the other
718 instructions in the function.
722 When defining a <code>TEXT</code>, specifying frame size <code>$-4</code>
723 tells the linker that this is a leaf function that does not need to save <code>LR</code> on entry.
727 The name <code>SP</code> always refers to the virtual stack pointer described earlier.
728 For the hardware register, use <code>R13</code>.
732 Condition code syntax is to append a period and the one- or two-letter code to the instruction,
733 as in <code>MOVW.EQ</code>.
734 Multiple codes may be appended: <code>MOVM.IA.W</code>.
735 The order of the code modifiers is irrelevant.
745 <code>R0->16</code>
747 <code>R0>>16</code>
749 <code>R0<<16</code>
751 <code>R0@>16</code>:
752 For <code><<</code>, left shift <code>R0</code> by 16 bits.
753 The other codes are <code>-></code> (arithmetic right shift),
754 <code>>></code> (logical right shift), and
755 <code>@></code> (rotate right).
759 <code>R0->R1</code>
761 <code>R0>>R1</code>
763 <code>R0<<R1</code>
765 <code>R0@>R1</code>:
766 For <code><<</code>, left shift <code>R0</code> by the count in <code>R1</code>.
767 The other codes are <code>-></code> (arithmetic right shift),
768 <code>>></code> (logical right shift), and
769 <code>@></code> (rotate right).
774 <code>[R0,g,R12-R15]</code>: For multi-register instructions, the set comprising
775 <code>R0</code>, <code>g</code>, and <code>R12</code> through <code>R15</code> inclusive.
779 <code>(R5, R6)</code>: Destination register pair.
784 <h3 id="arm64">ARM64</h3>
787 The ARM64 port is in an experimental state.
791 <code>R18</code> is the "platform register", reserved on the Apple platform.
792 To prevent accidental misuse, the register is named <code>R18_PLATFORM</code>.
793 <code>R27</code> and <code>R28</code> are reserved by the compiler and linker.
794 <code>R29</code> is the frame pointer.
795 <code>R30</code> is the link register.
799 Instruction modifiers are appended to the instruction following a period.
800 The only modifiers are <code>P</code> (postincrement) and <code>W</code>
802 <code>MOVW.P</code>, <code>MOVW.W</code>
812 <code>R0->16</code>
814 <code>R0>>16</code>
816 <code>R0<<16</code>
818 <code>R0@>16</code>:
819 These are the same as on the 32-bit ARM.
823 <code>$(8<<12)</code>:
824 Left shift the immediate value <code>8</code> by <code>12</code> bits.
829 Add the value of <code>R0</code> and <code>8</code>.
833 <code>(R2)(R0)</code>:
834 The location at <code>R0</code> plus <code>R2</code>.
840 <code>R0.UXTB<<imm</code>:
841 <code>UXTB</code>: extract an 8-bit value from the low-order bits of <code>R0</code> and zero-extend it to the size of <code>R0</code>.
842 <code>R0.UXTB<<imm</code>: left shift the result of <code>R0.UXTB</code> by <code>imm</code> bits.
843 The <code>imm</code> value can be 0, 1, 2, 3, or 4.
844 The other extensions include <code>UXTH</code> (16-bit), <code>UXTW</code> (32-bit), and <code>UXTX</code> (64-bit).
850 <code>R0.SXTB<<imm</code>:
851 <code>SXTB</code>: extract an 8-bit value from the low-order bits of <code>R0</code> and sign-extend it to the size of <code>R0</code>.
852 <code>R0.SXTB<<imm</code>: left shift the result of <code>R0.SXTB</code> by <code>imm</code> bits.
853 The <code>imm</code> value can be 0, 1, 2, 3, or 4.
854 The other extensions include <code>SXTH</code> (16-bit), <code>SXTW</code> (32-bit), and <code>SXTX</code> (64-bit).
858 <code>(R5, R6)</code>: Register pair for <code>LDAXP</code>/<code>LDP</code>/<code>LDXP</code>/<code>STLXP</code>/<code>STP</code>/<code>STP</code>.
864 Reference: <a href="/pkg/cmd/internal/obj/arm64">Go ARM64 Assembly Instructions Reference Manual</a>
867 <h3 id="ppc64">PPC64</h3>
870 This assembler is used by GOARCH values ppc64 and ppc64le.
874 Reference: <a href="/pkg/cmd/internal/obj/ppc64">Go PPC64 Assembly Instructions Reference Manual</a>
879 <h3 id="s390x">IBM z/Architecture, a.k.a. s390x</h3>
882 The registers <code>R10</code> and <code>R11</code> are reserved.
883 The assembler uses them to hold temporary values when assembling some instructions.
887 <code>R13</code> points to the <code>g</code> (goroutine) structure.
888 This register must be referred to as <code>g</code>; the name <code>R13</code> is not recognized.
892 <code>R15</code> points to the stack frame and should typically only be accessed using the
893 virtual registers <code>SP</code> and <code>FP</code>.
897 Load- and store-multiple instructions operate on a range of registers.
898 The range of registers is specified by a start register and an end register.
899 For example, <code>LMG</code> <code>(R9),</code> <code>R5,</code> <code>R7</code> would load
900 <code>R5</code>, <code>R6</code> and <code>R7</code> with the 64-bit values at
901 <code>0(R9)</code>, <code>8(R9)</code> and <code>16(R9)</code> respectively.
905 Storage-and-storage instructions such as <code>MVC</code> and <code>XC</code> are written
906 with the length as the first argument.
907 For example, <code>XC</code> <code>$8,</code> <code>(R9),</code> <code>(R9)</code> would clear
908 eight bytes at the address specified in <code>R9</code>.
912 If a vector instruction takes a length or an index as an argument then it will be the
914 For example, <code>VLEIF</code> <code>$1,</code> <code>$16,</code> <code>V2</code> will load
915 the value sixteen into index one of <code>V2</code>.
916 Care should be taken when using vector instructions to ensure that they are available at
918 To use vector instructions a machine must have both the vector facility (bit 129 in the
919 facility list) and kernel support.
920 Without kernel support a vector instruction will have no effect (it will be equivalent
921 to a <code>NOP</code> instruction).
931 <code>(R5)(R6*1)</code>: The location at <code>R5</code> plus <code>R6</code>.
932 It is a scaled mode as on the x86, but the only scale allowed is <code>1</code>.
937 <h3 id="mips">MIPS, MIPS64</h3>
940 General purpose registers are named <code>R0</code> through <code>R31</code>,
941 floating point registers are <code>F0</code> through <code>F31</code>.
945 <code>R30</code> is reserved to point to <code>g</code>.
946 <code>R23</code> is used as a temporary register.
950 In a <code>TEXT</code> directive, the frame size <code>$-4</code> for MIPS or
951 <code>$-8</code> for MIPS64 instructs the linker not to save <code>LR</code>.
955 <code>SP</code> refers to the virtual stack pointer.
956 For the hardware register, use <code>R29</code>.
966 <code>16(R1)</code>: The location at <code>R1</code> plus 16.
970 <code>(R1)</code>: Alias for <code>0(R1)</code>.
976 The value of <code>GOMIPS</code> environment variable (<code>hardfloat</code> or
977 <code>softfloat</code>) is made available to assembly code by predefining either
978 <code>GOMIPS_hardfloat</code> or <code>GOMIPS_softfloat</code>.
982 The value of <code>GOMIPS64</code> environment variable (<code>hardfloat</code> or
983 <code>softfloat</code>) is made available to assembly code by predefining either
984 <code>GOMIPS64_hardfloat</code> or <code>GOMIPS64_softfloat</code>.
987 <h3 id="unsupported_opcodes">Unsupported opcodes</h3>
990 The assemblers are designed to support the compiler so not all hardware instructions
991 are defined for all architectures: if the compiler doesn't generate it, it might not be there.
992 If you need to use a missing instruction, there are two ways to proceed.
993 One is to update the assembler to support that instruction, which is straightforward
994 but only worthwhile if it's likely the instruction will be used again.
995 Instead, for simple one-off cases, it's possible to use the <code>BYTE</code>
996 and <code>WORD</code> directives
997 to lay down explicit data into the instruction stream within a <code>TEXT</code>.
998 Here's how the 386 runtime defines the 64-bit atomic load function.
1002 // uint64 atomicload64(uint64 volatile* addr);
1004 // void atomicload64(uint64 *res, uint64 volatile *addr);
1005 TEXT runtime·atomicload64(SB), NOSPLIT, $0-12
1009 MOVL 0, AX // crash with nil ptr deref
1010 LEAL ret_lo+4(FP), BX
1011 // MOVQ (%EAX), %MM0
1012 BYTE $0x0f; BYTE $0x6f; BYTE $0x00
1013 // MOVQ %MM0, 0(%EBX)
1014 BYTE $0x0f; BYTE $0x7f; BYTE $0x03
1016 BYTE $0x0F; BYTE $0x77