2 Assembler

9.2

2 Assembler🔗

This module turns the current module into a assembly language with rudimentary macro opcode support. The macro support is not intended for the generated language but it is to be used for specifying compound "opcodes" for underlying ISA created using define-isa.

It also reprovides the entity and not-entity syntax classes for syntax so that they can be matched (in addition to specific entities) in macro opcodes.

syntax
(define-asm-lang isa)

isa : isa?

Defines and provides appropriate #%module-begin form so that enclosing module can be used as a lang with the s-exp meta-lang. When used as #lang, a module in this language can be run as a program and acts like a front-end to the assembler.

When #:private keyword is at the end of the #lang line, private opcodes are allowed.

The front-end currently supports the following command-line options:

[-o | --output filename] - specifies output filename which defaults to the module name with extension changed from ".rkt" to ".bin".
[-q | --quiet] - suppresses any non-error messages.
[-c | --color] - enable color.
[-n | --no-color] - disable color.
[-v | --verbose] - increases verbosity level, can be specified multiple times.

If used as a stand-alone program, it supports the following options:

[-V | --validate] - validates the ISA by printing its opcode tree, showing any collisions.
[-d | --disassemble fname] - disassembles given binary.
[-u | --unused] - analyzes unused opcode space.
[-c | --color] - enables color output.
[-n | --no-color] - disables color output.
[-a | --addrs] - outputs each disassembled instruction address as an end-of-line comment.
[-x | --hex] - outputs each disassembled instruction hexadecimal value as an end-of-line comment.

syntax
(const id value)

Defines a constant value which can be used in place of immediate values.

2.1 Macro Opcodes🔗

(require ledum/define/asm/macro)

package: ledum-definers

This module contains the the macro opcode specification forms.

syntax
(define-macro-opcode (name arg ...) maybe-doc body ...)

maybe-doc =
| #:doc (doc ...)

Defines macro opcode which gets spliced into the program upon usage. Can use syntax classes.

A default documentation for the macro syntax form is generated. Any prose text can be added to it with the #:doc keyword - as is the case in define-opcode. This is especially useful coupled with the at-exp meta-language.

