2 Programs🔗

An a86 program is a list of instructions. To be interpretable with asm-interp, the program must be well-formed, which means:

• Programs have at least one label which is declared Global; the first such label is used as the entry point.

• All label definitions are unique.

• All used labels are declared.

Examples

> (seq)

'()

> (seq (Label 'foo))

(list (Label 'foo))

> (seq (list (Label 'foo)))

(list (Label 'foo))

> (seq (list (Label 'foo)              (Mov 'rax 0))        (Mov 'rdx 'rax)        (list (Call 'bar)              (Ret)))

(list  (Label 'foo)  (Mov 'rax 0)  (Mov 'rdx 'rax)  (Call 'bar)  (Ret))

This function is useful to do some early error checking over whole programs and can help avoid confusing NASM errors. Unlike seq it should be called at the outermost level of a function that produces a86 code and not nested.

Examples

> (prog (Global 'foo) (Label 'foo))

(list (Global 'foo) (Label 'foo))

> (prog (Label 'foo))

prog: initial label undeclared as global: ($ 'foo)

> (prog (list (Label 'foo)))

prog: initial label undeclared as global: ($ 'foo)

> (prog (Mov 'rax 32))

prog: no initial label found

> (prog (Label 'foo)         (Label 'foo))

prog: duplicate label declaration found: 'foo

> (prog (Jmp 'foo))

prog: undeclared labels found: '(foo)

> (prog (Global 'foo)         (Label 'foo)         (Jmp 'foo))

(list (Global 'foo) (Label 'foo) (Jmp 'foo))

2.1 Psuedo-Instructions🔗

Psuedo-instructions are elements of Programs that make declarations and directives to the assembler, but don’t correspond to actual execuable Instructions.

Examples

> (Label 'fred)

(Label 'fred)

> (Label "fred")

Label: expects valid label name; given "fred"

> (Label 'fred-wilma)

Label: label names must conform to nasm restrictions

Examples

> (asm-display     (prog (Global 'foo)           (%%% "Start of foo")           (Label 'foo)           ; Racket comments won't appear           (%% "Inputs one argument in rdi")           (Mov 'rax 'rdi)           (Add 'rax 'rax)    (% "double it")           (Sub 'rax 1)       (% "subtract one")           (%% "we're done!")           (Ret)))

default rel         section .text         global $foo ;;; Start of foo $foo:         ;; Inputs one argument in rdi         mov rax, rdi         add rax, rax            ; double it         sub rax, 1              ; subtract one         ;; we're done!         ret

2.2 Instructions🔗

Instructions are represented as structures and can take as arguments Immediates, Registers, Labels, Memory Expressions, or Assembly Expressions.

For example, (Mov 'rax 42) is a "move" instruction that when executed will move the immediate value 42 into the rax register.

See Instruction Set for a complete listing of the instruction set and instruction constructor signatures.

2.3 Immediates🔗

Immediates are represented as exact integers of a certain bit width, which will depend upon the particular instruction and other arguments.

For example, Mov can take a 64-bit immediate source argument if the destination register is a 64-bit register. If the destination is a 32-bit register, the immediate must fit in 32-bits, etc. Cmp can take at most a 32-bit immediate argument. Instruction constructors check the size constraints of immediate arguments and signal an error when out of range.

Examples

> (Mov rax (sub1 (expt 2 64)))

(Mov 'rax 18446744073709551615)

> (Mov eax (sub1 (expt 2 64)))

Mov: literal must not exceed 32-bits; given

18446744073709551615 (64 bits)

> (Cmp rax (sub1 (expt 2 64)))

Cmp: literal must not exceed 32-bits; given

18446744073709551615 (64 bits); go through a register

instead

Note that x86 doesn’t have a notion of signed or unsigned integers. Some instructions compute either signed or unsigned operations, but the values in registers are simply bits. For this reason, a 64-bit immediate can be any exact integer in the range (- (expt 2 63)) and (sub1 (expt 2 64)), but keep in mind that, for example (- (expt 2 63)) and (expt 2 23) are represented by the same bits. Also note that asm-interp interprets the result of an assembly program as a signed integer. If you want to interpret the result as an unsigned integer, you will need add code to do so.

Examples

> (64-bit-integer? 0)

#t

> (64-bit-integer? (sub1 (expt 2 64)))

#t

> (64-bit-integer? (expt 2 64))

#f

> (64-bit-integer? (- (expt 2 63)))

#t

> (64-bit-integer? (sub1 (- (expt 2 63))))

#f

> (32-bit-integer? 0)

#t

> (32-bit-integer? (sub1 (expt 2 32)))

#t

> (32-bit-integer? (expt 2 32))

#f

> (32-bit-integer? (- (expt 2 32)))

#f

> (32-bit-integer? (sub1 (- (expt 2 32))))

#f

2.4 Registers🔗

Registers are represented as symbols, but this module also provides bindings corresponding to each register name, e.g. rax is bound to 'rax.

There are 16 64-bit registers.

The registers rbx, rsp, rbp, and r12 through r15 are “callee-saved” registers, meaning they are preserved across function calls (and must be saved and restored by any callee code).

Each register plays the same role as in x86, so for example rsp holds the current location of the stack.

There are 16 aliases for the lower 32-bits of the above registers. These are not separate registers, but instead provide access to the least signficant 32-bits of the 64-bits register.

There are 16 aliases for the lower 16-bits of the above registers (and thus the lower 16-bits of the 64-bit registers). These are not separate registers, but instead provide access to the least signficant 16-bits of the 64-bits register.

There are 16 aliases for the lower 8-bits of the above registers (and thus the lower 8-bits of the 64-bit registers). These are not separate registers, but instead provide access to the least signficant 8-bits of the 64-bits register.

Finally, there are 4 aliases for next higher 8-bits of the above registers (and thus the lower 9th-16th bits of some of the 64-bit registers}. Only rax, rbx, rcx, and rdx have such aliases.

2.5 Labels🔗

Labels are represented as symbols (or $ structures) that must conform to the naming restriction imposed by NASM, so not all symbols are valid label names.

Labels must also follow the NASM restrictions on label names: "Valid characters in labels are letters, numbers, _, $, #, @, ~, ., and ?. The only characters which may be used as the first character of an identifier are letters, . (with special meaning), _ and ?."

Examples

> (label? 'foo)

#t

> (label? "foo")

#f

> (label? 'rax)

#f

> (label? 'foo-bar)

#f

> (label? 'foo.bar)

#t

Examples

> (Label ($ 'rax))

(Label ($ 'rax))

2.6 Memory Expressions🔗

Memory expressions are represented with Offset structures. A memory expression signals that a quantity should be interpreted as a location in memory, rather than the bits itself. For example, the rsp holds a pointer the stack memory; (Mov rax rsp) will move the pointer held in rsp into rax, while (Mov rax (Offset rsp)) will read 64-bits of memory at the location pointed at by the pointer in rsp into rax. On the other hand, (Mov rsp rax) will move the value in rax into the rsp register (overwriting the stack pointer), while (Mov (Offset rsp) rax) will write the value in rax into the memory pointed at by the rsp register.

Memory expression can take as arguments either registers or Assembly Expressions, which are commonly used to indicate offsets from a given memory location, e.g. (Mov rax (Offset (@ (+ rsp 8)))) reads the 64-bits of memory at the location held in rsp + 8, i.e. 8 bytes past wherever rsp points.

Examples

> (Offset 'rax)

(Offset 'rax)

2.7 Assembly Expressions🔗

Assembly expressions are represented by s-expressions conforming to the following grammar:

For the meaning of assembly instructions, refer to the NASM docs.

Examples

> (exp? 0)

#t

> (exp? '(+ rax 8))

#t

> (exp? '(? lab1 0 1))

#t

This form is useful for referencing bound variables or Racket functions within assembly expression. If the Racket identifier you want to reference conflicts with an assembly expression keyword, e.g. +, you can use begin to escape into Racket expression mode, e.g. (@ (+ 1 (begin (+ 2 3)))) is '(+ 1 5).

If any unquoted expression evaluates to something that is not an assembly expression, an error is signalled.

Examples

> (@ (+ 1 2))

'(+ 1 2)

> (@ (+ x 1))

'(+ x 1)

> (let ((x 100)) (@ (+ x 1)))

'(+ 100 1)

> (let ((+ 100)) (@ (+ + +)))

'(+ 100 100)

> (@ (+ + +))

not an assembly expression #<procedure:+>

2.8 Instruction Set🔗

This section describes the instruction set of a86.

Examples

> (let ([l (symbol->label 'my-great-label)])     (seq (Label l)          (Jmp l)))

(list  (Label 'label_my_great_label_a1d1fe873a8070d)  (Jmp 'label_my_great_label_a1d1fe873a8070d))

Examples

> (asm-interp     (Global 'entry)     (Label 'entry)     (Call 'f)     (Add 'rax 1)     (Ret)     (Label 'f)     (Mov 'rax 41)     (Ret))

42

Examples

> (asm-interp     (Global 'entry)     (Label 'entry)     (Mov 'rax 42)     (Ret))

42

Either dst or src may be offsets, but not both.

Examples

> (asm-interp     (Global 'entry)     (Label 'entry)     (Mov 'rbx 42)     (Mov 'rax 'rbx)     (Ret))

42

> (Mov (Offset 'rax 0) (Offset 'rbx 0))

Mov: cannot use two memory locations; given (Offset '(+ rax

0)), (Offset '(+ rbx 0))

In the case of a 32-bit immediate, it is sign-extended to 64-bits.

Examples

> (asm-interp     (Global 'entry)     (Label 'entry)     (Mov 'rax 32)     (Add 'rax 10)     (Ret))

42

In the case of a 32-bit immediate, it is sign-extended to 64-bits.

Examples

> (asm-interp     (Global 'entry)     (Label 'entry)     (Mov 'rax 32)     (Sub 'rax 10)     (Ret))

22

In the case of a 32-bit immediate, it is sign-extended to 64-bits.

Examples

> (asm-interp     (Global 'entry)     (Label 'entry)     (Mov 'rax 32)     (Add 'rax 10)     (Ret))

42

In the case of a 32-bit immediate, it is sign-extended to 64-bits.

In the case of a 32-bit immediate, it is sign-extended to 64-bits.

Examples

> (asm-interp (Mov 'rax 42)               (Cmp 'rax 2)               (Jg 'l1)               (Mov 'rax 0)               (Label 'l1)               (Ret))

42

Examples

> (asm-interp (Mov 'rax 42)               (Jmp 'l1)               (Mov 'rax 0)               (Label 'l1)               (Ret))

42

> (asm-interp (Mov 'rax 42)               (Pop 'rbx)               (Jmp 'rbx))

42

Examples

> (asm-interp (Mov 'rax 42)               (Cmp 'rax 2)               (Jz 'l1)               (Mov 'rax 0)               (Label 'l1)               (Ret))

0

Examples

> (asm-interp (Mov 'rax 42)               (Cmp 'rax 2)               (Jnz 'l1)               (Mov 'rax 0)               (Label 'l1)               (Ret))

42

Examples

> (asm-interp (Mov 'rax 42)               (Cmp 'rax 2)               (Jl 'l1)               (Mov 'rax 0)               (Label 'l1)               (Ret))

0

Examples

> (asm-interp (Mov 'rax 42)               (Cmp 'rax 42)               (Jle 'l1)               (Mov 'rax 0)               (Label 'l1)               (Ret))

42

Examples

> (asm-interp (Mov 'rax 42)               (Cmp 'rax 2)               (Jg 'l1)               (Mov 'rax 0)               (Label 'l1)               (Ret))

42

Examples

> (asm-interp (Mov 'rax 42)               (Cmp 'rax 42)               (Jg 'l1)               (Mov 'rax 0)               (Label 'l1)               (Ret))

0

Examples

> (asm-interp (Mov 'rax (sub1 (expt 2 63)))               (Add 'rax 1)               (Jo 'l1)               (Mov 'rax 0)               (Label 'l1)               (Ret))

-9223372036854775808