Module inc::x86

A general purpose x86 library.

Getting started

The easiest way to learn assembly is to write very simple C programs and look at the generated code. Clang and GCC support -S flag to output the assembly instead of a binary executable.

Some reasonably good tutorials are:

1. x86 Assembly Guide 1

2. x86 Assembly Guide 2

3. Ops like .p2align are not x86 instructions but GNU assembly directives. See GNU assembler docs.

Syntax

Intel syntax is used everywhere instead of AT&T, which is so much more painful to read.

1. x86 assembly language | Syntax
2. AT&T Syntax versus Intel Syntax

Portability

This should work on osx and Linux. Platform specific code is annotated and picked at compile time where possible.

1. Writing 64 Bit Assembly on Mac OS X

System V AMD64 ABI

The default calling convention used by GCC on x86-64 seems to be System V AMD64 ABI. User defined functions, primitives as well as FFI into C must use this convention for simplicity.

Registers

Arguments are passed in the registers RDI, RSI, RDX, RCX, R8, R9 and the return value is passed back in RAX. Functions preserve the registers RBX, RSP, RBP, R12, R13, R14, and R15; while RAX, RDI, RSI, RDX, RCX, R8, R9, R10, R11 are scratch registers.

Reference Reading

1. x86 calling conventions
2. System V ABI
3. System V Application Binary Interface

Structs

ASM	ASM represents a list of instructions
Ins	An x86 instruction
Relative	Relative addressing modes for memory access

Enums

Reference	A Reference is a valid address to an x86 instruction.
Register	An x86 register

Constants

SYS_V	Registers for argument passing
WORDSIZE	Word size of the architecture

Functions

add	Add v to register r
and	Logical and of v to register r
call	Unconditional function call
cmp	Compares the first source operand with the second source operand and sets the status flags in the EFLAGS register.
enter	x86 function preamble
init_heap	The base address of the heap is passed in RDI and we reserve reg RSI for it.
je	Jump to the specified label if last comparison resulted in equality
jmp	Unconditionally jump to the specified label
label	A label is a target to jump to
lea	Load effective address of a label into register r with an offset
leave	Exit a function and clean up. See Enter
load	Load a value at stack index si to register r
mov	Mov! At least one of the operands must be a register, moving from RAM to RAM isn't a valid op.
mul	Multiply register AX with value v and move result to register RAX
or	Logical or of v to register r
pop	Pop a register r from stack
push	Push a register r to stack
ret	Return from the calling function
sal	Shift register r left by v bits; r = r * 2^v
sar	Shift register r right by v bits; r = r / 2^v
save	Save a register r to stack at index si
sub	Sub k from register r