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 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)))

.intel_syntax noprefix         .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 signed; given

18446744073709551615 (65 bits signed); 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 the assembler, so not all symbols are valid label names.

Labels must also follow the restrictions on label names: The NASM assembler’s documentation specifies: "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

> (asm-label? 'foo)

'("foo")

> (asm-label? "foo")

#f

> (asm-label? 'rax)

'("rax")

> (asm-label? 'foo-bar)

#f

> (asm-label? 'foo.bar)

'("foo.bar")

Examples

> (Label ($ 'rax))

(Label ($ 'rax))

(or (asm-symbol? x)

($? x))

2.6 Memory Expressions🔗

Memory expressions are represented with Mem structures. A memory expression signals that a quantity should be interpreted as a location in memory, rather than as the bits themselves. For example, consider the rsp register, which holds a pointer to the stack in memory, i.e., its value is a number that can be interpreted as an address. The instruction (Mov rax rsp) will copy that address from rsp into rax, while the instruction (Mov rax (Mem rsp)) will copy the 64 bits of data stored in memory at the address held by rsp into rax. Similarly, (Mov rsp rax) will copy the value held in rax into rsp (which will overwrite our stack pointer — almost always a bad thing), while (Mov (Mem rsp) rax) will write the value held in rax into the memory pointed to by the rsp pointer without actually changing the value held in rsp.

The integer?-accepting arguments base and offset place restrictions on those integers depending on the addressing mode. In 64-bit mode, the integer can be no wider than 32 bits (signed).

When the scale is omitted, it is not printed out in x86. However, omitting it is effectively equivalent to specifying a scale of 1.

When two registers are given as the base and index arguments, they must be of the same width. For example, rax and r8 are compatible, but rbx and eax are not.

We don’t use the scale for anything currently, but it is supported for future extensions to the course.

Because of how complicated it can be to correctly specify the arguments to a Mem, this structure is built by a specialized smart constructor. The acceptable forms are documented below:

procedure (Mem index [offset]) → Mem?

index : label?

offset : (or/c #f integer?) = #f

A relative address specification. In these cases, the printer automatically prefixes the address computation with the rip base register according to the x86 specification.

The index can be given as either a symbol (e.g., ’foo) or a $-wrapped label. In the former case, the symbol will be wrapped in a $ during construction to ensure proper architecture-dependent formatting when printing.

Prints in x86 as [rip + index + offset].

procedure (Mem offset) → Mem?

offset : integer?

An absolute address specification with an offset as the base. We don’t use this form currently, but it is supported for future extensions to the course.

Prints in x86 as [offset].

procedure (Mem base [index #:scale scale offset]) → Mem?

base : register?

index : (or/c #f (and/c register? (not/c 'rsp))) = #f

scale : (or/c #f 1 2 4 8) = #f

offset : (or/c #f integer?) = #f

An absolute address specification with a register as the base. The index, scale, and offset arguments are optional.

Prints in x86 as [base + (index * scale) + offset].

procedure (Mem index #:scale scale [offset]) → Mem?

index : (and/c register? (not/c 'rsp))

scale : (or/c 1 2 4 8)

offset : (or/c #f integer?) = #f

An absolute address specification with a non-rsp register as the index. This form requires the scale to be given, and it accepts an optional offset argument.

Prints in x86 as [(index * scale) + offset].

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 (Mem 'rax 0) (Mem 'rbx 0))

Mov: cannot use two memory locations; given (Mem 'rax 0),

(Mem '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