1 @c Copyright (C) 1991-2023 Free Software Foundation, Inc.
2 @c This is part of the GAS manual.
3 @c For copying conditions, see the file as.texinfo.
9 @chapter 80386 Dependent Features
12 @node Machine Dependencies
13 @chapter 80386 Dependent Features
17 @cindex i80386 support
18 @cindex x86-64 support
20 The i386 version @code{@value{AS}} supports both the original Intel 386
21 architecture in both 16 and 32-bit mode as well as AMD x86-64 architecture
22 extending the Intel architecture to 64-bits.
25 * i386-Options:: Options
26 * i386-Directives:: X86 specific directives
27 * i386-Syntax:: Syntactical considerations
28 * i386-Mnemonics:: Instruction Naming
29 * i386-Regs:: Register Naming
30 * i386-Prefixes:: Instruction Prefixes
31 * i386-Memory:: Memory References
32 * i386-Jumps:: Handling of Jump Instructions
33 * i386-Float:: Floating Point
34 * i386-SIMD:: Intel's MMX and AMD's 3DNow! SIMD Operations
35 * i386-LWP:: AMD's Lightweight Profiling Instructions
36 * i386-BMI:: Bit Manipulation Instruction
37 * i386-TBM:: AMD's Trailing Bit Manipulation Instructions
38 * i386-16bit:: Writing 16-bit Code
39 * i386-Arch:: Specifying an x86 CPU architecture
40 * i386-ISA:: AMD64 ISA vs. Intel64 ISA
41 * i386-Bugs:: AT&T Syntax bugs
48 @cindex options for i386
49 @cindex options for x86-64
51 @cindex x86-64 options
53 The i386 version of @code{@value{AS}} has a few machine
58 @cindex @samp{--32} option, i386
59 @cindex @samp{--32} option, x86-64
60 @cindex @samp{--x32} option, i386
61 @cindex @samp{--x32} option, x86-64
62 @cindex @samp{--64} option, i386
63 @cindex @samp{--64} option, x86-64
64 @item --32 | --x32 | --64
65 Select the word size, either 32 bits or 64 bits. @samp{--32}
66 implies Intel i386 architecture, while @samp{--x32} and @samp{--64}
67 imply AMD x86-64 architecture with 32-bit or 64-bit word-size
70 These options are only available with the ELF object file format, and
71 require that the necessary BFD support has been included (on a 32-bit
72 platform you have to add --enable-64-bit-bfd to configure enable 64-bit
73 usage and use x86-64 as target platform).
76 By default, x86 GAS replaces multiple nop instructions used for
77 alignment within code sections with multi-byte nop instructions such
78 as leal 0(%esi,1),%esi. This switch disables the optimization if a single
79 byte nop (0x90) is explicitly specified as the fill byte for alignment.
81 @cindex @samp{--divide} option, i386
83 On SVR4-derived platforms, the character @samp{/} is treated as a comment
84 character, which means that it cannot be used in expressions. The
85 @samp{--divide} option turns @samp{/} into a normal character. This does
86 not disable @samp{/} at the beginning of a line starting a comment, or
87 affect using @samp{#} for starting a comment.
89 @cindex @samp{-march=} option, i386
90 @cindex @samp{-march=} option, x86-64
91 @item -march=@var{CPU}[+@var{EXTENSION}@dots{}]
92 This option specifies the target processor. The assembler will
93 issue an error message if an attempt is made to assemble an instruction
94 which will not execute on the target processor. The following
95 processor names are recognized:
133 In addition to the basic instruction set, the assembler can be told to
134 accept various extension mnemonics. For example,
135 @code{-march=i686+sse4+vmx} extends @var{i686} with @var{sse4} and
136 @var{vmx}. The following extensions are currently supported:
189 @code{avx512_4fmaps},
190 @code{avx512_4vnniw},
191 @code{avx512_vpopcntdq},
194 @code{avx512_bitalg},
195 @code{avx512_vp2intersect},
202 @code{avx_vnni_int8},
206 @code{avx_ne_convert},
210 @code{avx_vnni_int16},
268 Note that these extension mnemonics can be prefixed with @code{no} to revoke
269 the respective (and any dependent) functionality.
271 When the @code{.arch} directive is used with @option{-march}, the
272 @code{.arch} directive will take precedent.
274 @cindex @samp{-mtune=} option, i386
275 @cindex @samp{-mtune=} option, x86-64
276 @item -mtune=@var{CPU}
277 This option specifies a processor to optimize for. When used in
278 conjunction with the @option{-march} option, only instructions
279 of the processor specified by the @option{-march} option will be
282 Valid @var{CPU} values are identical to the processor list of
283 @option{-march=@var{CPU}}.
285 @cindex @samp{-msse2avx} option, i386
286 @cindex @samp{-msse2avx} option, x86-64
288 This option specifies that the assembler should encode SSE instructions
291 @cindex @samp{-muse-unaligned-vector-move} option, i386
292 @cindex @samp{-muse-unaligned-vector-move} option, x86-64
293 @item -muse-unaligned-vector-move
294 This option specifies that the assembler should encode aligned vector
295 move as unaligned vector move.
297 @cindex @samp{-msse-check=} option, i386
298 @cindex @samp{-msse-check=} option, x86-64
299 @item -msse-check=@var{none}
300 @itemx -msse-check=@var{warning}
301 @itemx -msse-check=@var{error}
302 These options control if the assembler should check SSE instructions.
303 @option{-msse-check=@var{none}} will make the assembler not to check SSE
304 instructions, which is the default. @option{-msse-check=@var{warning}}
305 will make the assembler issue a warning for any SSE instruction.
306 @option{-msse-check=@var{error}} will make the assembler issue an error
307 for any SSE instruction.
309 @cindex @samp{-mavxscalar=} option, i386
310 @cindex @samp{-mavxscalar=} option, x86-64
311 @item -mavxscalar=@var{128}
312 @itemx -mavxscalar=@var{256}
313 These options control how the assembler should encode scalar AVX
314 instructions. @option{-mavxscalar=@var{128}} will encode scalar
315 AVX instructions with 128bit vector length, which is the default.
316 @option{-mavxscalar=@var{256}} will encode scalar AVX instructions
317 with 256bit vector length.
319 WARNING: Don't use this for production code - due to CPU errata the
320 resulting code may not work on certain models.
322 @cindex @samp{-mvexwig=} option, i386
323 @cindex @samp{-mvexwig=} option, x86-64
324 @item -mvexwig=@var{0}
325 @itemx -mvexwig=@var{1}
326 These options control how the assembler should encode VEX.W-ignored (WIG)
327 VEX instructions. @option{-mvexwig=@var{0}} will encode WIG VEX
328 instructions with vex.w = 0, which is the default.
329 @option{-mvexwig=@var{1}} will encode WIG EVEX instructions with
332 WARNING: Don't use this for production code - due to CPU errata the
333 resulting code may not work on certain models.
335 @cindex @samp{-mevexlig=} option, i386
336 @cindex @samp{-mevexlig=} option, x86-64
337 @item -mevexlig=@var{128}
338 @itemx -mevexlig=@var{256}
339 @itemx -mevexlig=@var{512}
340 These options control how the assembler should encode length-ignored
341 (LIG) EVEX instructions. @option{-mevexlig=@var{128}} will encode LIG
342 EVEX instructions with 128bit vector length, which is the default.
343 @option{-mevexlig=@var{256}} and @option{-mevexlig=@var{512}} will
344 encode LIG EVEX instructions with 256bit and 512bit vector length,
347 @cindex @samp{-mevexwig=} option, i386
348 @cindex @samp{-mevexwig=} option, x86-64
349 @item -mevexwig=@var{0}
350 @itemx -mevexwig=@var{1}
351 These options control how the assembler should encode w-ignored (WIG)
352 EVEX instructions. @option{-mevexwig=@var{0}} will encode WIG
353 EVEX instructions with evex.w = 0, which is the default.
354 @option{-mevexwig=@var{1}} will encode WIG EVEX instructions with
357 @cindex @samp{-mmnemonic=} option, i386
358 @cindex @samp{-mmnemonic=} option, x86-64
359 @item -mmnemonic=@var{att}
360 @itemx -mmnemonic=@var{intel}
361 This option specifies instruction mnemonic for matching instructions.
362 The @code{.att_mnemonic} and @code{.intel_mnemonic} directives will
365 @cindex @samp{-msyntax=} option, i386
366 @cindex @samp{-msyntax=} option, x86-64
367 @item -msyntax=@var{att}
368 @itemx -msyntax=@var{intel}
369 This option specifies instruction syntax when processing instructions.
370 The @code{.att_syntax} and @code{.intel_syntax} directives will
373 @cindex @samp{-mnaked-reg} option, i386
374 @cindex @samp{-mnaked-reg} option, x86-64
376 This option specifies that registers don't require a @samp{%} prefix.
377 The @code{.att_syntax} and @code{.intel_syntax} directives will take precedent.
379 @cindex @samp{-madd-bnd-prefix} option, i386
380 @cindex @samp{-madd-bnd-prefix} option, x86-64
381 @item -madd-bnd-prefix
382 This option forces the assembler to add BND prefix to all branches, even
383 if such prefix was not explicitly specified in the source code.
385 @cindex @samp{-mshared} option, i386
386 @cindex @samp{-mshared} option, x86-64
388 On ELF target, the assembler normally optimizes out non-PLT relocations
389 against defined non-weak global branch targets with default visibility.
390 The @samp{-mshared} option tells the assembler to generate code which
391 may go into a shared library where all non-weak global branch targets
392 with default visibility can be preempted. The resulting code is
393 slightly bigger. This option only affects the handling of branch
396 @cindex @samp{-mbig-obj} option, i386
397 @cindex @samp{-mbig-obj} option, x86-64
399 On PE/COFF target this option forces the use of big object file
400 format, which allows more than 32768 sections.
402 @cindex @samp{-momit-lock-prefix=} option, i386
403 @cindex @samp{-momit-lock-prefix=} option, x86-64
404 @item -momit-lock-prefix=@var{no}
405 @itemx -momit-lock-prefix=@var{yes}
406 These options control how the assembler should encode lock prefix.
407 This option is intended as a workaround for processors, that fail on
408 lock prefix. This option can only be safely used with single-core,
409 single-thread computers
410 @option{-momit-lock-prefix=@var{yes}} will omit all lock prefixes.
411 @option{-momit-lock-prefix=@var{no}} will encode lock prefix as usual,
412 which is the default.
414 @cindex @samp{-mfence-as-lock-add=} option, i386
415 @cindex @samp{-mfence-as-lock-add=} option, x86-64
416 @item -mfence-as-lock-add=@var{no}
417 @itemx -mfence-as-lock-add=@var{yes}
418 These options control how the assembler should encode lfence, mfence and
420 @option{-mfence-as-lock-add=@var{yes}} will encode lfence, mfence and
421 sfence as @samp{lock addl $0x0, (%rsp)} in 64-bit mode and
422 @samp{lock addl $0x0, (%esp)} in 32-bit mode.
423 @option{-mfence-as-lock-add=@var{no}} will encode lfence, mfence and
424 sfence as usual, which is the default.
426 @cindex @samp{-mrelax-relocations=} option, i386
427 @cindex @samp{-mrelax-relocations=} option, x86-64
428 @item -mrelax-relocations=@var{no}
429 @itemx -mrelax-relocations=@var{yes}
430 These options control whether the assembler should generate relax
431 relocations, R_386_GOT32X, in 32-bit mode, or R_X86_64_GOTPCRELX and
432 R_X86_64_REX_GOTPCRELX, in 64-bit mode.
433 @option{-mrelax-relocations=@var{yes}} will generate relax relocations.
434 @option{-mrelax-relocations=@var{no}} will not generate relax
435 relocations. The default can be controlled by a configure option
436 @option{--enable-x86-relax-relocations}.
438 @cindex @samp{-malign-branch-boundary=} option, i386
439 @cindex @samp{-malign-branch-boundary=} option, x86-64
440 @item -malign-branch-boundary=@var{NUM}
441 This option controls how the assembler should align branches with segment
442 prefixes or NOP. @var{NUM} must be a power of 2. It should be 0 or
443 no less than 16. Branches will be aligned within @var{NUM} byte
444 boundary. @option{-malign-branch-boundary=0}, which is the default,
445 doesn't align branches.
447 @cindex @samp{-malign-branch=} option, i386
448 @cindex @samp{-malign-branch=} option, x86-64
449 @item -malign-branch=@var{TYPE}[+@var{TYPE}...]
450 This option specifies types of branches to align. @var{TYPE} is
451 combination of @samp{jcc}, which aligns conditional jumps,
452 @samp{fused}, which aligns fused conditional jumps, @samp{jmp},
453 which aligns unconditional jumps, @samp{call} which aligns calls,
454 @samp{ret}, which aligns rets, @samp{indirect}, which aligns indirect
455 jumps and calls. The default is @option{-malign-branch=jcc+fused+jmp}.
457 @cindex @samp{-malign-branch-prefix-size=} option, i386
458 @cindex @samp{-malign-branch-prefix-size=} option, x86-64
459 @item -malign-branch-prefix-size=@var{NUM}
460 This option specifies the maximum number of prefixes on an instruction
461 to align branches. @var{NUM} should be between 0 and 5. The default
464 @cindex @samp{-mbranches-within-32B-boundaries} option, i386
465 @cindex @samp{-mbranches-within-32B-boundaries} option, x86-64
466 @item -mbranches-within-32B-boundaries
467 This option aligns conditional jumps, fused conditional jumps and
468 unconditional jumps within 32 byte boundary with up to 5 segment prefixes
469 on an instruction. It is equivalent to
470 @option{-malign-branch-boundary=32}
471 @option{-malign-branch=jcc+fused+jmp}
472 @option{-malign-branch-prefix-size=5}.
473 The default doesn't align branches.
475 @cindex @samp{-mlfence-after-load=} option, i386
476 @cindex @samp{-mlfence-after-load=} option, x86-64
477 @item -mlfence-after-load=@var{no}
478 @itemx -mlfence-after-load=@var{yes}
479 These options control whether the assembler should generate lfence
480 after load instructions. @option{-mlfence-after-load=@var{yes}} will
481 generate lfence. @option{-mlfence-after-load=@var{no}} will not generate
482 lfence, which is the default.
484 @cindex @samp{-mlfence-before-indirect-branch=} option, i386
485 @cindex @samp{-mlfence-before-indirect-branch=} option, x86-64
486 @item -mlfence-before-indirect-branch=@var{none}
487 @item -mlfence-before-indirect-branch=@var{all}
488 @item -mlfence-before-indirect-branch=@var{register}
489 @itemx -mlfence-before-indirect-branch=@var{memory}
490 These options control whether the assembler should generate lfence
491 before indirect near branch instructions.
492 @option{-mlfence-before-indirect-branch=@var{all}} will generate lfence
493 before indirect near branch via register and issue a warning before
494 indirect near branch via memory.
495 It also implicitly sets @option{-mlfence-before-ret=@var{shl}} when
496 there's no explicit @option{-mlfence-before-ret=}.
497 @option{-mlfence-before-indirect-branch=@var{register}} will generate
498 lfence before indirect near branch via register.
499 @option{-mlfence-before-indirect-branch=@var{memory}} will issue a
500 warning before indirect near branch via memory.
501 @option{-mlfence-before-indirect-branch=@var{none}} will not generate
502 lfence nor issue warning, which is the default. Note that lfence won't
503 be generated before indirect near branch via register with
504 @option{-mlfence-after-load=@var{yes}} since lfence will be generated
505 after loading branch target register.
507 @cindex @samp{-mlfence-before-ret=} option, i386
508 @cindex @samp{-mlfence-before-ret=} option, x86-64
509 @item -mlfence-before-ret=@var{none}
510 @item -mlfence-before-ret=@var{shl}
511 @item -mlfence-before-ret=@var{or}
512 @item -mlfence-before-ret=@var{yes}
513 @itemx -mlfence-before-ret=@var{not}
514 These options control whether the assembler should generate lfence
515 before ret. @option{-mlfence-before-ret=@var{or}} will generate
516 generate or instruction with lfence.
517 @option{-mlfence-before-ret=@var{shl/yes}} will generate shl instruction
518 with lfence. @option{-mlfence-before-ret=@var{not}} will generate not
519 instruction with lfence. @option{-mlfence-before-ret=@var{none}} will not
520 generate lfence, which is the default.
522 @cindex @samp{-mx86-used-note=} option, i386
523 @cindex @samp{-mx86-used-note=} option, x86-64
524 @item -mx86-used-note=@var{no}
525 @itemx -mx86-used-note=@var{yes}
526 These options control whether the assembler should generate
527 GNU_PROPERTY_X86_ISA_1_USED and GNU_PROPERTY_X86_FEATURE_2_USED
528 GNU property notes. The default can be controlled by the
529 @option{--enable-x86-used-note} configure option.
531 @cindex @samp{-mevexrcig=} option, i386
532 @cindex @samp{-mevexrcig=} option, x86-64
533 @item -mevexrcig=@var{rne}
534 @itemx -mevexrcig=@var{rd}
535 @itemx -mevexrcig=@var{ru}
536 @itemx -mevexrcig=@var{rz}
537 These options control how the assembler should encode SAE-only
538 EVEX instructions. @option{-mevexrcig=@var{rne}} will encode RC bits
539 of EVEX instruction with 00, which is the default.
540 @option{-mevexrcig=@var{rd}}, @option{-mevexrcig=@var{ru}}
541 and @option{-mevexrcig=@var{rz}} will encode SAE-only EVEX instructions
542 with 01, 10 and 11 RC bits, respectively.
544 @cindex @samp{-mamd64} option, x86-64
545 @cindex @samp{-mintel64} option, x86-64
548 This option specifies that the assembler should accept only AMD64 or
549 Intel64 ISA in 64-bit mode. The default is to accept common, Intel64
552 @cindex @samp{-O0} option, i386
553 @cindex @samp{-O0} option, x86-64
554 @cindex @samp{-O} option, i386
555 @cindex @samp{-O} option, x86-64
556 @cindex @samp{-O1} option, i386
557 @cindex @samp{-O1} option, x86-64
558 @cindex @samp{-O2} option, i386
559 @cindex @samp{-O2} option, x86-64
560 @cindex @samp{-Os} option, i386
561 @cindex @samp{-Os} option, x86-64
562 @item -O0 | -O | -O1 | -O2 | -Os
563 Optimize instruction encoding with smaller instruction size. @samp{-O}
564 and @samp{-O1} encode 64-bit register load instructions with 64-bit
565 immediate as 32-bit register load instructions with 31-bit or 32-bits
566 immediates, encode 64-bit register clearing instructions with 32-bit
567 register clearing instructions, encode 256-bit/512-bit VEX/EVEX vector
568 register clearing instructions with 128-bit VEX vector register
569 clearing instructions, encode 128-bit/256-bit EVEX vector
570 register load/store instructions with VEX vector register load/store
571 instructions, and encode 128-bit/256-bit EVEX packed integer logical
572 instructions with 128-bit/256-bit VEX packed integer logical.
574 @samp{-O2} includes @samp{-O1} optimization plus encodes
575 256-bit/512-bit EVEX vector register clearing instructions with 128-bit
576 EVEX vector register clearing instructions. In 64-bit mode VEX encoded
577 instructions with commutative source operands will also have their
578 source operands swapped if this allows using the 2-byte VEX prefix form
579 instead of the 3-byte one. Certain forms of AND as well as OR with the
580 same (register) operand specified twice will also be changed to TEST.
582 @samp{-Os} includes @samp{-O2} optimization plus encodes 16-bit, 32-bit
583 and 64-bit register tests with immediate as 8-bit register test with
584 immediate. @samp{-O0} turns off this optimization.
589 @node i386-Directives
590 @section x86 specific Directives
592 @cindex machine directives, x86
593 @cindex x86 machine directives
596 @cindex @code{lcomm} directive, COFF
597 @item .lcomm @var{symbol} , @var{length}[, @var{alignment}]
598 Reserve @var{length} (an absolute expression) bytes for a local common
599 denoted by @var{symbol}. The section and value of @var{symbol} are
600 those of the new local common. The addresses are allocated in the bss
601 section, so that at run-time the bytes start off zeroed. Since
602 @var{symbol} is not declared global, it is normally not visible to
603 @code{@value{LD}}. The optional third parameter, @var{alignment},
604 specifies the desired alignment of the symbol in the bss section.
606 This directive is only available for COFF based x86 targets.
608 @cindex @code{largecomm} directive, ELF
609 @item .largecomm @var{symbol} , @var{length}[, @var{alignment}]
610 This directive behaves in the same way as the @code{comm} directive
611 except that the data is placed into the @var{.lbss} section instead of
612 the @var{.bss} section @ref{Comm}.
614 The directive is intended to be used for data which requires a large
615 amount of space, and it is only available for ELF based x86_64
618 @cindex @code{value} directive
619 @item .value @var{expression} [, @var{expression}]
620 This directive behaves in the same way as the @code{.short} directive,
621 taking a series of comma separated expressions and storing them as
622 two-byte wide values into the current section.
624 @cindex @code{insn} directive
625 @item .insn [@var{prefix}[,...]] [@var{encoding}] @var{major-opcode}[@code{+r}|@code{/@var{extension}}] [,@var{operand}[,...]]
626 This directive allows composing instructions which @code{@value{AS}}
627 may not know about yet, or which it has no way of expressing (which
628 can be the case for certain alternative encodings). It assumes certain
629 basic structure in how operands are encoded, and it also only
630 recognizes - with a few extensions as per below - operands otherwise
631 valid for instructions. Therefore there is no guarantee that
632 everything can be expressed (e.g. the original Intel Xeon Phi's MVEX
633 encodings cannot be expressed).
637 @var{prefix} expresses one or more opcode prefixes in the usual way.
638 Legacy encoding prefixes altering meaning (0x66, 0xF2, 0xF3) may be
639 specified as high byte of <major-opcode> (perhaps already including an
640 encoding space prefix). Note that there can only be one such prefix.
641 Segment overrides are better specified in the respective memory
642 operand, as long as there is one.
645 @var{encoding} is used to specify VEX, XOP, or EVEX encodings. The
646 syntax tries to resemble that used in documentation:
648 @item @code{VEX}[@code{.@var{len}}][@code{.@var{prefix}}][@code{.@var{space}}][@code{.@var{w}}]
649 @item @code{EVEX}[@code{.@var{len}}][@code{.@var{prefix}}][@code{.@var{space}}][@code{.@var{w}}]
650 @item @code{XOP}@var{space}[@code{.@var{len}}][@code{.@var{prefix}}][@code{.@var{w}}]
655 @item @var{len} can be @code{LIG}, @code{128}, @code{256}, or (EVEX
656 only) @code{512} as well as @code{L0} / @code{L1} for VEX / XOP and
657 @code{L0}...@code{L3} for EVEX
658 @item @var{prefix} can be @code{NP}, @code{66}, @code{F3}, or @code{F2}
659 @item @var{space} can be
661 @item @code{0f}, @code{0f38}, @code{0f3a}, or @code{M0}...@code{M31}
663 @item @code{08}...@code{1f} for XOP
664 @item @code{0f}, @code{0f38}, @code{0f3a}, or @code{M0}...@code{M15}
667 @item @var{w} can be @code{WIG}, @code{W0}, or @code{W1}
672 @item Omitted @var{len} means "infer from operand size" if there is at
673 least one sized vector operand, or @code{LIG} otherwise. (Obviously
674 @var{len} has to be omitted when there's EVEX rounding control
675 specified later in the operands.)
676 @item Omitted @var{prefix} means @code{NP}.
677 @item Omitted @var{space} (VEX/EVEX only) implies encoding space is
678 taken from @var{major-opcode}.
679 @item Omitted @var{w} means "infer from GPR operand size" in 64-bit
680 code if there is at least one GPR(-like) operand, or @code{WIG}
685 @var{major-opcode} is an absolute expression specifying the instruction
686 opcode. Legacy encoding prefixes altering encoding space (0x0f,
687 0x0f38, 0x0f3a) have to be specified as high byte(s) here.
688 "Degenerate" ModR/M bytes, as present in e.g. certain FPU opcodes or
689 sub-spaces like that of major opcode 0x0f01, generally want encoding as
690 immediate operand (such opcodes wouldn't normally have non-immediate
691 operands); in some cases it may be possible to also encode these as low
692 byte of the major opcode, but there are potential ambiguities. Also
693 note that after stripping encoding prefixes, the residual has to fit in
694 two bytes (16 bits). @code{+r} can be suffixed to the major opcode
695 expression to specify register-only encoding forms not using a ModR/M
696 byte. @code{/@var{extension}} can alternatively be suffixed to the
697 major opcode expression to specify an extension opcode, encoded in bits
698 3-5 of the ModR/M byte.
701 @var{operand} is an instruction operand expressed the usual way.
702 Register operands are primarily used to express register numbers as
703 encoded in ModR/M byte and REX/VEX/XOP/EVEX prefixes. In certain
704 cases the register type (really: size) is also used to derive other
705 encoding attributes, if these aren't specified explicitly. Note that
706 there is no consistency checking among operands, so entirely bogus
707 mixes of operands are possible. Note further that only operands
708 actually encoded in the instruction should be specified. Operands like
709 @samp{%cl} in shift/rotate instructions have to be omitted, or else
710 they'll be encoded as an ordinary (register) operand. Operand order
711 may also not match that of the actual instruction (see below).
714 Encoding of operands: While for a memory operand (of which there can be
715 only one) it is clear how to encode it in the resulting ModR/M byte,
716 register operands are encoded strictly in this order (operand counts do
717 not include immediate ones in the enumeration below, and if there was an
718 extension opcode specified it counts as a register operand; VEX.vvvv
719 is meant to cover XOP and EVEX as well):
722 @item VEX.vvvv for 1-register-operand VEX/XOP/EVEX insns,
723 @item ModR/M.rm, ModR/M.reg for 2-operand insns,
724 @item ModR/M.rm, VEX.vvvv, ModR/M.reg for 3-operand insns, and
725 @item Imm@{4,5@}, ModR/M.rm, VEX.vvvv, ModR/M.reg for 4-operand insns,
728 obviously with the ModR/M.rm slot skipped when there is a memory
729 operand, and obviously with the ModR/M.reg slot skipped when there is
730 an extension opcode. For Intel syntax of course the opposite order
731 applies. With @code{+r} (and hence no ModR/M) there can only be a
732 single register operand for legacy encodings. VEX and alike can have
733 two register operands, where the second (first in Intel syntax) would
736 Immediate operands (including immediate-like displacements, i.e. when
737 not part of ModR/M addressing) are emitted in the order specified,
738 regardless of AT&T or Intel syntax. Since it may not be possible to
739 infer the size of such immediates, they can be suffixed by
740 @code{@{:s@var{n}@}} or @code{@{:u@var{n}@}}, representing signed /
741 unsigned immediates of the given number of bits respectively. When
742 emitting such operands, the number of bits will be rounded up to the
743 smallest suitable of 8, 16, 32, or 64. Immediates wider than 32 bits
744 are permitted in 64-bit code only.
746 For EVEX encoding memory operands with a displacement need to know
747 Disp8 scaling size in order to use an 8-bit displacement. For many
748 instructions this can be inferred from the types of other operands
749 specified. In Intel syntax @samp{DWORD PTR} and alike can be used to
750 specify the respective size. In AT&T syntax the memory operands can
751 be suffixed by @code{@{:d@var{n}@}} to specify the size (in bytes).
752 This can be combined with an embedded broadcast specifier:
753 @samp{8(%eax)@{1to8:d8@}}.
755 @c FIXME: Document other x86 specific directives ? Eg: .code16gcc,
760 @section i386 Syntactical Considerations
762 * i386-Variations:: AT&T Syntax versus Intel Syntax
763 * i386-Chars:: Special Characters
766 @node i386-Variations
767 @subsection AT&T Syntax versus Intel Syntax
769 @cindex i386 intel_syntax pseudo op
770 @cindex intel_syntax pseudo op, i386
771 @cindex i386 att_syntax pseudo op
772 @cindex att_syntax pseudo op, i386
773 @cindex i386 syntax compatibility
774 @cindex syntax compatibility, i386
775 @cindex x86-64 intel_syntax pseudo op
776 @cindex intel_syntax pseudo op, x86-64
777 @cindex x86-64 att_syntax pseudo op
778 @cindex att_syntax pseudo op, x86-64
779 @cindex x86-64 syntax compatibility
780 @cindex syntax compatibility, x86-64
782 @code{@value{AS}} now supports assembly using Intel assembler syntax.
783 @code{.intel_syntax} selects Intel mode, and @code{.att_syntax} switches
784 back to the usual AT&T mode for compatibility with the output of
785 @code{@value{GCC}}. Either of these directives may have an optional
786 argument, @code{prefix}, or @code{noprefix} specifying whether registers
787 require a @samp{%} prefix. AT&T System V/386 assembler syntax is quite
788 different from Intel syntax. We mention these differences because
789 almost all 80386 documents use Intel syntax. Notable differences
790 between the two syntaxes are:
792 @cindex immediate operands, i386
793 @cindex i386 immediate operands
794 @cindex register operands, i386
795 @cindex i386 register operands
796 @cindex jump/call operands, i386
797 @cindex i386 jump/call operands
798 @cindex operand delimiters, i386
800 @cindex immediate operands, x86-64
801 @cindex x86-64 immediate operands
802 @cindex register operands, x86-64
803 @cindex x86-64 register operands
804 @cindex jump/call operands, x86-64
805 @cindex x86-64 jump/call operands
806 @cindex operand delimiters, x86-64
809 AT&T immediate operands are preceded by @samp{$}; Intel immediate
810 operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}).
811 AT&T register operands are preceded by @samp{%}; Intel register operands
812 are undelimited. AT&T absolute (as opposed to PC relative) jump/call
813 operands are prefixed by @samp{*}; they are undelimited in Intel syntax.
815 @cindex i386 source, destination operands
816 @cindex source, destination operands; i386
817 @cindex x86-64 source, destination operands
818 @cindex source, destination operands; x86-64
820 AT&T and Intel syntax use the opposite order for source and destination
821 operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The
822 @samp{source, dest} convention is maintained for compatibility with
823 previous Unix assemblers. Note that @samp{bound}, @samp{invlpga}, and
824 instructions with 2 immediate operands, such as the @samp{enter}
825 instruction, do @emph{not} have reversed order. @ref{i386-Bugs}.
827 @cindex mnemonic suffixes, i386
828 @cindex sizes operands, i386
829 @cindex i386 size suffixes
830 @cindex mnemonic suffixes, x86-64
831 @cindex sizes operands, x86-64
832 @cindex x86-64 size suffixes
834 In AT&T syntax the size of memory operands is determined from the last
835 character of the instruction mnemonic. Mnemonic suffixes of @samp{b},
836 @samp{w}, @samp{l} and @samp{q} specify byte (8-bit), word (16-bit), long
837 (32-bit) and quadruple word (64-bit) memory references. Mnemonic suffixes
838 of @samp{x}, @samp{y} and @samp{z} specify xmm (128-bit vector), ymm
839 (256-bit vector) and zmm (512-bit vector) memory references, only when there's
840 no other way to disambiguate an instruction. Intel syntax accomplishes this by
841 prefixing memory operands (@emph{not} the instruction mnemonics) with
842 @samp{byte ptr}, @samp{word ptr}, @samp{dword ptr}, @samp{qword ptr},
843 @samp{xmmword ptr}, @samp{ymmword ptr} and @samp{zmmword ptr}. Thus, Intel
844 syntax @samp{mov al, byte ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T
845 syntax. In Intel syntax, @samp{fword ptr}, @samp{tbyte ptr} and
846 @samp{oword ptr} specify 48-bit, 80-bit and 128-bit memory references.
848 In 64-bit code, @samp{movabs} can be used to encode the @samp{mov}
849 instruction with the 64-bit displacement or immediate operand.
851 @cindex return instructions, i386
852 @cindex i386 jump, call, return
853 @cindex return instructions, x86-64
854 @cindex x86-64 jump, call, return
856 Immediate form long jumps and calls are
857 @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
859 @samp{call/jmp far @var{section}:@var{offset}}. Also, the far return
861 is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
862 @samp{ret far @var{stack-adjust}}.
864 @cindex sections, i386
865 @cindex i386 sections
866 @cindex sections, x86-64
867 @cindex x86-64 sections
869 The AT&T assembler does not provide support for multiple section
870 programs. Unix style systems expect all programs to be single sections.
874 @subsection Special Characters
876 @cindex line comment character, i386
877 @cindex i386 line comment character
878 The presence of a @samp{#} appearing anywhere on a line indicates the
879 start of a comment that extends to the end of that line.
881 If a @samp{#} appears as the first character of a line then the whole
882 line is treated as a comment, but in this case the line can also be a
883 logical line number directive (@pxref{Comments}) or a preprocessor
884 control command (@pxref{Preprocessing}).
886 If the @option{--divide} command-line option has not been specified
887 then the @samp{/} character appearing anywhere on a line also
888 introduces a line comment.
890 @cindex line separator, i386
891 @cindex statement separator, i386
892 @cindex i386 line separator
893 The @samp{;} character can be used to separate statements on the same
897 @section i386-Mnemonics
898 @subsection Instruction Naming
900 @cindex i386 instruction naming
901 @cindex instruction naming, i386
902 @cindex x86-64 instruction naming
903 @cindex instruction naming, x86-64
905 Instruction mnemonics are suffixed with one character modifiers which
906 specify the size of operands. The letters @samp{b}, @samp{w}, @samp{l}
907 and @samp{q} specify byte, word, long and quadruple word operands. If
908 no suffix is specified by an instruction then @code{@value{AS}} tries to
909 fill in the missing suffix based on the destination register operand
910 (the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent
911 to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to
912 @samp{movw $1, bx}. Note that this is incompatible with the AT&T Unix
913 assembler which assumes that a missing mnemonic suffix implies long
914 operand size. (This incompatibility does not affect compiler output
915 since compilers always explicitly specify the mnemonic suffix.)
917 When there is no sizing suffix and no (suitable) register operands to
918 deduce the size of memory operands, with a few exceptions and where long
919 operand size is possible in the first place, operand size will default
920 to long in 32- and 64-bit modes. Similarly it will default to short in
921 16-bit mode. Noteworthy exceptions are
925 Instructions with an implicit on-stack operand as well as branches,
926 which default to quad in 64-bit mode.
929 Sign- and zero-extending moves, which default to byte size source
933 Floating point insns with integer operands, which default to short (for
934 perhaps historical reasons).
937 CRC32 with a 64-bit destination, which defaults to a quad source
942 @cindex encoding options, i386
943 @cindex encoding options, x86-64
945 Different encoding options can be specified via pseudo prefixes:
949 @samp{@{disp8@}} -- prefer 8-bit displacement.
952 @samp{@{disp32@}} -- prefer 32-bit displacement.
955 @samp{@{disp16@}} -- prefer 16-bit displacement.
958 @samp{@{load@}} -- prefer load-form instruction.
961 @samp{@{store@}} -- prefer store-form instruction.
964 @samp{@{vex@}} -- encode with VEX prefix.
967 @samp{@{vex3@}} -- encode with 3-byte VEX prefix.
970 @samp{@{evex@}} -- encode with EVEX prefix.
973 @samp{@{rex@}} -- prefer REX prefix for integer and legacy vector
974 instructions (x86-64 only). Note that this differs from the @samp{rex}
975 prefix which generates REX prefix unconditionally.
978 @samp{@{nooptimize@}} -- disable instruction size optimization.
981 Mnemonics of Intel VNNI/IFMA instructions are encoded with the EVEX prefix
982 by default. The pseudo @samp{@{vex@}} prefix can be used to encode
983 mnemonics of Intel VNNI/IFMA instructions with the VEX prefix.
985 @cindex conversion instructions, i386
986 @cindex i386 conversion instructions
987 @cindex conversion instructions, x86-64
988 @cindex x86-64 conversion instructions
989 The Intel-syntax conversion instructions
993 @samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax},
996 @samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax},
999 @samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax},
1002 @samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax},
1005 @samp{cdqe} --- sign-extend dword in @samp{%eax} to quad in @samp{%rax}
1009 @samp{cqo} --- sign-extend quad in @samp{%rax} to octuple in
1010 @samp{%rdx:%rax} (x86-64 only),
1014 are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, @samp{cltd}, @samp{cltq}, and
1015 @samp{cqto} in AT&T naming. @code{@value{AS}} accepts either naming for these
1018 @cindex extension instructions, i386
1019 @cindex i386 extension instructions
1020 @cindex extension instructions, x86-64
1021 @cindex x86-64 extension instructions
1022 The Intel-syntax extension instructions
1026 @samp{movsx} --- sign-extend @samp{reg8/mem8} to @samp{reg16}.
1029 @samp{movsx} --- sign-extend @samp{reg8/mem8} to @samp{reg32}.
1032 @samp{movsx} --- sign-extend @samp{reg8/mem8} to @samp{reg64}
1036 @samp{movsx} --- sign-extend @samp{reg16/mem16} to @samp{reg32}
1039 @samp{movsx} --- sign-extend @samp{reg16/mem16} to @samp{reg64}
1043 @samp{movsxd} --- sign-extend @samp{reg32/mem32} to @samp{reg64}
1047 @samp{movzx} --- zero-extend @samp{reg8/mem8} to @samp{reg16}.
1050 @samp{movzx} --- zero-extend @samp{reg8/mem8} to @samp{reg32}.
1053 @samp{movzx} --- zero-extend @samp{reg8/mem8} to @samp{reg64}
1057 @samp{movzx} --- zero-extend @samp{reg16/mem16} to @samp{reg32}
1060 @samp{movzx} --- zero-extend @samp{reg16/mem16} to @samp{reg64}
1065 are called @samp{movsbw/movsxb/movsx}, @samp{movsbl/movsxb/movsx},
1066 @samp{movsbq/movsxb/movsx}, @samp{movswl/movsxw}, @samp{movswq/movsxw},
1067 @samp{movslq/movsxl}, @samp{movzbw/movzxb/movzx},
1068 @samp{movzbl/movzxb/movzx}, @samp{movzbq/movzxb/movzx},
1069 @samp{movzwl/movzxw} and @samp{movzwq/movzxw} in AT&T syntax.
1071 @cindex jump instructions, i386
1072 @cindex call instructions, i386
1073 @cindex jump instructions, x86-64
1074 @cindex call instructions, x86-64
1075 Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
1076 AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
1079 @subsection AT&T Mnemonic versus Intel Mnemonic
1081 @cindex i386 mnemonic compatibility
1082 @cindex mnemonic compatibility, i386
1084 @code{@value{AS}} supports assembly using Intel mnemonic.
1085 @code{.intel_mnemonic} selects Intel mnemonic with Intel syntax, and
1086 @code{.att_mnemonic} switches back to the usual AT&T mnemonic with AT&T
1087 syntax for compatibility with the output of @code{@value{GCC}}.
1088 Several x87 instructions, @samp{fadd}, @samp{fdiv}, @samp{fdivp},
1089 @samp{fdivr}, @samp{fdivrp}, @samp{fmul}, @samp{fsub}, @samp{fsubp},
1090 @samp{fsubr} and @samp{fsubrp}, are implemented in AT&T System V/386
1091 assembler with different mnemonics from those in Intel IA32 specification.
1092 @code{@value{GCC}} generates those instructions with AT&T mnemonic.
1095 @item @samp{movslq} with AT&T mnemonic only accepts 64-bit destination
1096 register. @samp{movsxd} should be used to encode 16-bit or 32-bit
1097 destination register with both AT&T and Intel mnemonics.
1101 @section Register Naming
1103 @cindex i386 registers
1104 @cindex registers, i386
1105 @cindex x86-64 registers
1106 @cindex registers, x86-64
1107 Register operands are always prefixed with @samp{%}. The 80386 registers
1112 the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx},
1113 @samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the
1114 frame pointer), and @samp{%esp} (the stack pointer).
1117 the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx},
1118 @samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}.
1121 the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh},
1122 @samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These
1123 are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx},
1124 @samp{%cx}, and @samp{%dx})
1127 the 6 section registers @samp{%cs} (code section), @samp{%ds}
1128 (data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs},
1132 the 5 processor control registers @samp{%cr0}, @samp{%cr2},
1133 @samp{%cr3}, @samp{%cr4}, and @samp{%cr8}.
1136 the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2},
1137 @samp{%db3}, @samp{%db6}, and @samp{%db7}.
1140 the 2 test registers @samp{%tr6} and @samp{%tr7}.
1143 the 8 floating point register stack @samp{%st} or equivalently
1144 @samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)},
1145 @samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}.
1146 These registers are overloaded by 8 MMX registers @samp{%mm0},
1147 @samp{%mm1}, @samp{%mm2}, @samp{%mm3}, @samp{%mm4}, @samp{%mm5},
1148 @samp{%mm6} and @samp{%mm7}.
1151 the 8 128-bit SSE registers registers @samp{%xmm0}, @samp{%xmm1}, @samp{%xmm2},
1152 @samp{%xmm3}, @samp{%xmm4}, @samp{%xmm5}, @samp{%xmm6} and @samp{%xmm7}.
1155 The AMD x86-64 architecture extends the register set by:
1159 enhancing the 8 32-bit registers to 64-bit: @samp{%rax} (the
1160 accumulator), @samp{%rbx}, @samp{%rcx}, @samp{%rdx}, @samp{%rdi},
1161 @samp{%rsi}, @samp{%rbp} (the frame pointer), @samp{%rsp} (the stack
1165 the 8 extended registers @samp{%r8}--@samp{%r15}.
1168 the 8 32-bit low ends of the extended registers: @samp{%r8d}--@samp{%r15d}.
1171 the 8 16-bit low ends of the extended registers: @samp{%r8w}--@samp{%r15w}.
1174 the 8 8-bit low ends of the extended registers: @samp{%r8b}--@samp{%r15b}.
1177 the 4 8-bit registers: @samp{%sil}, @samp{%dil}, @samp{%bpl}, @samp{%spl}.
1180 the 8 debug registers: @samp{%db8}--@samp{%db15}.
1183 the 8 128-bit SSE registers: @samp{%xmm8}--@samp{%xmm15}.
1186 With the AVX extensions more registers were made available:
1191 the 16 256-bit SSE @samp{%ymm0}--@samp{%ymm15} (only the first 8
1192 available in 32-bit mode). The bottom 128 bits are overlaid with the
1193 @samp{xmm0}--@samp{xmm15} registers.
1197 The AVX512 extensions added the following registers:
1202 the 32 512-bit registers @samp{%zmm0}--@samp{%zmm31} (only the first 8
1203 available in 32-bit mode). The bottom 128 bits are overlaid with the
1204 @samp{%xmm0}--@samp{%xmm31} registers and the first 256 bits are
1205 overlaid with the @samp{%ymm0}--@samp{%ymm31} registers.
1208 the 8 mask registers @samp{%k0}--@samp{%k7}.
1213 @section Instruction Prefixes
1215 @cindex i386 instruction prefixes
1216 @cindex instruction prefixes, i386
1217 @cindex prefixes, i386
1218 Instruction prefixes are used to modify the following instruction. They
1219 are used to repeat string instructions, to provide section overrides, to
1220 perform bus lock operations, and to change operand and address sizes.
1221 (Most instructions that normally operate on 32-bit operands will use
1222 16-bit operands if the instruction has an ``operand size'' prefix.)
1223 Instruction prefixes are best written on the same line as the instruction
1224 they act upon. For example, the @samp{scas} (scan string) instruction is
1228 repne scas %es:(%edi),%al
1231 You may also place prefixes on the lines immediately preceding the
1232 instruction, but this circumvents checks that @code{@value{AS}} does
1233 with prefixes, and will not work with all prefixes.
1235 Here is a list of instruction prefixes:
1237 @cindex section override prefixes, i386
1240 Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es},
1241 @samp{fs}, @samp{gs}. These are automatically added by specifying
1242 using the @var{section}:@var{memory-operand} form for memory references.
1244 @cindex size prefixes, i386
1246 Operand/Address size prefixes @samp{data16} and @samp{addr16}
1247 change 32-bit operands/addresses into 16-bit operands/addresses,
1248 while @samp{data32} and @samp{addr32} change 16-bit ones (in a
1249 @code{.code16} section) into 32-bit operands/addresses. These prefixes
1250 @emph{must} appear on the same line of code as the instruction they
1251 modify. For example, in a 16-bit @code{.code16} section, you might
1258 @cindex bus lock prefixes, i386
1259 @cindex inhibiting interrupts, i386
1261 The bus lock prefix @samp{lock} inhibits interrupts during execution of
1262 the instruction it precedes. (This is only valid with certain
1263 instructions; see a 80386 manual for details).
1265 @cindex coprocessor wait, i386
1267 The wait for coprocessor prefix @samp{wait} waits for the coprocessor to
1268 complete the current instruction. This should never be needed for the
1269 80386/80387 combination.
1271 @cindex repeat prefixes, i386
1273 The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added
1274 to string instructions to make them repeat @samp{%ecx} times (@samp{%cx}
1275 times if the current address size is 16-bits).
1276 @cindex REX prefixes, i386
1278 The @samp{rex} family of prefixes is used by x86-64 to encode
1279 extensions to i386 instruction set. The @samp{rex} prefix has four
1280 bits --- an operand size overwrite (@code{64}) used to change operand size
1281 from 32-bit to 64-bit and X, Y and Z extensions bits used to extend the
1284 You may write the @samp{rex} prefixes directly. The @samp{rex64xyz}
1285 instruction emits @samp{rex} prefix with all the bits set. By omitting
1286 the @code{64}, @code{x}, @code{y} or @code{z} you may write other
1287 prefixes as well. Normally, there is no need to write the prefixes
1288 explicitly, since gas will automatically generate them based on the
1289 instruction operands.
1293 @section Memory References
1295 @cindex i386 memory references
1296 @cindex memory references, i386
1297 @cindex x86-64 memory references
1298 @cindex memory references, x86-64
1299 An Intel syntax indirect memory reference of the form
1302 @var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}]
1306 is translated into the AT&T syntax
1309 @var{section}:@var{disp}(@var{base}, @var{index}, @var{scale})
1313 where @var{base} and @var{index} are the optional 32-bit base and
1314 index registers, @var{disp} is the optional displacement, and
1315 @var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index}
1316 to calculate the address of the operand. If no @var{scale} is
1317 specified, @var{scale} is taken to be 1. @var{section} specifies the
1318 optional section register for the memory operand, and may override the
1319 default section register (see a 80386 manual for section register
1320 defaults). Note that section overrides in AT&T syntax @emph{must}
1321 be preceded by a @samp{%}. If you specify a section override which
1322 coincides with the default section register, @code{@value{AS}} does @emph{not}
1323 output any section register override prefixes to assemble the given
1324 instruction. Thus, section overrides can be specified to emphasize which
1325 section register is used for a given memory operand.
1327 Here are some examples of Intel and AT&T style memory references:
1330 @item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]}
1331 @var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is
1332 missing, and the default section is used (@samp{%ss} for addressing with
1333 @samp{%ebp} as the base register). @var{index}, @var{scale} are both missing.
1335 @item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]}
1336 @var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is
1337 @samp{foo}. All other fields are missing. The section register here
1338 defaults to @samp{%ds}.
1340 @item AT&T: @samp{foo(,1)}; Intel @samp{[foo]}
1341 This uses the value pointed to by @samp{foo} as a memory operand.
1342 Note that @var{base} and @var{index} are both missing, but there is only
1343 @emph{one} @samp{,}. This is a syntactic exception.
1345 @item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo}
1346 This selects the contents of the variable @samp{foo} with section
1347 register @var{section} being @samp{%gs}.
1350 Absolute (as opposed to PC relative) call and jump operands must be
1351 prefixed with @samp{*}. If no @samp{*} is specified, @code{@value{AS}}
1352 always chooses PC relative addressing for jump/call labels.
1354 Any instruction that has a memory operand, but no register operand,
1355 @emph{must} specify its size (byte, word, long, or quadruple) with an
1356 instruction mnemonic suffix (@samp{b}, @samp{w}, @samp{l} or @samp{q},
1359 The x86-64 architecture adds an RIP (instruction pointer relative)
1360 addressing. This addressing mode is specified by using @samp{rip} as a
1361 base register. Only constant offsets are valid. For example:
1364 @item AT&T: @samp{1234(%rip)}, Intel: @samp{[rip + 1234]}
1365 Points to the address 1234 bytes past the end of the current
1368 @item AT&T: @samp{symbol(%rip)}, Intel: @samp{[rip + symbol]}
1369 Points to the @code{symbol} in RIP relative way, this is shorter than
1370 the default absolute addressing.
1373 Other addressing modes remain unchanged in x86-64 architecture, except
1374 registers used are 64-bit instead of 32-bit.
1377 @section Handling of Jump Instructions
1379 @cindex jump optimization, i386
1380 @cindex i386 jump optimization
1381 @cindex jump optimization, x86-64
1382 @cindex x86-64 jump optimization
1383 Jump instructions are always optimized to use the smallest possible
1384 displacements. This is accomplished by using byte (8-bit) displacement
1385 jumps whenever the target is sufficiently close. If a byte displacement
1386 is insufficient a long displacement is used. We do not support
1387 word (16-bit) displacement jumps in 32-bit mode (i.e. prefixing the jump
1388 instruction with the @samp{data16} instruction prefix), since the 80386
1389 insists upon masking @samp{%eip} to 16 bits after the word displacement
1390 is added. (See also @pxref{i386-Arch})
1392 Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz},
1393 @samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in byte
1394 displacements, so that if you use these instructions (@code{@value{GCC}} does
1395 not use them) you may get an error message (and incorrect code). The AT&T
1396 80386 assembler tries to get around this problem by expanding @samp{jcxz foo}
1407 @section Floating Point
1409 @cindex i386 floating point
1410 @cindex floating point, i386
1411 @cindex x86-64 floating point
1412 @cindex floating point, x86-64
1413 All 80387 floating point types except packed BCD are supported.
1414 (BCD support may be added without much difficulty). These data
1415 types are 16-, 32-, and 64- bit integers, and single (32-bit),
1416 double (64-bit), and extended (80-bit) precision floating point.
1417 Each supported type has an instruction mnemonic suffix and a constructor
1418 associated with it. Instruction mnemonic suffixes specify the operand's
1419 data type. Constructors build these data types into memory.
1421 @cindex @code{float} directive, i386
1422 @cindex @code{single} directive, i386
1423 @cindex @code{double} directive, i386
1424 @cindex @code{tfloat} directive, i386
1425 @cindex @code{hfloat} directive, i386
1426 @cindex @code{bfloat16} directive, i386
1427 @cindex @code{float} directive, x86-64
1428 @cindex @code{single} directive, x86-64
1429 @cindex @code{double} directive, x86-64
1430 @cindex @code{tfloat} directive, x86-64
1431 @cindex @code{hfloat} directive, x86-64
1432 @cindex @code{bfloat16} directive, x86-64
1435 Floating point constructors are @samp{.float} or @samp{.single},
1436 @samp{.double}, @samp{.tfloat}, @samp{.hfloat}, and @samp{.bfloat16} for 32-,
1437 64-, 80-, and 16-bit (two flavors) formats respectively. The former three
1438 correspond to instruction mnemonic suffixes @samp{s}, @samp{l}, and @samp{t}.
1439 @samp{t} stands for 80-bit (ten byte) real. The 80387 only supports this
1440 format via the @samp{fldt} (load 80-bit real to stack top) and @samp{fstpt}
1441 (store 80-bit real and pop stack) instructions.
1443 @cindex @code{word} directive, i386
1444 @cindex @code{long} directive, i386
1445 @cindex @code{int} directive, i386
1446 @cindex @code{quad} directive, i386
1447 @cindex @code{word} directive, x86-64
1448 @cindex @code{long} directive, x86-64
1449 @cindex @code{int} directive, x86-64
1450 @cindex @code{quad} directive, x86-64
1452 Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and
1453 @samp{.quad} for the 16-, 32-, and 64-bit integer formats. The
1454 corresponding instruction mnemonic suffixes are @samp{s} (short),
1455 @samp{l} (long), and @samp{q} (quad). As with the 80-bit real format,
1456 the 64-bit @samp{q} format is only present in the @samp{fildq} (load
1457 quad integer to stack top) and @samp{fistpq} (store quad integer and pop
1458 stack) instructions.
1461 Register to register operations should not use instruction mnemonic suffixes.
1462 @samp{fstl %st, %st(1)} will give a warning, and be assembled as if you
1463 wrote @samp{fst %st, %st(1)}, since all register to register operations
1464 use 80-bit floating point operands. (Contrast this with @samp{fstl %st, mem},
1465 which converts @samp{%st} from 80-bit to 64-bit floating point format,
1466 then stores the result in the 4 byte location @samp{mem})
1469 @section Intel's MMX and AMD's 3DNow! SIMD Operations
1472 @cindex 3DNow!, i386
1475 @cindex 3DNow!, x86-64
1476 @cindex SIMD, x86-64
1478 @code{@value{AS}} supports Intel's MMX instruction set (SIMD
1479 instructions for integer data), available on Intel's Pentium MMX
1480 processors and Pentium II processors, AMD's K6 and K6-2 processors,
1481 Cyrix' M2 processor, and probably others. It also supports AMD's 3DNow!@:
1482 instruction set (SIMD instructions for 32-bit floating point data)
1483 available on AMD's K6-2 processor and possibly others in the future.
1485 Currently, @code{@value{AS}} does not support Intel's floating point
1488 The eight 64-bit MMX operands, also used by 3DNow!, are called @samp{%mm0},
1489 @samp{%mm1}, ... @samp{%mm7}. They contain eight 8-bit integers, four
1490 16-bit integers, two 32-bit integers, one 64-bit integer, or two 32-bit
1491 floating point values. The MMX registers cannot be used at the same time
1492 as the floating point stack.
1494 See Intel and AMD documentation, keeping in mind that the operand order in
1495 instructions is reversed from the Intel syntax.
1498 @section AMD's Lightweight Profiling Instructions
1503 @code{@value{AS}} supports AMD's Lightweight Profiling (LWP)
1504 instruction set, available on AMD's Family 15h (Orochi) processors.
1506 LWP enables applications to collect and manage performance data, and
1507 react to performance events. The collection of performance data
1508 requires no context switches. LWP runs in the context of a thread and
1509 so several counters can be used independently across multiple threads.
1510 LWP can be used in both 64-bit and legacy 32-bit modes.
1512 For detailed information on the LWP instruction set, see the
1513 @cite{AMD Lightweight Profiling Specification} available at
1514 @uref{http://developer.amd.com/cpu/LWP,Lightweight Profiling Specification}.
1517 @section Bit Manipulation Instructions
1522 @code{@value{AS}} supports the Bit Manipulation (BMI) instruction set.
1524 BMI instructions provide several instructions implementing individual
1525 bit manipulation operations such as isolation, masking, setting, or
1528 @c Need to add a specification citation here when available.
1531 @section AMD's Trailing Bit Manipulation Instructions
1536 @code{@value{AS}} supports AMD's Trailing Bit Manipulation (TBM)
1537 instruction set, available on AMD's BDVER2 processors (Trinity and
1540 TBM instructions provide instructions implementing individual bit
1541 manipulation operations such as isolating, masking, setting, resetting,
1542 complementing, and operations on trailing zeros and ones.
1544 @c Need to add a specification citation here when available.
1547 @section Writing 16-bit Code
1549 @cindex i386 16-bit code
1550 @cindex 16-bit code, i386
1551 @cindex real-mode code, i386
1552 @cindex @code{code16gcc} directive, i386
1553 @cindex @code{code16} directive, i386
1554 @cindex @code{code32} directive, i386
1555 @cindex @code{code64} directive, i386
1556 @cindex @code{code64} directive, x86-64
1557 While @code{@value{AS}} normally writes only ``pure'' 32-bit i386 code
1558 or 64-bit x86-64 code depending on the default configuration,
1559 it also supports writing code to run in real mode or in 16-bit protected
1560 mode code segments. To do this, put a @samp{.code16} or
1561 @samp{.code16gcc} directive before the assembly language instructions to
1562 be run in 16-bit mode. You can switch @code{@value{AS}} to writing
1563 32-bit code with the @samp{.code32} directive or 64-bit code with the
1564 @samp{.code64} directive.
1566 @samp{.code16gcc} provides experimental support for generating 16-bit
1567 code from gcc, and differs from @samp{.code16} in that @samp{call},
1568 @samp{ret}, @samp{enter}, @samp{leave}, @samp{push}, @samp{pop},
1569 @samp{pusha}, @samp{popa}, @samp{pushf}, and @samp{popf} instructions
1570 default to 32-bit size. This is so that the stack pointer is
1571 manipulated in the same way over function calls, allowing access to
1572 function parameters at the same stack offsets as in 32-bit mode.
1573 @samp{.code16gcc} also automatically adds address size prefixes where
1574 necessary to use the 32-bit addressing modes that gcc generates.
1576 The code which @code{@value{AS}} generates in 16-bit mode will not
1577 necessarily run on a 16-bit pre-80386 processor. To write code that
1578 runs on such a processor, you must refrain from using @emph{any} 32-bit
1579 constructs which require @code{@value{AS}} to output address or operand
1582 Note that writing 16-bit code instructions by explicitly specifying a
1583 prefix or an instruction mnemonic suffix within a 32-bit code section
1584 generates different machine instructions than those generated for a
1585 16-bit code segment. In a 32-bit code section, the following code
1586 generates the machine opcode bytes @samp{66 6a 04}, which pushes the
1587 value @samp{4} onto the stack, decrementing @samp{%esp} by 2.
1593 The same code in a 16-bit code section would generate the machine
1594 opcode bytes @samp{6a 04} (i.e., without the operand size prefix), which
1595 is correct since the processor default operand size is assumed to be 16
1596 bits in a 16-bit code section.
1599 @section Specifying CPU Architecture
1601 @cindex arch directive, i386
1602 @cindex i386 arch directive
1603 @cindex arch directive, x86-64
1604 @cindex x86-64 arch directive
1606 @code{@value{AS}} may be told to assemble for a particular CPU
1607 (sub-)architecture with the @code{.arch @var{cpu_type}} directive. This
1608 directive enables a warning when gas detects an instruction that is not
1609 supported on the CPU specified. The choices for @var{cpu_type} are:
1611 @multitable @columnfractions .20 .20 .20 .20
1612 @item @samp{default} @tab @samp{push} @tab @samp{pop}
1613 @item @samp{i8086} @tab @samp{i186} @tab @samp{i286} @tab @samp{i386}
1614 @item @samp{i486} @tab @samp{i586} @tab @samp{i686} @tab @samp{pentium}
1615 @item @samp{pentiumpro} @tab @samp{pentiumii} @tab @samp{pentiumiii} @tab @samp{pentium4}
1616 @item @samp{prescott} @tab @samp{nocona} @tab @samp{core} @tab @samp{core2}
1617 @item @samp{corei7} @tab @samp{iamcu}
1618 @item @samp{k6} @tab @samp{k6_2} @tab @samp{athlon} @tab @samp{k8}
1619 @item @samp{amdfam10} @tab @samp{bdver1} @tab @samp{bdver2} @tab @samp{bdver3}
1620 @item @samp{bdver4} @tab @samp{znver1} @tab @samp{znver2} @tab @samp{znver3}
1621 @item @samp{znver4} @tab @samp{btver1} @tab @samp{btver2} @tab @samp{generic32}
1622 @item @samp{generic64} @tab @samp{.cmov} @tab @samp{.fxsr} @tab @samp{.mmx}
1623 @item @samp{.sse} @tab @samp{.sse2} @tab @samp{.sse3} @tab @samp{.sse4a}
1624 @item @samp{.ssse3} @tab @samp{.sse4.1} @tab @samp{.sse4.2} @tab @samp{.sse4}
1625 @item @samp{.avx} @tab @samp{.vmx} @tab @samp{.smx} @tab @samp{.ept}
1626 @item @samp{.clflush} @tab @samp{.movbe} @tab @samp{.xsave} @tab @samp{.xsaveopt}
1627 @item @samp{.aes} @tab @samp{.pclmul} @tab @samp{.fma} @tab @samp{.fsgsbase}
1628 @item @samp{.rdrnd} @tab @samp{.f16c} @tab @samp{.avx2} @tab @samp{.bmi2}
1629 @item @samp{.lzcnt} @tab @samp{.popcnt} @tab @samp{.invpcid} @tab @samp{.vmfunc}
1630 @item @samp{.monitor} @tab @samp{.hle} @tab @samp{.rtm} @tab @samp{.tsx}
1631 @item @samp{.lahf_sahf} @tab @samp{.adx} @tab @samp{.rdseed} @tab @samp{.prfchw}
1632 @item @samp{.smap} @tab @samp{.mpx} @tab @samp{.sha} @tab @samp{.prefetchwt1}
1633 @item @samp{.clflushopt} @tab @samp{.xsavec} @tab @samp{.xsaves} @tab @samp{.se1}
1634 @item @samp{.avx512f} @tab @samp{.avx512cd} @tab @samp{.avx512er} @tab @samp{.avx512pf}
1635 @item @samp{.avx512vl} @tab @samp{.avx512bw} @tab @samp{.avx512dq} @tab @samp{.avx512ifma}
1636 @item @samp{.avx512vbmi} @tab @samp{.avx512_4fmaps} @tab @samp{.avx512_4vnniw}
1637 @item @samp{.avx512_vpopcntdq} @tab @samp{.avx512_vbmi2} @tab @samp{.avx512_vnni}
1638 @item @samp{.avx512_bitalg} @tab @samp{.avx512_bf16} @tab @samp{.avx512_vp2intersect}
1639 @item @samp{.tdx} @tab @samp{.avx_vnni} @tab @samp{.avx512_fp16}
1640 @item @samp{.clwb} @tab @samp{.rdpid} @tab @samp{.ptwrite} @tab @samp{.ibt}
1641 @item @samp{.prefetchi} @tab @samp{.avx_ifma} @tab @samp{.avx_vnni_int8}
1642 @item @samp{.cmpccxadd} @tab @samp{.wrmsrns} @tab @samp{.msrlist}
1643 @item @samp{.avx_ne_convert} @tab @samp{.rao_int} @tab @samp{.fred} @tab @samp{.lkgs}
1644 @item @samp{.avx_vnni_int16} @tab @samp{.sha512} @tab @samp{.sm3} @tab @samp{.sm4}
1645 @item @samp{.pbndkb}
1646 @item @samp{.wbnoinvd} @tab @samp{.pconfig} @tab @samp{.waitpkg} @tab @samp{.cldemote}
1647 @item @samp{.shstk} @tab @samp{.gfni} @tab @samp{.vaes} @tab @samp{.vpclmulqdq}
1648 @item @samp{.movdiri} @tab @samp{.movdir64b} @tab @samp{.enqcmd} @tab @samp{.tsxldtrk}
1649 @item @samp{.amx_int8} @tab @samp{.amx_bf16} @tab @samp{.amx_fp16}
1650 @item @samp{.amx_complex} @tab @samp{.amx_tile}
1651 @item @samp{.kl} @tab @samp{.widekl} @tab @samp{.uintr} @tab @samp{.hreset}
1652 @item @samp{.3dnow} @tab @samp{.3dnowa} @tab @samp{.sse4a} @tab @samp{.sse5}
1653 @item @samp{.syscall} @tab @samp{.rdtscp} @tab @samp{.svme}
1654 @item @samp{.lwp} @tab @samp{.fma4} @tab @samp{.xop} @tab @samp{.cx16}
1655 @item @samp{.padlock} @tab @samp{.clzero} @tab @samp{.mwaitx} @tab @samp{.rdpru}
1656 @item @samp{.mcommit} @tab @samp{.sev_es} @tab @samp{.snp} @tab @samp{.invlpgb}
1657 @item @samp{.tlbsync}
1660 Apart from the warning, there are only two other effects on
1661 @code{@value{AS}} operation; Firstly, if you specify a CPU other than
1662 @samp{i486}, then shift by one instructions such as @samp{sarl $1, %eax}
1663 will automatically use a two byte opcode sequence. The larger three
1664 byte opcode sequence is used on the 486 (and when no architecture is
1665 specified) because it executes faster on the 486. Note that you can
1666 explicitly request the two byte opcode by writing @samp{sarl %eax}.
1667 Secondly, if you specify @samp{i8086}, @samp{i186}, or @samp{i286},
1668 @emph{and} @samp{.code16} or @samp{.code16gcc} then byte offset
1669 conditional jumps will be promoted when necessary to a two instruction
1670 sequence consisting of a conditional jump of the opposite sense around
1671 an unconditional jump to the target.
1673 Note that the sub-architecture specifiers (starting with a dot) can be prefixed
1674 with @code{no} to revoke the respective (and any dependent) functionality.
1676 Following the CPU architecture (but not a sub-architecture, which are those
1677 starting with a dot), you may specify @samp{jumps} or @samp{nojumps} to
1678 control automatic promotion of conditional jumps. @samp{jumps} is the
1679 default, and enables jump promotion; All external jumps will be of the long
1680 variety, and file-local jumps will be promoted as necessary.
1681 (@pxref{i386-Jumps}) @samp{nojumps} leaves external conditional jumps as
1682 byte offset jumps, and warns about file-local conditional jumps that
1683 @code{@value{AS}} promotes.
1684 Unconditional jumps are treated as for @samp{jumps}.
1693 @section AMD64 ISA vs. Intel64 ISA
1695 There are some discrepancies between AMD64 and Intel64 ISAs.
1698 @item For @samp{movsxd} with 16-bit destination register, AMD64
1699 supports 32-bit source operand and Intel64 supports 16-bit source
1702 @item For far branches (with explicit memory operand), both ISAs support
1703 32- and 16-bit operand size. Intel64 additionally supports 64-bit
1704 operand size, encoded as @samp{ljmpq} and @samp{lcallq} in AT&T syntax
1705 and with an explicit @samp{tbyte ptr} operand size specifier in Intel
1708 @item @samp{lfs}, @samp{lgs}, and @samp{lss} similarly allow for 16-
1709 and 32-bit operand size (32- and 48-bit memory operand) in both ISAs,
1710 while Intel64 additionally supports 64-bit operand sise (80-bit memory
1716 @section AT&T Syntax bugs
1718 The UnixWare assembler, and probably other AT&T derived ix86 Unix
1719 assemblers, generate floating point instructions with reversed source
1720 and destination registers in certain cases. Unfortunately, gcc and
1721 possibly many other programs use this reversed syntax, so we're stuck
1730 results in @samp{%st(3)} being updated to @samp{%st - %st(3)} rather
1731 than the expected @samp{%st(3) - %st}. This happens with all the
1732 non-commutative arithmetic floating point operations with two register
1733 operands where the source register is @samp{%st} and the destination
1734 register is @samp{%st(i)}.
1739 @cindex i386 @code{mul}, @code{imul} instructions
1740 @cindex @code{mul} instruction, i386
1741 @cindex @code{imul} instruction, i386
1742 @cindex @code{mul} instruction, x86-64
1743 @cindex @code{imul} instruction, x86-64
1744 There is some trickery concerning the @samp{mul} and @samp{imul}
1745 instructions that deserves mention. The 16-, 32-, 64- and 128-bit expanding
1746 multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5
1747 for @samp{imul}) can be output only in the one operand form. Thus,
1748 @samp{imul %ebx, %eax} does @emph{not} select the expanding multiply;
1749 the expanding multiply would clobber the @samp{%edx} register, and this
1750 would confuse @code{@value{GCC}} output. Use @samp{imul %ebx} to get the
1751 64-bit product in @samp{%edx:%eax}.
1753 We have added a two operand form of @samp{imul} when the first operand
1754 is an immediate mode expression and the second operand is a register.
1755 This is just a shorthand, so that, multiplying @samp{%eax} by 69, for
1756 example, can be done with @samp{imul $69, %eax} rather than @samp{imul