On this page:
2.1 Core APIs
Assembler
make-assembler
current-assembler
Assembler?
emit-code!
assembler-shutdown-all!
Context
make-context
current-context
Context?
Label
Label?
label
label-addr
:  !
data!
2.2 Instrcution Operands
Size
Scale
Operand
Reg
Reg?
GPR
GPR?
XMM
XMM?
Seg
Seg?
IP
IP?
Mref
Mref?
mref
Imm
Imm?
imm8
imm16
imm32
imm64
rel8
rel32
latent-imm
Offset
Offset?
moff
2.3 Helper Macros
define-cast
with-labels
λ!
define-λ!

2 APIs🔗ℹ

This module provide apis described here, but not instructions.

 (require x64asm) package: x64asm-lib
This module provide apis described here and instructions.

Same as x64asm, but works in untyped racket.

2.1 Core APIs🔗ℹ

syntax

Assembler

Type of assemblers.

procedure

(make-assembler)  Assembler?

Creates an assembler.

parameter

(current-assembler)  Assembler?

(current-assembler asm)  void?
  asm : Assembler?
A parameter defines the current assembler.

procedure

(Assembler? asm)  boolean?

  asm : any/c
Tests whether asm is an Assembler.

procedure

(emit-code! [asm ctx ctx*])  void?

  asm : Assembler? = (current-assembler)
  ctx : Context? = (assert (current-context))
  ctx* : (listof Context?) = '()
Generates codes from given contexts. After calling this function, labels from ctx and ctx* have their addresses available. Memories for generated code are managed by asm. When contexts have mutually referenced labels, they must be submitted to emit-code! together.

procedure

(assembler-shutdown-all! [asm])  void?

  asm : Assembler? = (current-assembler)
Releases memories held by asm. Codes generated via asm are invalidated.

syntax

Context

Type of contexts. A Context manages a sequence of instruction. Calling a instruction function will append a instruction to that sequence.

See also Instructions.

procedure

(make-context)  Context?

Creates a context.

parameter

(current-context)  (or/c #f Context?)

(current-context ctx)  void?
  ctx : (or/c #f Context?)
A parameter defines the current context.

procedure

(Context? ctx)  boolean?

  ctx : any/c
Tests whether ctx is a Context.

syntax

Label

Type of labels

procedure

(Label? v)  boolean?

  v : any/c
Tests whether v is a label.

syntax

(label may-id)

 
maybe-id = 
  | id
Creates a label.

When id is given, see also with-labels.

procedure

(label-addr l)  exact-nonnegative-integer?

  l : Label?
Returns the address of label. This should be called after emit-code! is called.

procedure

(:! [#:ctx ctx] l)  void?

  ctx : Context? = (assert (current-context))
  l : Label?
Locates a label in the current code stream of ctx.

procedure

(data! [#:ctx ctx] datum ...)  void?

  ctx : Context? = (assert (current-context))
  datum : (or/c bytes? Imm?)
Writes custom datum into the code stream of ctx.

2.2 Instrcution Operands🔗ℹ

syntax

Size

Equivalent to (U 8 16 32 64 80 128 256).

80 and 256 are currently not used.

syntax

Scale

Equivalent to (U 1 2 4 8)

syntax

Operand

Equivalent to (U Imm Mref Offset Reg)

syntax

Reg

Type of registers

procedure

(Reg? v)  boolean?

  v : any/c
Tests whether v is a register. See also Registers

syntax

GPR

Type of general purpose registers

procedure

(GPR? v)  boolean?

  v : any/c
Tests whether v is a general purpose register. See also Registers

syntax

XMM

Type of xmm registers

procedure

(XMM? v)  boolean?

  v : any/c
Tests whether v is a xmm register. See also Registers

syntax

Seg

Type of segment registers

procedure

(Seg? v)  boolean?

  v : any/c
Tests whether v is a segment register. See also Registers

syntax

IP

Type of instruction pointer registers

procedure

(IP? v)  boolean?

  v : any/c
Tests whether v is a instruction pointer register. See also Registers

syntax

Mref

Type of memory references

procedure

(Mref? v)  boolean?

  v : any/c
Tests whether v is a memory reference.

syntax

(mref size-expr maybe-seg maybe-sib maybe-disp)

 
maybe-seg = 
  | seg-expr :
     
maybe-sib = 
  | base-expr
  | base-expr + index-expr * scale-expr
  | index-expr * scale-expr
     
maybe-disp = 
  | + int/imm-expr
  | - int-expr
Creates a memory reference.

syntax

Imm

Type of immediate numbers

procedure

(Imm? v)  boolean?

  v : any/c
Tests whether v is a immediate number.

procedure

(imm8 num [#:! self!])  Imm?

  num : (or/c integer? Label?)
  self! : (or/c #f Label?) = #f
(imm16 num [#:! self!])  Imm?
  num : (or/c integer? Label?)
  self! : (or/c #f Label?) = #f
(imm32 num [#:! self!])  Imm?
  num : (or/c integer? Label?)
  self! : (or/c #f Label?) = #f
(imm64 num [#:! self!])  Imm?
  num : (or/c integer? Label?)
  self! : (or/c #f Label?) = #f
Creates an immediate number. When a label is given, its address will be used in generated code stream.

When self! is provided, it will point to this immediate number, which may be useful for self-modifying code.

procedure

(rel8 l [#:! self!])  Imm?

  l : Label?
  self! : (or/c #f Label?) = #f
(rel32 l [#:! self!])  Imm?
  l : Label?
  self! : (or/c #f Label?) = #f
Creates an immediate number, and its value will be the offset from the next instruction to l. See also imm8.

procedure

(latent-imm size proc [#:! self!])  Imm?

  size : (or/c 8 16 32 64)
  proc : (-> integer?)
  self! : (or/c #f Label?) = #f
Creates an immediate number, but its value is determined by proc after labels get their address(enabled for label-addr).

syntax

Offset

Type of memory offsets

procedure

(Offset? v)  boolean?

  v : any/c
Tests whether v is a memory offset.

syntax

(moff size-expr maybe-seg int/imm64-expr)

 
maybe-seg = 
  | seg-expr :
Creates a memory offset. Only useful for mov.

2.3 Helper Macros🔗ℹ

syntax

(define-cast id #:type Type #:ctype ctype-expr)

Defines id with type (Nonnegative-Fixnum -> Type), which is used to cast a memory address to a function.

Note: requires from enclosing module would not work inside ctype-expr in typed/racket. Use local-require instead.
(define-cast flfls
  #:type (FlVector FlVector -> Void)
  #:ctype (let ()
            (local-require racket/flonum)
            (_fun (a b) ::
                  (_pointer = (flvector->cpointer a))
                  (_pointer = (flvector->cpointer b))
                  [_size = (flvector-length b)] -> _void)))

syntax

(with-labels maybe-captured (l ...) body ...)

 
maybe-captured = 
  | #:captured
When #:captured is not specified, it is equivalent to
(let ()
  (define l (label)) ...
  (let ()
    body
    ...))

When #:captured is given, (label id) syntax is enabled inside body. When (label id) is used, there is no need to define a label before using it.

syntax

(λ! cast-expr maybe-labels maybe-asm maybe-capture body ...)

 
maybe-labels = 
  | #:labels (l ...)
     
maybe-asm = 
  | #:assembler asm-expr
     
maybe-capture = 
  | #:captured
Creates a context as (current-context), run body, emit-code! via asm-expr or (current-assembler), and use cast-expr to get the returned procedure.

For maybe-labels and maybe-capture, see with-labels.

syntax

(define-λ! id form ...)

Equivalent to

(define id (λ! form ...))

.