static_asm

A header-only C++20 library for compile-time x86/x86-64 instruction encoding.

This project is dual-licensed under the Boost Software License 1.0 and the MIT License. You may choose either license.

Purpose

• Learning x86 assembly encoding in a practical and fun way
• Generating assembly instructions at compile time with full type safety
• Creating shellcode and JIT code templates without runtime overhead

Quick Start

#include "static_asm.hpp"

using namespace static_asm;
using namespace static_asm::x86;
using namespace static_asm::x86::registers;
using namespace static_asm::x86::instructions;

// Build machine code at compile time
constexpr auto code = core::assemble(
    mov(rax, 0x12345678),    // mov rax, imm32
    add(rax, rcx),           // add rax, rcx
    xor_(r8, r8),            // xor r8, r8
    call(rax),               // call rax
    ret()                    // ret
);
// code is std::array<uint8_t, N> - fully constexpr!

For named branches and embedded data, see Labels and Branch Relaxation.

Examples by Category

ALU Operations

// Register to register
add(rax, rbx);           // 48 01 D8
sub(ecx, edx);           // 29 D1
and_(r8, r9);            // 4D 21 C8
or_(rsi, rdi);           // 48 09 FE
xor_(eax, eax);          // 31 C0 (common idiom to zero a register)
cmp(rax, rcx);           // 48 39 C8

// Register with immediate
add(rax, 0x10);          // 48 83 C0 10 (sign-extended imm8)
add(rax, 0x10000);       // 48 05 00 00 01 00 (imm32)
sub(ecx, 100);           // 83 E9 64
and_(rdx, 0xFF);         // 48 83 E2 FF

// With memory operands
add(eax, dword_ptr(rbx));                        // 03 03
add(rax, qword_ptr(rcx + disp<0x10>));           // 48 03 41 10
sub(dword_ptr(rsp + disp<0x20>), eax);           // 29 44 24 20

Use disp<value> for the shortest displacement. It chooses no displacement for zero where legal, a signed disp8 for -128 through 127, and disp32 otherwise. RIP-relative addresses always need a disp32; RBP/R13 with zero still need a zero disp8. Values outside signed 32 bits fail compilation. A plain integer such as rcx + 0x10 still uses disp32: C++ cannot select different exact-size instruction array types from the value of an int argument. [base + disp] with a general base uses the canonical ModR/M-only form (no SIB byte); RSP/R12 bases emit a SIB byte because the hardware requires it.

Data Movement

// Register to register
mov(rax, rbx);           // 48 89 D8
mov(eax, ecx);           // 89 C8
mov(r8, r9);             // 4D 89 C8

// Immediate to register
mov(rax, 0x12345678);    // 48 C7 C0 78 56 34 12
mov(eax, 0xDEADBEEF);    // B8 EF BE AD DE

// Memory operations
mov(rax, qword_ptr(rbx));                        // 48 8B 03
mov(eax, dword_ptr(rcx + disp<0x10>));           // 8B 41 10
mov(rax, qword_ptr(rbp - disp<0x20>));           // 48 8B 45 E0 (canonical, no SIB)
mov(qword_ptr(rsp + disp<0x8>), rax);            // 48 89 44 24 08 (RSP base needs SIB)

// Zero/sign extension
movzx(eax, bl);          // 0F B6 C3 (zero-extend byte to dword)
movzx(rax, bx);          // 48 0F B7 C3 (zero-extend word to qword)
movsx(eax, cl);          // 0F BE C1 (sign-extend byte to dword)
movsx(rax, dx);          // 48 0F BF C2 (sign-extend word to qword)
movsxd(rax, ecx);        // 48 63 C1 (sign-extend dword to qword)

// Load effective address
lea(rax, qword_ptr(rbx + rcx * s4));                      // 48 8D 04 8B
lea(rax, qword_ptr(rbx + rcx * s8 + disp<0x10>));         // 48 8D 44 CB 10

// Exchange (register or memory; XCHG is symmetric)
xchg(rax, rbx);                                  // 48 87 D8
xchg(qword_ptr(rcx), rax);                       // 48 87 01
xchg(rbx, qword_ptr(rcx + disp<0x10>));          // 48 87 59 10

// Store an immediate to a displaced / SIB / RIP memory destination
mov(dword_ptr(rbp - disp<0x20>), 0x100);         // C7 45 E0 00 01 00 00
mov(qword_ptr(rcx + disp<0x10>), 1);             // 48 C7 41 10 01 00 00 00
add(qword_ptr(rbx + disp<0x8>), 0x10);           // 48 81 43 08 10 00 00 00

