akyoto / asm

:running: An x86-64 assembler written in Go.

asm

An x86-64 assembler written in Go. It is used by the Q programming language for machine code generation.

It was born out of the need for a highly performant assembler that had next to no overhead when compiling instructions to bytecode. When I started this project, I had no idea of how x86 instructions were constructed and I was forced to do a lot of reverse engineering via NASM.

Hopefully this repository helps someone who is learning about x86 assembly and its bytecode format.

There are a few examples to get an idea of the API I was aiming for.

x86-64 bytecode

An x86-64 program consists of a list of instructions. All of these instructions are built with the following format:

Name	Size in bytes	Required?
Legacy prefixes	1-4
OP code	1-4	required
Mod/RM	1
SIB	1
Displacement	1-8
Immediate	1-8

Out of these only the actual OP code which decides the instruction to execute is required. The remaining components depend on what instruction and what kind of parameters you have.

The maximum size for a single instruction is limited to 15 bytes.

Mod/RM

The Mod/RM byte has the following format:

Name	Size in bits
Mod	2
Reg	3
RM	3

(mod << 6) | (reg << 3) | rm

SIB

The SIB byte has the same format as Mod/RM, just with different meanings:

Name	Size in bits
Scale	2
Index	3
Base	3

(scale << 6) | (index << 3) | base

The opcode directory has a few helper functions to construct these components.

Registers

The following is a list of register names you can use. I decided to stick with the original names instead of r0-r7 for rax-rbp. I might still switch to r0-r7 for the future and enable the old names as synonyms.

64 bit	32 bit	16 bit	8 bit
rax	eax	ax	al
rcx	ecx	cx	cl
rdx	edx	dx	dl
rbx	ebx	bx	bl
rsi	esi	si	sil
rdi	edi	di	dil
rsp	esp	sp	spl
rbp	ebp	bp	bpl
r8	r8d	r8w	r8b
r9	r9d	r9w	r9b
r10	r10d	r10w	r10b
r11	r11d	r11w	r11b
r12	r12d	r12w	r12b
r13	r13d	r13w	r13b
r14	r14d	r14w	r14b
r15	r15d	r15w	r15b

Resources

• https://godbolt.org
• https://www.felixcloutier.com/x86
• https://wiki.osdev.org/X86-64_Instruction_Encoding
• https://www.systutorials.com/beginners-guide-x86-64-instruction-encoding/
• https://blog.yossarian.net/2020/06/13/How-x86_64-addresses-memory
• https://cs.brown.edu/courses/cs033/docs/guides/x64_cheatsheet.pdf
• https://www.cs.cmu.edu/~fp/courses/15213-s07/resources.html
• https://www.agner.org/optimize/optimizing_assembly.pdf
• https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html