Take the following example code:
(define-macro-opcode (ldw r w:isa-word)
#:doc @{Loads the word @racket[w] into register @racket[r].}
(define wl (bitwise-and w #xff))
(define wh (bitwise-and (arithmetic-shift w -8) #xff))
(ldl r wl)
(when/pass (> wh 0)
(ldh r wh)))
It produces the documentation as follows:
macro opcode
(ldw r w:isa-word)
Loads the word w into register r.

syntax
(define-macro-opcodes name maybe-doc
((arg ...) body ...) ...)

maybe-doc =
| #:doc (doc ...)

Like define-macro-opcode but for multiple argument patterns.

syntax
(reset-macro-counter)

When used, resets the syntax phase macro counter which is used for caching condition results in when/pass.

syntax
(when/pass condition body ...)

Like when, however for multiple passes in the assembler if in one pass the condition is #t, it will evaluate to #t in all subsequent passes no matter the actual condition expression result in that pass.

syntax
(if/pass condition true-body false-body)

Like when/pass but for if form.

2.2 Assembler Passes🔗

(require ledum/define/asm/passes)

package: ledum-definers

A module implementing a simple multi-pass mechanism required for supporting label resolution.

parameter
(asm-output) → bufwriter?
(asm-output output) → void?
output : bufwriter?

Active bufwriter used for current pass.

parameter
(asm-pass-success) → boolean?
(asm-pass-success success) → void?
success : boolean?

A parameter which should remain #t if none of the labels during given pass changed their value.

parameter
(asm-pass-number) → exact-nonnegative-integer?
(asm-pass-number number) → void?
number : exact-nonnegative-integer?

The current pass number.

syntax
(label id)

id : identifier?

Specifies a label at given position in the code which can be referenced elsewhere.

At the very beginning the label bindings are defined. Then in the first pass they are populated with actual addresses and in the second pass their usage reflects their actual values.

syntax
(maybe-define-label lbls (label id))

A special syntax form used by the assembler to collect all label identifiers first.

procedure
(reset-asm-pass-success) → void?

Resets asm-pass-success to #t. Must be called at the beginning of each pass.

procedure
(asm-offset) → exact-nonnegative-integer?

Current position in the asm-output bufwriter?.

procedure
(asm-labels-resolved?) → boolean?

Returns #t if the pass number is greater than 1.

syntax
(offset off)

off : exact-nonnegative-integer?

Sets the current position in the assembler output writer to given offset off.

syntax
(skip amt)

amt : exact-integer?

Skips given amount amt in the assembler output writer moving the offset relative to current position.

syntax
(data val ...)

val : exact-nonnegative-integer?

Adds given val values into the output at current assembler position.

syntax
(string str)

str : string?

For each character of given string str this form adds a single word to the output stream. Currently only lower 8 bits of each value are added.

syntax
(beddata val ...)

val : exact-nonnegative-integer?

Adds given val values into the output at current assembler position. Each value is considered a big-endian value twice the bit-width of whatever is the configured writer bit-width.

2.3 Buffered Writer🔗

(require ledum/define/asm/writer)

package: ledum-definers

Memory-backed writer with skip and seek capability.

struct
(struct bufwriter (buf pos size bitw))
  buf : vector?
  pos : exact-nonnegative-integer?
  size : exact-nonnegative-integer?
  bitw : exact-positive-integer?

The writer representation contains buf vector? of preallocated length which is always at least as big as size. The current pos can be beyond the end of the buffer which gets automatically extended upon write. The bitw field is used by bufwriter-output.

procedure
(make-bufwriter bitw [initial-prealloc]) → bufwriter?
bitw : exact-positive-integer?
initial-prealloc : exact-positive-integer? = 16

Creates a new bufwriter? of given bitw with initial vector of size initial-prealloc.

procedure
(bufwriter-tell bw) → exact-nonnegative-integer?
bw : bufwriter?

Returns the current position in the writer.

procedure
(bufwriter-write bw v) → void?
bw : bufwriter?
v : exact-nonnegative-integer?

Writes a single value v to the bufwriter bw, incrementing the current position by one and allocating more buffer space if needed. If the write happens past writer current size, it is also increased.

procedure
(bufwriter-skip bw n) → void?
bw : bufwriter?
n : exact-positive-integer?

Moves the current position in the writer by n. No allocations or writes are made - those are handled only upon writes.

procedure
(bufwriter-seek bw n) → void?
bw : bufwriter?
n : exact-nonnegative-integer?

Moves the current position in the writer to n.

procedure
(bufwriter-output bw) → void?
bw : bufwriter?

Serializes given writer to (current-output-port).

2.4 Assembler Printer🔗

(require ledum/define/asm/print)

package: ledum-definers

This module unifies printing of the assembler and disassembler at various verbosity levels.

parameter
(asm-verbosity) → exact-nonnegative-integer?
(asm-verbosity verbosity) → void?
verbosity : exact-nonnegative-integer?

The current verbosity level.

parameter
(asm-color) → boolean?
(asm-color enabled) → void?
enabled : boolean?

If #t the output color is enabled.

syntax
(asm-print maybe-level fmt arg ... maybe-dots)

maybe-level =
| #:1
| #:2
| ...

maybe-dots =
| #:::

fmt : string?
arg : any/c

A simple printf wrapper which prints only if the current verbosity level is equal or greater than the level specified here. Defaults to 1.

If the dots keyword #::: are at the end of the expression, no newline is printed.

contents ← prev up next →

1	Instruction Set Architecture
2	Assembler
3	Device Bus
4	Devices
5	Logging
6	Emulation
7	Arithmetic-Logic Unit
8	Bits
9	Register Bank
10	Ledum Exceptions

2.1	Macro Opcodes
2.2	Assembler Passes
2.3	Buffered Writer
2.4	Assembler Printer