A qword memory destination has only a sign-extended 32-bit immediate encoding. An integer's 64-bit bit pattern must match that encoding: for example, 0x7FFFFFFF and -0x80000000LL fit, while positive 0x80000000ULL does not. An invalid value fails constant evaluation or throws std::out_of_range at runtime. With exceptions disabled, an invalid runtime value terminates. Explicit imm32 operands supply the raw four immediate bytes.

RIP-Relative Addressing

rip + disp (and rip - disp) encode the 64-bit RIP-relative form (ModR/M mod=00 r/m=101, a mandatory disp32, never a SIB byte):

mov(rax, qword_ptr(rip + 0x10));   // 48 8B 05 10 00 00 00
lea(rax, qword_ptr(rip + 0x100));  // 48 8D 05 00 01 00 00
add(qword_ptr(rip + 0x20), rbx);   // 48 01 1D 20 00 00 00
inc(qword_ptr(rip + 0x40));        // 48 FF 05 40 00 00 00
test(rax, qword_ptr(rip + 0x10)); // 48 85 05 10 00 00 00
test(qword_ptr(rip + 0), 0x10);   // 48 F7 05 00 00 00 00 10 00 00 00

SIB Addressing (Scale-Index-Base)

// [base + index*scale]
mov(eax, dword_ptr(rbx + rcx * s1));   // 8B 04 0B
mov(eax, dword_ptr(rbx + rcx * s2));   // 8B 04 4B
mov(eax, dword_ptr(rbx + rcx * s4));   // 8B 04 8B
mov(eax, dword_ptr(rbx + rcx * s8));   // 8B 04 CB

// [base + index*scale + displacement]
mov(rax, qword_ptr(rbx + rcx * s4 + disp<0x10>));         // 48 8B 44 8B 10
mov(rax, qword_ptr(r12 + r13 * s8 + 0x1000));             // 4B 8B 84 EC 00 10 00 00

// Store to SIB address
mov(dword_ptr(rax + rdx * s4), ecx);                      // 89 0C 90
mov(qword_ptr(rbx + rsi * s8 + disp<0x20>), rax);         // 48 89 44 F3 20

// LEA with SIB (useful for address calculations)
lea(rax, qword_ptr(rbx + rcx * s4));                      // 48 8D 04 8B
lea(rax, qword_ptr(rdi + rsi * s8 + 0x100));              // 48 8D 84 F7 00 01 00 00

Shift and Rotate

// Shift by 1
shl(eax, 1);             // D1 E0
shr(rax, 1);             // 48 D1 E8
sar(ecx, 1);             // D1 F9

// Shift by immediate
shl(eax, 4);             // C1 E0 04
shr(rax, 8);             // 48 C1 E8 08
sar(rdx, 16);            // 48 C1 FA 10

// Shift by CL register
shl(eax, cl);            // D3 E0
shr(rax, cl);            // 48 D3 E8

// Rotate
rol(eax, 1);             // D1 C0
ror(rax, 8);             // 48 C1 C8 08
rcl(ecx, cl);            // D3 D1
rcr(rdx, 1);             // 48 D1 DA

Multiply and Divide

// Single operand (result in rdx:rax)
mul(rbx);                // 48 F7 E3 (unsigned: rdx:rax = rax * rbx)
imul(rcx);               // 48 F7 E9 (signed: rdx:rax = rax * rcx)
div(rbx);                // 48 F7 F3 (unsigned: rax = rdx:rax / rbx, rdx = remainder)
idiv(rcx);               // 48 F7 F9 (signed division)

// Two-operand IMUL (dest = dest * src)
imul(rax, rbx);          // 48 0F AF C3
imul(ecx, edx);          // 0F AF CA

// Three-operand IMUL (dest = src * imm)
imul(rax, rbx, 10);      // 48 6B C3 0A
imul(ecx, edx, 1000);    // 69 CA E8 03 00 00

// Single-operand form with a memory operand
mul(qword_ptr(rcx));                             // 48 F7 21
imul(qword_ptr(rcx + disp<0x20>));               // 48 F7 69 20
div(dword_ptr(rax + disp<0x10>));                // F7 70 10
idiv(qword_ptr(rbx));                            // 48 F7 3B

Increment / Decrement / Negate / Not

// Register operands
inc(rax);                // 48 FF C0
dec(ecx);                // FF C9
neg(rbx);                // 48 F7 DB
not_(rdx);               // 48 F7 D2