YASM_ARCH(7)

✨ NAME ✨

yasm_arch — the target architectures Yasm can assemble for 💖

---

🌸 SYNOPSIS 🌸

yasm -a arch [-m machine] ...

---

💅 DESCRIPTION 💅

okay so bestie, the standard Yasm distribution ships with a whole little squad of modules for different target architectures 🫶 and every target architecture can support one or more machine architectures. so like, one arch, many machines, it's giving polycule energy tbh.

you pick your architecture and your machine right on the yasm(1) command line, using the -a arch and -m machine command line options respectively ✨ simple as.

but also — plot twist — the machine architecture can get auto-selected by certain object formats, no user input required 👑 for example, the elf32 object format selects the x86 machine architecture by default, while the elf64 object format selects the amd64 machine architecture by default. the object format is basically picking your machine for you, periodt.

---

🌈 X86 ARCHITECTURE 🌈

the x86 architecture supports the IA-32 instruction set and its derivatives, plus the AMD64 instruction set. it's literally two machines in a trench coat:

• x86 — for the IA-32 and derivatives
• amd64 — for the AMD64 and derivatives

and the default machine for the x86 architecture? that's the x86 machine. keeping it simple, iconic behavior 💖

🎀 BITS Setting 🎀

the x86 architecture BITS setting tells Yasm which processor mode the generated code is intended to execute in. because x86 processors can run in three different major execution modes:

• 16-bit
• 32-bit
• 64-bit (on AMD64-supporting processors only)

and here's the tea: the x86 instruction set contains portions whose function is execution-mode dependent — think operand-size and address-size override prefixes 😭 — so Yasm literally cannot assemble x86 instructions correctly unless you tell it what processor mode the code is gonna execute in. no vibes-based guessing here.

you can change the BITS setting in a variety of ways. when you're using the NASM-compatible parser, you can change it directly with the BITS xx assembler directive 🌟 and the default BITS setting is determined by the object format in use.

🦋 BITS 64 Extensions 🦋

the AMD64 architecture is a new 64-bit architecture developed by AMD, based on the 32-bit x86 architecture. it extends the original x86 by:

• doubling the number of general purpose and SIMD registers
• extending the arithmetic operations and address space to 64 bits
• plus other features

recently, Intel introduced an essentially identical version of AMD64 called EM64T. same vibe, different name 💀

when an AMD64-supporting processor is executing in 64-bit mode, a bunch of additional extensions become available, including:

• extra general purpose registers
• extra SSE2 registers
• RIP-relative addressing

Yasm extends the base NASM syntax to support AMD64 like this 👇 to enable assembly of instructions for the 64-bit mode of AMD64 processors, use the directive BITS 64. and just like NASM's BITS directive, this does not change the format of the output object file to 64 bits — it only changes the assembler mode to assume that the instructions being assembled will be run in 64-bit mode. read that again bestie, it matters 👀

to specify an AMD64 object file, use -m amd64 on the Yasm command line, or explicitly target a 64-bit object format such as -f win64 or -f elf64. and -f elfx32 can be used to select 32-bit ELF object format for AMD64 processors ✨

💜 Register Changes 💜

the additional 64-bit general purpose registers are named r8-r15. there are also 8-bit (rXb), 16-bit (rXw), and 32-bit (rXd) subregisters that map to the least significant 8, 16, or 32 bits of the 64-bit register. tiny versions of the big ones, we love a nested register moment 🥺

the original 8 general purpose registers have also been extended to 64-bits: eax, edx, ecx, ebx, esi, edi, esp, and ebp have new 64-bit versions called rax, rdx, rcx, rbx, rsi, rdi, rsp, and rbp respectively. and the old 32-bit registers map to the least significant bits of the new 64-bit registers.

new 8-bit registers are also available that map to the 8 least significant bits of rsi, rdi, rsp, and rbp. these are called sil, dil, spl, and bpl respectively 💅 unfortunately — and this is the tragic part 😭 — due to the way instructions are encoded, these new 8-bit registers are encoded the same as the old 8-bit registers ah, dh, ch, and bh. the processor tells which one is being used by the presence of the new REX prefix, which is used to specify the other extended registers.

this means it is illegal to mix the use of ah, dh, ch, and bh with an instruction that requires the REX prefix for other reasons. for instance:

add ah, [r10]

(NASM syntax) is not a legal instruction, because the use of r10 requires a REX prefix, making it impossible to use ah. the compiler said no ❌

in 64-bit mode, an additional 8 SSE2 registers are also available. these are named xmm8-xmm15 🎀

⭐ 64 Bit Instructions ⭐

by default, most operations in 64-bit mode remain 32-bit; operations that are 64-bit usually require a REX prefix (one bit in the REX prefix determines whether an operation is 64-bit or 32-bit). so basically all 32-bit instructions have a 64-bit version, and the 64-bit versions of instructions can use extended registers "for free" (because the REX prefix is already present). free real estate, no cap 🏠✨

examples in NASM syntax:

mov eax, 1  ; 32-bit instruction

mov rcx, 1  ; 64-bit instruction

instructions that modify the stack — push, pop, call, ret, enter, and leave — are implicitly 64-bit. their 32-bit counterparts are not available, but their 16-bit counterparts are 🫶

examples in NASM syntax:

push eax  ; illegal instruction

push rbx  ; 1-byte instruction

push r11  ; 2-byte instruction with REX prefix

🌸 Implicit Zero Extension 🌸

results of 32-bit operations are implicitly zero-extended to the upper 32 bits of the corresponding 64-bit register. 16 and 8 bit operations, on the other hand, do not affect upper bits of the register (just as in 32-bit and 16-bit modes). and this can be used to generate smaller code in some instances — little optimization hack, iykyk 💖

examples in NASM syntax:

mov ecx, 1  ; 1 byte shorter than mov rcx, 1

and edx, 3  ; equivalent to and rdx, 3

🧚 Immediates 🧚

for most instructions in 64-bit mode, immediate values remain 32 bits; their value is sign-extended into the upper 32 bits of the target register prior to being used. the exception is the mov instruction, which can take a 64-bit immediate when the destination is a 64-bit register 👑

examples in NASM syntax:

add rax, 1           ; optimized down to signed 8-bit

add rax, dword 1     ; force size to 32-bit

add rax, 0xffffffff  ; sign-extended 32-bit

add rax, -1          ; same as above

add rax, 0xffffffffffffffff ; truncated to 32-bit (warning)

mov eax, 1           ; 5 byte

mov rax, 1           ; 5 byte (optimized to signed 32-bit)

mov rax, qword 1     ; 10 byte (forced 64-bit)

mov rbx, 0x1234567890abcdef ; 10 byte

mov rcx, 0xffffffff  ; 10 byte (does not fit in signed 32-bit)

mov ecx, -1          ; 5 byte, equivalent to above

mov rcx, sym         ; 5 byte, 32-bit size default for symbols

mov rcx, qword sym   ; 10 byte, override default size

heads up bestie, the handling of mov reg64, unsized immediate is different between YASM and NASM 2.x. YASM follows the above behavior, while NASM 2.x does the following:

add rax, 0xffffffff  ; sign-extended 32-bit immediate

add rax, -1          ; same as above

add rax, 0xffffffffffffffff ; truncated 32-bit (warning)

add rax, sym         ; sign-extended 32-bit immediate

mov eax, 1           ; 5 byte (32-bit immediate)

mov rax, 1           ; 10 byte (64-bit immediate)

mov rbx, 0x1234567890abcdef ; 10 byte instruction

mov rcx, 0xffffffff  ; 10 byte instruction

mov ecx, -1          ; 5 byte, equivalent to above

mov ecx, sym         ; 5 byte (32-bit immediate)

mov rcx, sym         ; 10 byte instruction

mov rcx, qword sym   ; 10 byte (64-bit immediate)

🍓 Displacements 🍓

just like immediates, displacements, for the most part, remain 32 bits and are sign extended prior to use. again, the exception is one restricted form of the mov instruction: between the al/ax/eax/rax register and a 64-bit absolute address (no registers allowed in the effective address). in NASM syntax, use of the 64-bit absolute form requires [qword] 🌟

examples in NASM syntax:

mov eax, [1]    ; 32 bit, with sign extension

mov al, [rax-1] ; 32 bit, with sign extension

mov al, [qword 0x1122334455667788] ; 64-bit absolute

mov al, [0x1122334455667788] ; truncated to 32-bit (warning)

💫 RIP Relative Addressing 💫

in 64-bit mode, a new form of effective addressing is available to make it easier to write position-independent code 🫶 any memory reference may be made RIP relative (RIP is the instruction pointer register, which contains the address of the location immediately following the current instruction).

in NASM syntax, there are two ways to specify RIP-relative addressing:

mov dword [rip+10], 1

stores the value 1 ten bytes after the end of the instruction. 10 can also be a symbolic constant, and will be treated the same way. on the other hand,

mov dword [symb wrt rip], 1

stores the value 1 into the address of symbol symb. this is distinctly different than the behavior of:

mov dword [symb+rip], 1

which takes the address of the end of the instruction, adds the address of symb to it, then stores the value 1 there. 😱 and if symb is a variable, this will not store the value 1 into the symb variable! the way these two look almost the same but do completely different things... not me getting got by that 🙈

Yasm also supports the following syntax for RIP-relative addressing:

mov [rel sym], rax  ; RIP-relative

mov [abs sym], rax  ; not RIP-relative

the behavior of:

mov [sym], rax

depends on a mode set by the DEFAULT directive, as follows. the default mode is always "abs", and in "rel" mode, use of registers, an fs or gs segment override, or an explicit "abs" override will result in a non-RIP-relative effective address. okay so watch closely, this is the whole vibe check 👀

default rel

mov [sym], rbx      ; RIP-relative

mov [abs sym], rbx  ; not RIP-relative (explicit override)

mov [rbx+1], rbx    ; not RIP-relative (register use)

mov [fs:sym], rbx   ; not RIP-relative (fs or gs use)

mov [ds:sym], rbx   ; RIP-relative (segment, but not fs or gs)

mov [rel sym], rbx  ; RIP-relative (redundant override)

default abs

mov [sym], rbx      ; not RIP-relative

mov [abs sym], rbx  ; not RIP-relative

mov [rbx+1], rbx    ; not RIP-relative

mov [fs:sym], rbx   ; not RIP-relative

mov [ds:sym], rbx   ; not RIP-relative

---

okay bestie that's part 1, and there's more coming so don't go anywhere 💖✨

mov [rel sym], rbx  ; RIP-relative (explicit override)

💭 Memory references

okay so bestie, here's the tea on memory sizes 🫖 — usually YASM can just tell how big your memory reference is by looking at which registers you're moving around. like, mov [rax],ecx is literally a 32-bit move, because ecx is 32 bits. the register snitched on itself, no cap. 💅

but rn, if YASM can't figure out how much memory you're moving, it hits you with the non-obvious invalid combination of opcode and operands error 😭 (it's giving cryptic, it's giving unhelpful). the fix? just add a memory size specifier, bestie: qword, dword, word, or byte. that's it, that's the whole vibe check. ✨

here's a 64-bit memory move, which sets 8 bytes starting at rax:

mov qword [rax], 1

here's a 32-bit memory move, which sets 4 bytes:

mov dword [rax], 1

here's a 16-bit memory move, which sets 2 bytes:

mov word [rax], 1

here's an 8-bit memory move, which sets 1 byte:

mov byte [rax], 1

see? one byte per size step, it's giving mathematically consistent icon behavior 👑

---

🌈 LC3B ARCHITECTURE 🌈

the lc3b architecture supports the LC-3b ISA — yes that's the one used in the ECE 312 (now ECE 411) course at the University of Illinois, Urbana-Champaign 🎓, plus other university courses too (academia girlies rise up). for more details and example code, go peek at http://courses.ece.uiuc.edu/ece411/ 🦋

and the lc3b architecture is a minimalist. it consists of only one machine: lc3b. one. single. machine. it said "I don't need a whole roster" 💅 periodt.

---

👀 SEE ALSO 👀

• yasm(1)

---

💀 BUGS 💀

⚠️ listen, this one's a real trap, so pay attention bestie ⚠️

when you're using the x86 architecture, it is overly easy to generate AMD64 code (by using the BITS 64 directive) and then generate a 32-bit object file anyway — which happens by failing to specify -m amd64 on the command line, or by selecting a 64-bit object format. the two halves of your brain are not talking to each other and the assembler is just standing there watching 😭

and similarly? specifying -m amd64 does not default the BITS setting to 64. it just doesn't. no automatic glow-up, unfortunately. 🙈

an easy way to dodge this whole mess: directly specify a 64-bit object format such as -f elf64. be explicit, be iconic, be correct. ✨

---

🫶 AUTHOR 🫶

Peter Johnson <peter@tortall.net>

• Author. (the literal main character, we stan 👑)

---

🎀 COPYRIGHT 🎀

Copyright © 2004, 2005, 2006, 2007 Peter Johnson

---

and that's a wrap on YASM_ARCH(7) 💖 this page came to you from Yasm, dated October 2006 — yes it's vintage, yes it still slays, we love a timeless classic 🦋🌸 byeee, go assemble something cute 💅✨