Introduction

What BitterASM is

BitterASM is a metalanguage for constructing assembly languages. It defines the semantics and metaprogramming machinery needed to build an ISA, while assuming essentially nothing about the target architecture itself.

Traditional assemblers bake in a specific architecture: registers, instructions, opcodes, addressing modes, and binary encoding are all privileged, built-in concepts. That works fine until you want something the assembler’s authors didn’t anticipate — a pseudo-instruction, an alternate syntax, a non-binary target, a research architecture. Then you’re stuck extending the assembler itself.

BitterASM inverts this. The language core knows nothing about:

registers, instructions, opcodes, operands, immediates,
addresses, word sizes, endianness, calling conventions,
sections, labels, binary

Every one of those is defined in ordinary BitterASM code — as libraries, architecture packages, and evaluators. The complexity of a real ISA lives where it belongs: in the code describing that ISA, not in the language interpreting it.

The core ideas

Instructions are macros, not language features. mov isn’t a built-in instruction declaration — it’s a macro someone wrote and exposed publicly. There’s no fundamental distinction between a “real” instruction and a “pseudo” one at the language level; both are just macros that expand into some encoding.

Syntax is an interface, not part of the ISA. Because instructions are macros with their own invocation syntax, the same underlying x86 machinery could support mov rax, 3, an arrow-style rax <- 3, or something else entirely — all sharing one architecture implementation underneath.

Abstraction does not imply optimization. What you expand is what you get. If a macro expands clear rax into xor rax, rax, that’s the macro author’s explicit choice. BitterASM never second-guesses it by picking a “faster” sequence on its own. A macro can implement sophisticated code selection, but that logic belongs to the macro author, not the language.

Even bits are a library concept. The only thing BitterASM assumes is Int — an architecture-neutral, arbitrary-precision integer. Binary (bit, bits<N>) is defined in terms of Int in the standard library, not built into the language. 3 is just the mathematical integer three until some library gives it a binary interpretation. This leaves room for architectures that aren’t binary at all.

Evaluators own the output contract, not the language. BitterASM source describes behavior; an evaluator decides what running that behavior produces. A binary evaluator turns assembly into machine code. A different evaluator could target something else entirely. Language semantics (Int, struct, type, macro, pattern matching, imports, generics) mean the same thing everywhere — only the output effect changes.

Imports compose modules; they don’t grant magic. from x86_64.intel import * works because that package defines mov and rax — not because the language has special knowledge of x86. Importing a binary library doesn’t secretly switch the language into “binary mode”; binary is just one ordinary abstraction among many.

Why bother

The payoff for assuming almost nothing is:

• Portability — the same metaprogramming core builds tiny pedagogical ISAs, real architectures like RISC-V, and pathologically complex ones like x86-64, without special-casing any of them.
• Auditable, structured assembly — instructions and their expansions are ordinary, inspectable code rather than opaque tables inside an assembler binary.
• Alternate syntaxes for free — because syntax lives with the macros that define it, an architecture can offer multiple front-ends (native, AT&T-style, “pretty,” even something Pythonic) over one shared implementation.
• Room for the unknown — future architectures that aren’t neatly binary, register-based, or von Neumann at all don’t require changes to BitterASM itself.

The tradeoff is symmetric: the fewer assumptions the language makes, the more an architecture package has to define for itself. That’s the bitter part. The resulting portability, auditability, and extensibility are the sweet part.

Getting started

BitterASM comes as two programs:

• bitterasm, the compiler. It reads .basm source, expands every macro, and writes the values the program emits to a .em file.
• bitter, an evaluator. It reads a .em file and packs its values into machine-code bytes.

Keeping them separate is deliberate. bitterasm knows nothing about bits, bytes or machine code: it only produces a stream of values. What those values mean is up to whichever evaluator reads them, and bitter is the one that turns them into binary. See Evaluators.

This chapter covers:

• Installation: building and installing both programs and the standard library.
• Your first program: assembling two RISC-V instructions, and then a program that emits plain numbers.
• The toolchain: every bitterasm and bitter command.

Installation

BitterASM is built from source and needs a Rust toolchain (cargo). From a clone of the repository:

make install    # or: ./install.sh

The script asks before installing each part:

• bitterasm (the compiler) and bitter (the binary evaluator), into ~/.bitterasm/bin.
• The standard library, copied from std/ to ~/.bitterasm/std.
• Optionally, the bitterasm-lsp language server.

Pass -y to answer yes to every prompt. Add ~/.bitterasm/bin to your PATH if the script tells you to.

Where imports are found

An absolute import such as from std.riscv.native import * is looked up in these directories, in order:

1. The current directory.
2. Each directory in BITTERASM_PATH (separated like PATH).
3. ~/.bitterasm.

So a program anywhere on disk finds the installed std, and a project’s own std/ directory takes priority over it. See Imports.

Checking it works

bitterasm --version
bitter --version

Next: Your first program.

Your first program

Assembling real instructions

Save this as first.basm:

from std.riscv.native import *

add a0, a1, a2
addi a0, a0, 1

33 85 c5 00 13 05 15 00

Then compile it and pack the result:

bitterasm compile first.basm     # writes first.em
bitter encode first.em           # writes first.bin

first.bin holds the eight bytes above: two RV32I instructions, little-endian, exactly what a RISC-V assembler would produce.

Nothing in the language itself knows what add or a0 is. Both are ordinary declarations in the standard library: add is a macro and a0 is a constant. The import brings them into scope, like importing a library in any other language.

Emitting plain values

A program’s output is whatever its macros emit. Here is a program with no architecture at all:

macro show(value: int) {
    @emit value
}

show 1
show 2 + 3
show 'A'

1 5 65

• macro show(value: int) { ... } declares a macro named show that takes one integer.
• @emit adds a value to the program’s output.
• show 1 calls the macro. A line that starts with a macro’s name followed by its arguments is a call, just like an instruction in a traditional assembler.

Compile it and look at the .em file:

bitterasm compile show.basm
cat show.em

{
  "version": 1,
  "requires": [],
  "module": "show",
  "exports": {},
  "entries": [
    { "kind": "Int", "value": "1" },
    { "kind": "Int", "value": "5" },
    { "kind": "Int", "value": "65" }
  ]
}

bitter encode show.em fails, and that’s on purpose. A bare integer has no width, so bitter can’t tell how many bits 5 should take up. Giving it a width is a library’s job: std.binary defines bits<N>, and the RISC-V package builds its instructions out of bits<N> fields. See Packing bytes with bitter.

Next: The toolchain.

The toolchain

bitterasm

compile and check also take lint options (-A, -W, -D, -F) and output options (--diagnostic-format, --color). See Diagnostics and lints. compile --verbose shows progress and timing for each top-level call.

bitter

bitter build runs the whole pipeline, so you don’t need the intermediate .em files. With several inputs, it joins their same-named sections and resolves pub labels across files. See Linking multiple files and Executables.

A typical session

bitterasm check hello.basm            # fast feedback while editing
bitter build hello.basm -o hello      # compile, link and pack
./hello

Basics

A BitterASM program is a text file, usually ending in .basm. This chapter covers what every program is made of: its layout, and the values it computes with.

One statement per line

A newline ends a statement, just as in a traditional assembler:

macro show(value: int) {
    @emit value
}

show 1
show 2

1 2

Inside (), [] and {}, a statement can continue onto the next line, so a long call can be split:

macro add3(a: int, b: int, c: int) -> int {
    @return a + b + c
}

macro show(value: int) {
    @emit value
}

show add3(
    1,
    2,
    3
)

6

Comments

# starts a comment that runs to the end of the line. There are no block comments. ## and #! start doc comments.

# A whole-line comment.
macro show(value: int) {
    @emit value    # a trailing comment
}

show 7

7

Names

Names may contain letters, digits and underscores, and don’t start with a digit. Any Unicode letter counts, so π is a valid name. A name that starts with an underscore marks a parameter as deliberately unused (see Diagnostics and lints).

The only reserved words are from, import, as, in, pub, skip, macro, type, struct, enum, const and section. Everything else, including int and every instruction mnemonic, is an ordinary name.

Order doesn’t matter

A file’s declarations are visible throughout the file, so you can use a macro or constant above the line that declares it:

show LIMIT

const LIMIT = 9

macro show(value: int) {
    @emit value
}

9

What does follow source order is the output: calls emit their values in the order they appear.

What a file can contain

In this chapter

• Integers: the one built-in type.
• Operators: arithmetic, bitwise, comparison and logic.
• Ranges and in: 0..n, and testing membership.
• Characters and strings.
• Constants: naming values with const.

Integers

int is BitterASM’s only built-in type. An int is a mathematical integer: it has arbitrary precision and no width, so it never overflows or wraps.

macro show(value: int) {
    @emit value
}

show 1_000_000 * 1_000_000 * 1_000_000 * 1_000_000

1000000000000000000000000

3 is just the number three, with no bits attached. Bits, bytes, signed and unsigned values are all library types built on int: see bits<N> in Packing bytes with bitter, and Types for how to build types of your own.

Literals

Any literal may use _ between digits for readability: 1_000_000, 0xffff_0000, 0b1010_0101.

macro show(value: int) {
    @emit value
}

show 42
show 0xff
show 0b1010
show 0o17
show 0xff_ff

42 255 10 15 65535

Negative numbers

There are no negative literals. -5 is the negation operator applied to 5, which gives the same result:

macro show(value: int) {
    @emit value
}

show -5
show -(2 + 3)

-5 -5

True and false

There’s no built-in boolean. Conditions are integers: 0 is false and anything else is true. Comparisons and logical operators produce 0 or 1. See Operators.

std.binary does define a bool type (a one-bit bits<1>) with true and false constants, for code that needs a boolean it can emit.

No floating point

There are no fractional numbers in the language. std.decimal provides Decimal and Fraction types, and std.math provides fixed-point arithmetic, square roots, logarithms and trigonometry over them.

Operators

Arithmetic

macro show(value: int) {
    @emit value
}

show 7 / 2
show -7 / 2
show -7 % 2

3 -3 -1

For floor, ceiling or Euclidean division, use std.math.

Bitwise

Integers have no width, so bitwise operators act as if every number had infinitely many bits, in two’s complement. Negative numbers have infinitely many leading ones.

macro show(value: int) {
    @emit value
}

show 0b1100 & 0b1010
show 0b1100 | 0b1010
show 0b1100 ^ 0b1010
show ~0
show 1 << 4
show -16 >> 2

8 14 6 -1 16 -4

Comparison

==, !=, <, <=, > and >= produce 1 for true and 0 for false. == and != also compare structs and enums, field by field.

macro show(value: int) {
    @emit value
}

show 2 < 3
show 2 == 3

1 0

Logic

Any nonzero value counts as true, and the result is always 0 or 1:

macro show(value: int) {
    @emit value
}

show 3 && 4
show 0 || 7
show !5

1 1 0

Precedence

From tightest to loosest binding:

Operators on the same level group left to right. Use parentheses whenever the grouping isn’t obvious, especially when mixing bitwise and comparison operators:

macro show(value: int) {
    @emit value
}

show 1 << 4 | 1
show (6 & 3) == 2

17 1

Since as binds tightly, a + b as T means a + (b as T), and -1 as T means -(1 as T). Write (a + b) as T and (-1) as T. See Conversions.

from std.ctypes import int8_t

macro emit_byte(b: int8_t) {
    @emit b
}

emit_byte -1 as int8_t

`as` binds more tightly than `-`, so `-x as T` means `-(x as T)`; write `(-x) as T`

Ranges and in

Ranges

A range is a run of consecutive integers:

If b is not greater than a (or, for ..=, less than a), the range is empty. Ranges only count upward. For other steps, use std.iter’s range.

A range is mostly used as the source of a @for loop:

macro show(value: int) {
    @emit value
}

@for i in 0..3 {
    show i
}

@for i in 0..=3 {
    show i * 10
}

0 1 2 0 10 20 30

Inside a macro, a range can be stored in a constant and used later. A top-level @for needs its range written in place, because it’s unrolled before anything else in the file is evaluated.

in

value in source is 1 if source contains value, and 0 otherwise. The source can be:

• A range. i in 0..len checks 0 <= i && i < len. Nothing is iterated, so it’s cheap even for a range with a trillion elements.
• A struct value, such as an array or a string. x in arr is true if x equals one of the elements @for would visit: the pub fields that aren’t skip, as described in Struct fields.

macro show(value: int) {
    @emit value
}

show 5 in 0..5
show 5 in 0..=5
show 1000 in 0..1_000_000_000_000
show 'b' in "abc"
show 'z' in "abc"

0 1 1 1 0

in is often used in an @assert:

macro checked_index(idx: int, len: int) {
    @assert idx in 0..len, "index out of bounds"
    @emit idx
}

checked_index 3, 4

3

macro checked_index(idx: int, len: int) {
    @assert idx in 0..len, "index out of bounds"
    @emit idx
}

checked_index 4, 4

index out of bounds

in binds as tightly as <, and a range binds more loosely than anything else, so i + 1 in 0..n + 1 means (i + 1) in 0..(n + 1).

in isn’t for types

x in SomeEnum doesn’t test whether x is a valid variant. in always asks whether a value you have contains something, the same question @for walks through. Asking whether a value belongs to a type is a different question, so it doesn’t share the keyword.

Characters and strings

Characters

A character literal like 'a' is just an int: the character’s Unicode code point. '€' is 0x20AC, whatever machine you target. Characters carry no encoding and no byte order.

macro show(value: int) {
    @emit value
}

show 'A'
show '€'
show '\n'

65 8364 10

A character literal holds exactly one character. The escapes are \n, \r, \t, \0, \\ and \'.

Strings

A string literal like "abc" is a struct with one int field per character (its code point) and a len field:

len counts characters, not bytes. Strings accept the same escapes as characters, with \" in place of \'.

macro show(value: int) {
    @emit value
}

const text = "hé€"
show text.len
show text.__el1

3 233

@for visits a string’s characters, but not its len, which is declared pub skip (see Struct fields):

macro each_char() {
    @for c in "ab" {
        @emit c
    }
}

each_char

97 98

Strings as bytes

A string literal has no encoding until a library gives it one:

• std.array’s array_from_struct("abc") turns it into an Array<int, 3>.
• std.string’s string_from_struct("abc") encodes it as UTF-8, packed into one integer, with a len in bytes.

from std.string import string_from_struct

macro packed() {
    const s = string_from_struct("hi")
    @emit s.value
    @emit s.len
}

packed

26729 2

26729 is 0x6869: the bytes h (0x68) and i (0x69).

To put a string’s bytes in a program, an architecture package provides a directive for it. For example, std.x86_64.nasm has NASM’s db:

msg:
    db "Hello, World!\n"

Constants

const gives a value a name:

const WIDTH = 8
const MASK = (1 << WIDTH) - 1

macro show(value: int) {
    @emit value
}

show MASK

255

A constant can hold any value: an integer, a struct, an enum variant, or a string.

Syntax

const NAME = value
const NAME: Type = value
pub const NAME = value

• : Type converts the value to Type, and checks it, before binding it. See Conversions.
• pub lets other files import the constant. See Visibility.

from std.binary import bits

const BYTE: bits<8> = 200

macro emit_byte(b: bits<8>) {
    @emit b
}

emit_byte BYTE

bits<8> { value: 200 }

A value that doesn’t fit the type is a compile error. bits<8> checks that its value fits in eight bits:

from std.binary import bits

const BYTE: bits<8> = 300

invariant `fits_inside_width(width, value)` was violated for `bits`

Constants never change

There are no variables in BitterASM. A constant is bound once and never reassigned, and nothing in the language can be mutated. To compute a value step by step, use recursion or @fold.

Constants inside macros

Inside a macro body, const names an intermediate value. It’s visible for the rest of that body:

macro hypot_squared(a: int, b: int) {
    const aa = a * a
    const bb = b * b
    @emit aa + bb
}

hypot_squared 3, 4

25

A pub const inside a macro is different: it declares a new top-level constant when the macro is called. See Generating declarations.

Registers are constants

Architecture packages use constants for registers. For example, std.riscv.impl declares each register as a constant of type Reg, a five-bit number:

pub type Reg = bits<5>

@for i in 0..32 {
    pub const x`i` = Reg(i)
}

pub const zero = x0
pub const ra = x1

The x`i` builds the names x0 to x31. See Spliced names.

Doc comments

## documents the item below it, and #! documents the whole file. The text is Markdown.

Syntax

#! What this file is for.

## What this item does.
item

Example

#! Helpers for showing values.

## Emits `value` unchanged.
##
## ```
## show 7
## ```
macro show(value: int) {
    @emit value
}

show 7

7

Doc comments are for the people who use your code. Plain # comments are for the people who maintain it, and are never part of the docs. The two mix freely:

## Emits `value` twice.
# Written as two `@emit`s rather than a loop, to keep the expansion short.
macro twice(value: int) {
    @emit value
    @emit value
}

twice 3

3 3

What can be documented

A ## block documents the next item, as long as only blank lines and # comments sit in between. An item is any of:

• a macro, struct, enum, type alias or const
• a label
• a syntax line
• a struct field or an enum variant

## A 2D point.
struct Point {
    ## Distance from the left edge.
    pub x: int,
    ## Distance from the top edge.
    pub y: int,
}

## Where a program starts.
enum Entry {
    ## At the first instruction.
    Start,
    ## At an offset from it.
    Offset: int,
}

macro show(value: int) {
    @emit value
}

show Point { x: 1, y: 2 }.y

2

An item inside a block is documented the same way, such as each constant a top-level @for generates:

@for i in 0..4 {
    ## Register `i`.
    pub const r`i` = i
}

macro show(value: int) {
    @emit value
}

show r3

3

#! lines only document the file when they come before its first statement.

To turn doc comments into reference pages, see Generating docs.

Where doc comments are ignored

A doc comment that doesn’t document anything is reported by the unused_doc_comments lint. That happens when:

• a ## sits above something that isn’t an item, such as an invocation or an @emit
• a ## is at the end of a file or a block
• a #! comes after the file’s first statement

macro show(value: int) {
    @emit value
}

## Shows seven.
show 7

doc comment documents nothing

Use # for an ordinary comment.

### and longer runs of # are ordinary comments too, so banners such as #### Registers #### never end up in the docs.

Formatting

bitterasm fmt keeps each line’s ## or #! marker. It wraps prose that runs past comment_width, but leaves code blocks, tables and headings exactly as written.

Macros

Macros are how BitterASM does everything. An instruction like add a0, a1, a2 is a call to a macro named add. A “pseudo-instruction” is a macro too, and so is a helper that computes a value. The language draws no line between them.

A macro runs at compile time. It can compute values, check conditions, call other macros, and emit values into the program’s output.

Declaring a macro

macro name(param: Type, ...) -> ReturnType
    | facet ...
{
    body
}

• Parameters each have a name and a type. See Parameters and defaults.
• -> ReturnType is optional. See Returning values.
• Facets (| before ..., | syntax { ... }, …) are optional modifiers, one per line, before the body.
• pub macro lets other files import it. See Visibility.

Two ways to call a macro

As a statement, like an instruction: the name, then its arguments separated by commas, with no parentheses. Whatever the macro emits goes into the output.

As an expression, like a function: the name, then its arguments in parentheses. The call’s value is whatever the macro returns.

macro square(x: int) -> int {
    @return x * x
}

macro show(value: int) {
    @emit value
}

show 3              # statement call
show square(4)      # `square(4)` is an expression call

3 16

A statement call throws away the macro’s return value, so a statement call of square would do nothing. An expression call can’t throw away emitted values, so a macro that emits can only be called as an expression in a few places. See Where emitted values can go.

A macro with no parameters is called by its name alone:

macro nop() {
    @emit 0x13
}

nop
nop

19 19

Inside a macro

A macro’s body is a list of statements:

• Meta keywords such as @emit, @return, @if and @for.
• Calls to other macros, which emit into this macro’s output.
• const declarations naming intermediate values.
• Declarations that the macro generates when it’s called. See Generating declarations.

macro show(value: int) {
    @emit value
}

macro countdown(start: int) {
    @for i in 0..start {
        show start - i
    }
    show 0
}

countdown 3

3 2 1 0

In this chapter

• Parameters and defaults
• Returning values
• Overloading: several macros with one name.
• Recursion: macros that call themselves.
• Hooks: before and after: code that runs around a macro.
• Custom syntax: calls shaped like mov rax, [rbx] or x <- 5.
• Generating declarations: macros that declare constants and types.

Macros can also be generic, and can take other macros as arguments. See Generics.

Parameters and defaults

Parameters

Every parameter has a name and a type:

macro show_sum(a: int, b: int) {
    @emit a + b
}

show_sum 2, 3

5

Arguments are matched to parameters by position. Named arguments like f(b = 1) are only for constructing structs, not for calling macros.

Arguments are type-checked

Each argument must already have its parameter’s type. Nothing is converted automatically, even when a conversion exists:

from std.binary import bits

macro emit_byte(b: bits<8>) {
    @emit b
}

emit_byte 65

type mismatch for `b`: expected `bits<8>`, found `int`

Convert explicitly with as:

from std.binary import bits

macro emit_byte(b: bits<8>) {
    @emit b
}

emit_byte 65 as bits<8>

bits<8> { value: 65 }

Defaults

Parameters at the end of the list can have a default value, used when the call leaves them out:

macro encode(value: int, width: int = 8, mask: int = (1 << width) - 1) {
    @emit value & mask
}

encode 0x1ff
encode 0x1ff, 4

255 15

• A default can use earlier parameters. Defaults are evaluated left to right at each call, so mask above sees whichever width the call ended up with.
• Once one parameter has a default, every parameter after it needs one too.

Unused parameters

An unused parameter triggers the unused_parameter warning. If it’s unused on purpose, for example because only its type matters for overloading, start its name with an underscore:

macro kind(_value: int) {
    @emit 1
}

kind 42

1

Returning values

A macro gives a value back to its caller with @return:

macro max(a: int, b: int) -> int {
    @if a > b {
        @return a
    }
    @return b
}

macro show(value: int) {
    @emit value
}

show max(3, 9)

9

-> int declares the return type. It’s optional, but if it’s there, it’s enforced. It’s also needed when the macro is passed as an argument (see Macros as parameters) or used as a conversion.

The returned value must have the declared type. As with arguments, nothing is converted automatically:

from std.binary import bits

macro byte() -> bits<8> {
    @return 5
}

macro emit_byte(b: bits<8>) {
    @emit b
}

emit_byte byte()

`byte` returned `int`, but its signature declares `-> bits<8>`

Write @return 5 as bits<8> instead.

-> is only about returning. A macro that declares -> T must return a T, so declaring a return type on a macro that only emits is an error:

from std.binary import bits

macro nop() -> bits<8> {
    @emit 0x90 as bits<8>
}

nop

`nop` returned nothing, but its signature declares `-> bits<8>`

To declare what a macro emits, use the emits facet instead: macro nop() | emits bits<8> { ... }.

Returning versus emitting

Every macro has two separate outputs:

A macro may do both. A macro that only emits is like an instruction; a macro that only returns is like a function.

Where emitted values can go

A statement call puts the macro’s emitted values in the output where the call appears. A call used as an expression has nowhere to put emitted values unless it’s the whole of one of these:

• a const’s value: const x = f()
• @return’s value: @return f()

In both cases, the emitted values are kept, in order, where that statement appears. The same goes for @fold in expression position.

macro emit_and_return(x: int) -> int {
    @emit x
    @return x * 10
}

macro caller() {
    const y = emit_and_return(1)
    @emit y
}

caller

1 10

Anywhere else, such as inside a larger expression, calling a macro that emits is an error, because its values would be lost:

macro emit_and_return(x: int) -> int {
    @emit x
    @return x * 10
}

macro caller() {
    @emit 1 + emit_and_return(1)
}

caller

`emit_and_return` emits values, so it can only be used as a statement

Macros that return nothing

Using a macro that returns nothing as a value is an error. A bare @return ends a macro early without a value.

Overloading

Several macros can share a name, as long as their parameters differ. A call picks the one whose parameter types and count fit its arguments:

struct Reg {
    pub n: int,
}

macro describe(r: Reg) {
    @emit 1000 + r.n
}

macro describe(v: int) {
    @emit v
}

describe Reg(3)
describe 3

1003 3

This is how instruction sets handle operand forms: std.x86_64 has one mov for register-to-register, another for an immediate, another for memory, and so on, each with its own encoding.

How a call picks an overload

1. Only overloads that accept the number of arguments are considered, counting defaults.
2. Of those, only overloads whose parameter types match the arguments are considered.
3. A non-generic overload beats a generic one.
4. If more than one candidate is left, the call is ambiguous, which is an error.

macro kind<T>(_x: T) {
    @emit 1
}

macro kind(_x: int) {
    @emit 2
}

kind 5

2

macro g(_a: int, _b: int = 0) {
    @emit 3
}

macro g(_a: int) {
    @emit 4
}

g 1

multiple overloads of `g` accept (int)

Overloads across files

A file’s overloads merge with same-named overloads it imports, from any number of modules. That’s how a dialect adds new operand forms to an instruction it builds on: std.x86_64.nasm adds mov rax, [rel label] alongside every mov from std.x86_64.intel. See Imports.

Recursion

A macro can call itself, directly or through other macros:

macro factorial(n: int) -> int {
    @if n <= 1 {
        @return 1
    }
    @return n * factorial(n - 1)
}

macro show(value: int) {
    @emit value
}

show factorial(20)

2432902008176640000

Limits

Since macros run inside the compiler, a runaway recursion must not crash it, so calls are limited:

• At most 32 nested calls. Deeper than that fails with MacroCallDepthExceeded. The limit counts every nested call, whether it was made as a statement or as an expression.
• Tail calls don’t count. A macro whose @return is exactly a call to itself, like @return gcd(b, a % b), reuses the current call instead of nesting a new one. A tail-call loop can run up to 4,096 times before it fails with MacroTailCallLimitExceeded.

macro gcd(a: int, b: int) -> int {
    @if b == 0 {
        @return a
    }
    @return gcd(b, a % b)
}

macro show(value: int) {
    @emit value
}

show gcd(1071, 462)

21

A call is only a tail call if it’s the whole @return value. @return 1 + f(x) isn’t one. A macro with an after hook never makes tail calls, because its hooks have to run after each call finishes.

Prefer loops for long runs

For anything that repeats more than a few thousand times, use @for or @fold instead. They have no depth limit, and can run up to 1,000,000 iterations:

macro sum_to(n: int) -> int {
    @return @fold total = 0 @for i in 0..=n {
        @next total + i
    }
}

macro show(value: int) {
    @emit value
}

show sum_to(100_000)

5000050000

Hooks: before and after

A macro can declare calls that run every time it’s called: before hooks run first, then the body, then after hooks.

macro show(value: int) {
    @emit value
}

macro traced(x: int) -> int
    | before show(100)
    | after show(result.returned)
{
    @return x + 1
}

traced 1

100 2

Syntax

macro name(params)
    | before hook_call(params...)
    | after hook_call(params..., result.returned)
{
    body
}

• A hook is a macro call. It can use the macro’s parameters.
• In an after hook, result.returned is the value the body returned.
• A macro can have any number of each. They run in the order they’re written.
• Anything a hook emits goes into the output, like the body’s own emits.

Checking arguments

The most common use is a shared check. std.array checks every index once, in a hook, rather than in each macro’s body:

macro oob_check(len: int, index: int) {
    @assert index >= 0, "negative index"
    @assert index < len, "index past the end"
}

macro element_offset(len: int, index: int) -> int
    | before oob_check(len, index)
{
    @return index * 4
}

macro show(value: int) {
    @emit value
}

show element_offset(8, 3)

12

Hooks compose

A hook is an ordinary macro call, so if the hook macro has hooks of its own, they run too. Checks built from hooks keep working however deep the call chain goes.

Hooks change when a macro can tail-call itself: a macro with an after hook never does, because the hook has to run after each call returns.

Custom syntax

By default, a macro is called as its name followed by comma-separated arguments: swap 1, 2. The syntax facet gives a macro any call shape you like. That’s how assembly syntax is built: lw a0, 8(sp), mov rax, [rbx + 8] and x1 = x2 + x3 are all ordinary macros with custom syntax.

macro swap(a: int, b: int)
    | syntax { swap $a$ with $b$ }
{
    @emit b
    @emit a
}

swap 1 with 2

2 1

Patterns

A pattern is a sequence of tokens between { and }:

• $name$ is a capture. The call site can put any expression there, and it becomes the argument for parameter name.
• Anything else is literal: the call site must contain exactly that token.

Every capture must name one of the macro’s parameters. To match a literal ` or $, escape it: \` or \$.

Three kinds of pattern

Anchored patterns start with the macro’s own name, like the swap pattern above. They’re tried only for statements that start with that name, so they’re cheap. Most instruction syntax is anchored.

Unanchored patterns start with something else, usually a capture. They are tried against every statement, so a statement doesn’t need to start with a mnemonic at all:

macro store(dst: int, src: int)
    | syntax { $dst$ <- $src$ }
{
    @emit dst * 100 + src
}

const r1 = 1

r1 <- 7

107

A statement must start with a name, so r1 <- 7 works where 1 <- 7 wouldn’t.

Operand patterns start with a token that can’t begin a statement, such as [. They’re tried wherever an argument starts, and a match becomes an expression call. So an operand pattern belongs on a macro that returns a value:

struct Mem {
    pub addr: int,
}

macro mem(addr: int) -> Mem
    | syntax { [$addr$] }
{
    @return Mem(addr)
}

macro load(dst: int, src: Mem) {
    @emit dst
    @emit src.addr
}

load 1, [0x40]

1 64

[0x40] becomes mem(0x40), a Mem, and overloading picks the load that takes a Mem. This is how std.x86_64.nasm gives [rel label] its own type.

Changing another macro’s syntax

A syntax statement assigns a call shape to a macro declared somewhere else, without touching its declaration:

macro copy(dst: int, src: int) {
    @emit dst
    @emit src
}

syntax copy(dst, src) = { copy $src$ to $dst$ }

copy 5 to 6

6 5

The names in parentheses are the macro’s parameters, which the pattern can capture. This is what makes dialects possible. std.riscv.impl declares every instruction with no syntax of its own. Then:

• std.riscv.native assigns conventional syntax: lw a0, 8(sp).
• std.riscv.c_like assigns C-like syntax to the same macros: a0 = a1 + a2.

A program imports one dialect or the other, and both share one implementation. A file that imports a macro gets the syntax its dialect assigned too. If two imports assign different syntax to the same macro, the importing file must pick one with a syntax statement of its own.

Designing patterns

A capture accepts any expression, and it stops only where the next literal token appears. Two patterns are ambiguous when some statement matches both, so start them differently:

• std.riscv.c_like writes register forms as $rd$ = $rs1$ + $rs2$ and immediate forms as $rd$ <- $rs1$ + $imm$. If both used =, x1 = x2 + imm - 1 would be a valid parse of either one.
• Avoid a literal : right after a leading capture. name: is how a label is written, and that check runs first.

Declare a macro with custom syntax before any statement that uses it in the same file. The parser can misread an earlier call that uses a shape it hasn’t seen yet.

Generating declarations

A macro body can contain declarations: pub const, struct, enum, type, and even macro. Each call to the macro adds them to the program as if they had been written at the top level.

macro declare_word(bits: int) {
    pub const WORD`bits`_BYTES = `bits / 8`
    struct Word`bits` {
        pub value: int,
    }
}

declare_word 16
declare_word 32

macro show(value: int) {
    @emit value
}

macro emit_word(w: Word16) {
    @emit w
}

show WORD32_BYTES
emit_word Word16(7)

4
Word16 { value: 7 }

Two calls generated WORD16_BYTES, Word16, WORD32_BYTES and Word32.

What gets evaluated

When the macro runs, the declaration’s name is evaluated: the backticks in Word`bits` splice in the parameter’s value. See Spliced names.

Everything else is copied into the program as written, and evaluated later where the declaration ends up. There, the macro’s parameters no longer exist.

The one exception is a pub const’s value. Backticks in it are evaluated when the macro runs, so `bits / 8` above becomes 2 or 4. Without the backticks, bits / 8 would refer to a bits that isn’t defined at the top level.

A generated struct, enum, type alias or macro gets no such exception: only its name can use the macro’s parameters.

Inside a macro, pub const and const differ

• const x = ... names a value for the rest of the macro body.
• pub const x = ... generates a top-level constant.

Seeing what was generated

A program that generates declarations gets a generated_declarations warning, as a reminder that it contains code you can’t see in its source. bitterasm expand prints the program with each call replaced by its body, which shows what was generated:

bitterasm expand program.basm

To silence the warning, allow the lint (see Diagnostics and lints).

Meta keywords

Words starting with @ are meta keywords. They control what a macro does while the compiler runs it: emit values, return, check conditions, branch and loop. There are eight:

Nothing a meta keyword does survives into the output except what it emits. There’s no @if at run time on the target machine; that would be an instruction, which is a macro some architecture package provides.

Where they can be used

@emit, @return and @assert only mean something while a macro runs:

const WIDTH = 8

@assert WIDTH % 8 == 0

`@assert` can only be used inside a macro

At the top level, @for and @if repeat or choose statements: they can generate declarations and calls. In a struct declaration they choose fields, and in a construction they choose field values. See Structs.

macro show(value: int) {
    @emit value
}

@for i in 0..3 {
    show i * i
}

@if 2 > 1 {
    show 100
}

0 1 4 100

@emit

@emit adds one value to the program’s output.

Syntax

@emit value

Example

macro bytes3(a: int, b: int, c: int) {
    @emit a
    @emit b
    @emit c
}

bytes3 1, 2, 3

1 2 3

What can be emitted

Any value: an integer, a struct, an enum variant. The compiler doesn’t care what a value means; it just records it in order in the .em file. What the value turns into is the evaluator’s decision. For example, bitter packs a bits<8> into one byte and an instruction struct into its encoding.

from std.binary import bits

struct Pair {
    pub hi: bits<4>,
    pub lo: bits<4>,
}

macro pair(hi: int, lo: int) {
    @emit Pair(hi as bits<4>, lo as bits<4>)
}

pair 0xA, 0xB

Pair { hi: bits<4> { value: 10 }, lo: bits<4> { value: 11 } }

ab

Emitting from nested calls

A macro’s output includes everything emitted by the macros it calls, in order. So an instruction macro can be built from smaller ones.

A call used as an expression can only emit when its values have somewhere to go. See Where emitted values can go.

Restricting what a macro emits: emits

The emits facet declares which types a macro may emit. It’s optional, but if it’s there, it’s enforced: emitting anything else is a compile error. Give several emits facets to allow several types, and use a wildcard to allow any instance of a generic type, as in | emits bits<...>. This is how instruction macros declare what they encode to; -> is only for what a macro returns.

from std.binary import bits

macro byte(value: int)
    | emits bits<8>
{
    @emit value as bits<8>
}

byte 0x41

bits<8> { value: 65 }

from std.binary import bits

macro byte(value: int)
    | emits bits<8>
{
    @emit value
}

byte 0x41

`@emit`ed value has type `int`, but this macro's `emits` facet(s) only declare `bits<8>`

A macro with no emits facet may emit anything.

Emitting moves labels

Each emitted value takes up one position in the output, and a label is the position of the next value emitted after it.

@return

@return ends a macro and, optionally, gives a value back to the caller.

Syntax

@return value
@return

Example

macro clamp(x: int, lo: int, hi: int) -> int {
    @if x < lo {
        @return lo
    }
    @if x > hi {
        @return hi
    }
    @return x
}

macro show(value: int) {
    @emit value
}

show clamp(-5, 0, 10)
show clamp(50, 0, 10)
show clamp(7, 0, 10)

0 10 7

Details

• @return stops the macro at once, even from inside @if, @match, @for or @fold.
• A bare @return ends the macro without a value.
• Values the macro emitted before returning stay emitted.
• @return f(...), where f is the macro itself, is a tail call: it doesn’t count toward the recursion limit. See Recursion.
• @return can return the value of a call that emits, and its emitted values are kept. See Returning values.

Returning early

macro first_multiple_of(k: int, limit: int) -> int {
    @for i in 1..limit {
        @if i % k == 0 {
            @return i
        }
    }
    @return -1
}

macro show(value: int) {
    @emit value
}

show first_multiple_of(7, 100)
show first_multiple_of(700, 100)

7 -1

@assert

@assert stops compilation with an error if a condition is false.

Syntax

@assert condition
@assert condition, "message"

The message is optional, and must be a string literal.

Example

macro shift_amount(n: int) {
    @assert n >= 0 && n < 32, "shift amount must be 0 to 31"
    @emit n
}

shift_amount 5

5

macro shift_amount(n: int) {
    @assert n >= 0 && n < 32, "shift amount must be 0 to 31"
    @emit n
}

shift_amount 40

shift amount must be 0 to 31

Details

• The condition is true if it’s not 0.
• A passing @assert emits nothing and has no other effect.
• The error points at the @assert that failed.

Asserts, hooks and invariants

An @assert checks something at one point in one macro. For checks that apply more broadly:

• To check the arguments of several macros the same way, put the asserts in one macro and call it from a before hook.
• To check every value of a type, wherever it’s made, use an invariant.

@if and @else

@if runs its body only when a condition is true. An optional @else body runs otherwise.

Syntax

@if condition {
    ...
}

@if condition {
    ...
} @else {
    ...
}

@else goes on the same line as the closing }.

Example

macro abs(x: int) -> int {
    @if x < 0 {
        @return -x
    } @else {
        @return x
    }
}

macro show(value: int) {
    @emit value
}

show abs(-4)
show abs(4)

4 4

More than two branches

There’s no @else @if. Nest another @if inside the @else, or use @match:

macro sign(x: int) {
    @if x < 0 {
        @emit -1
    } @else {
        @if x == 0 {
            @emit 0
        } @else {
            @emit 1
        }
    }
}

sign -5
sign 0
sign 9

-1 0 1

Choosing an encoding

@if is how an instruction picks between encodings. For example, it might use a short form when an immediate fits:

macro load_imm(value: int) {
    @if value in -2048..2048 {
        @emit 1    # one instruction
    } @else {
        @emit 2    # two instructions
    }
}

load_imm 100
load_imm 100_000

1 2

The choice is explicit and visible in the macro. BitterASM never swaps in a “better” encoding on its own.

Outside macros

At the top level, @if includes or skips statements, including declarations:

const DEBUG = 1

macro show(value: int) {
    @emit value
}

@if DEBUG {
    show 0xdeb
}

3563

In a struct declaration or construction, it includes or skips fields. See Structs.

@match

@match compares a value against a list of patterns and runs the first arm that matches.

Syntax

@match value {
    pattern => { ... }
    pattern => { ... }
    _ => { ... }
}

Arms are tried from top to bottom. _ matches anything. If no arm matches, nothing happens. Commas between arms are optional.

Matching values

A pattern that’s an ordinary expression matches if it equals the value:

macro name_length(n: int) {
    @match n {
        0 => { @emit 4 }        # "zero"
        1 => { @emit 3 }        # "one"
        1 + 1 => { @emit 3 }    # "two"
        _ => { @emit -1 }
    }
}

name_length 0
name_length 2
name_length 7

4 3 -1

Matching enums

Matching is most useful with enums. Name a variant by itself, or qualified by its enum:

enum Color {
    Red,
    Green,
    Blue,
}

macro code(c: Color) {
    @match c {
        Red => { @emit 1 }
        Color.Green => { @emit 2 }
        _ => { @emit 3 }
    }
}

code Color.Red
code Color.Green
code Color.Blue

1 2 3

For a variant with a payload, Variant(name) binds the payload to name for that arm. Variant(_) matches any payload without binding it.

enum Shape {
    Circle: int,
    Square: int,
    Empty,
}

macro area(s: Shape) {
    @match s {
        Shape.Circle(r) => { @emit 3 * r * r }
        Square(w) => { @emit w * w }
        Empty => { @emit 0 }
    }
}

area Shape.Circle(2)
area Shape.Square(5)
area Shape.Empty

12 25 0

Variant(expression), where the expression isn’t a plain name, matches only when the payload equals it. Qualified forms work the same way: Shape.Circle(r), and for a generic enum, Option<int>.Some(v).

A pattern that isn’t a variant, such as a constant holding an enum value, is compared with ==:

enum Color {
    Red,
    Green,
    Blue,
}

const FAVORITE = Color.Blue

macro is_favorite(c: Color) {
    @match c {
        FAVORITE => { @emit 1 }
        _ => { @emit 0 }
    }
}

is_favorite Color.Blue
is_favorite Color.Red

1 0

Returning from a match

@return inside an arm returns from the whole macro:

from std.option import Option

macro unwrap_or(o: Option<int>, fallback: int) -> int {
    @match o {
        Option<int>.Some(v) => { @return v }
        None => { @return fallback }
    }
}

macro show(value: int) {
    @emit value
}

show unwrap_or(Option<int>.Some(42), 0)
show unwrap_or(Option<int>.None, 7)

42 7

@for

@for runs its body once for each element of a source, binding the element to a name.

Syntax

@for name in source {
    ...
}

Looping over a range

macro squares(n: int) {
    @for i in 0..n {
        @emit i * i
    }
}

squares 5

0 1 4 9 16

See Ranges for .. and ..=.

Looping over a struct

A struct value works as a source too. @for visits its pub fields in declaration order, skipping fields marked skip. That’s how you loop over an array or a string:

from std.array import Array

macro sum<const N: int>(values: Array<int, N>) -> int {
    const total = @fold acc = 0 @for v in values {
        @next acc + v
    }
    @return total
}

macro each_char() {
    @for c in "hi" {
        @emit c
    }
}

macro show(value: int) {
    @emit value
}

show sum(Array<int, 3> { __el0: 1, __el1: 2, __el2: 3 })
each_char

6 104 105

See Struct fields: pub and skip.

Details

• Each iteration is fresh. Nothing carries over from one iteration to the next: a const in the body only exists for that iteration. To carry a value along, such as a running total, use @fold.
• @return ends the whole macro, not just the loop.
• At most 1,000,000 iterations.
• At the top level, the source must be a range written in place, such as 0..32. The loop is unrolled before anything else in the file is evaluated, so it can generate declarations:

@for i in 0..4 {
    pub const r`i` = i * 10
}

macro show(value: int) {
    @emit value
}

show r3

30

That’s how architecture packages declare their registers. The backticks in r`i` build each name; see Spliced names.

In struct declarations and constructions

@for can also generate a struct’s fields, or the values of a construction. See Structs.

@fold and @next

@fold is a @for that carries values from one iteration to the next. These values are called accumulators. @next ends an iteration and gives the accumulators their values for the next one.

Syntax

@fold acc = initial @for x in source {
    ...
    @next new_value
}

@fold a = 0, b = 0 @for x in source {
    ...
    @next a = new_a, b = new_b
}

Example: a running total

macro sum_to(n: int) -> int {
    @return @fold total = 0 @for i in 0..=n {
        @next total + i
    }
}

macro show(value: int) {
    @emit value
}

show sum_to(10)

55

The fold starts with total = 0. Each iteration sees the current total, and @next total + i gives the next iteration its new total. The fold’s value is the final total.

Example: offsets into a table

A fold can emit, too. This one emits each entry’s offset, then the table’s total size:

from std.array import Array

macro offsets<const N: int>(lengths: Array<int, N>) {
    const table_size = @fold offset = 0 @for len in lengths {
        @emit offset
        @next offset + len
    }
    @emit table_size
}

offsets Array<int, 3> { __el0: 4, __el1: 2, __el2: 5 }

0 4 6 11

Several accumulators

Separate accumulators with commas. @next then names each one it changes. The fold’s value is a struct with one field per accumulator:

macro stats(n: int) {
    const r = @fold count = 0, evens = 0 @for i in 0..n {
        @if i % 2 == 0 {
            @next count = count + 1, evens = evens + 1
        }
        @next count = count + 1
    }
    @emit r.count
    @emit r.evens
}

stats 5

5 3

How @next works

• @next ends the iteration, like continue in other languages. Code after it in the same iteration doesn’t run.
• Accumulators @next doesn’t name keep their values, and an iteration that reaches no @next at all keeps every value. So filtering needs no @else: @if keep { @next total + x }.
• Nothing is mutated. Each iteration binds fresh values, the same way @for binds its loop variable.
• @next belongs to the innermost @fold in the same macro body. Using it inside a plain @for nested in the fold, or in a macro called from the fold, is an error.
• A fold whose body has no @next at all gets the fold_without_next warning, since its accumulators could never change.

Statement or expression

• As an expression, such as a const’s value or @return’s value, a fold gives its final accumulators. Its emitted values are kept.
• As a statement, its value is ignored. That’s what you want when the body only emits.

No depth limit

A fold runs as many iterations as its source has elements, up to @for’s limit of 1,000,000. That makes it the tool for long computations that recursion, limited to 32 nested calls or 4,096 tail calls, can’t handle.

Everywhere @for works

At the top level the fold is unrolled before anything else, like a top-level @for. The source must be a range written in place, and the accumulators are integers. const x = @fold ... names the result, which can then bound a later top-level @for:

const total = @fold acc = 0 @for i in 0..4 {
    @next acc + i
}

macro show(value: int) {
    @emit value
}

show total

6

In a struct construction, a fold can compute field values:

from std.array import Array

macro prefix_sums() -> Array<int, 4> {
    @return Array<int, 4> {
        @fold acc = 0 @for i in 0..4 {
            __el`i`: acc + i,
            @next acc + i
        }
    }
}

macro show_all<const N: int>(values: Array<int, N>) {
    @for v in values {
        @emit v
    }
}

show_all prefix_sums()

0 1 3 6

In a struct declaration, a fold can compute field names. There, the accumulators must be integers.

Types

BitterASM has exactly one built-in type, int. Every other type is declared in BitterASM code, usually in a library:

Types can be generic: bits<8> and Array<int, 4> are instances of generic structs.

Why types matter

Types exist only at compile time. The compiler uses them to:

• Check arguments. A macro that takes a Reg rejects anything that isn’t a Reg.
• Pick overloads. mov rax, rbx and mov rax, 5 call different mov macros because rbx and 5 have different types. See Overloading.
• Enforce rules. An invariant such as “fits in 8 bits” or “is even” is checked every time a value of the type is made.
• Describe output. A struct’s fields tell an evaluator like bitter how to lay out bits. See Packing bytes with bitter.

No automatic conversions

A value never changes type on its own. To turn one type into another, convert it explicitly with as:

from std.binary import bits

macro emit_byte(b: bits<8>) {
    @emit b
}

emit_byte 65 as bits<8>

bits<8> { value: 65 }

Equality

== and != work on any two values: structs compare field by field, and enums compare variant and payload.

In this chapter

• Structs: declaring, constructing and reading them.
• Struct fields: pub and skip: visibility and iteration.
• Enums: a value that is one of several variants.
• Type aliases: new names for types, and new types with rules.
• Invariants: rules every value of a type must follow.
• Conversions: as, to and from.

Structs

A struct groups named fields into one value.

Declaring a struct

struct Name {
    field: Type,
    pub field: Type,
    pub field: Type = default,
}

• Fields are separated by commas or newlines; a trailing comma is fine.
• pub makes a field readable from other files, and visible to @for. See Struct fields.
• = default gives a value used when a construction leaves the field out.
• pub struct lets other files import the struct itself.
• Facets such as invariant go between the name and the {.

Constructing a struct

There are three ways to build a struct value:

struct Point {
    pub x: int,
    pub y: int = 5,
}

macro emit_point(p: Point) {
    @emit p
}

emit_point Point(1, 2)            # positional
emit_point Point(x = 3)           # named; y uses its default
emit_point Point { x: 4, y: 6 }   # braces

Point { x: 1, y: 2 }
Point { x: 3, y: 5 }
Point { x: 4, y: 6 }

Every field without a default must be given a value:

struct Point {
    pub x: int,
    pub y: int,
}

macro emit_point(p: Point) {
    @emit p
}

emit_point Point(1)

`Point` expects 2 argument(s), but 1 were supplied

A generic struct is constructed with braces: Pair<int> { a: 1, b: 2 }.

Reading fields

Use .field:

struct Point {
    pub x: int,
    pub y: int,
}

macro show(value: int) {
    @emit value
}

const p = Point(3, 4)
show p.x * p.x + p.y * p.y

25

Values are never modified. To “change” a field, build a new struct.

Structs as machine code

When an evaluator like bitter packs a struct, it concatenates its fields, first field in the most significant bits. That’s how an instruction format is described. Here’s RISC-V’s R-type format from std.riscv.impl:

pub struct RType {
    funct7: Funct7,     # bits<7>
    rs2: Reg,           # bits<5>
    rs1: Reg,           # bits<5>
    funct3: Funct3,     # bits<3>
    rd: Reg,            # bits<5>
    opcode: Opcode,     # bits<7>
}

A 32-bit instruction is just a struct whose fields add up to 32 bits. See Packing bytes with bitter.

Generating fields

A struct’s fields can be generated with @for and @if, using the struct’s generic parameters. This is how std.array declares an array of any length:

pub struct Array<T, const N: int>
    | invariant N >= 0
{
    @for i in 0..N {
        pub __el`i`: T,
    }

    pub skip len: int = N,
}

macro show_all<const N: int>(values: Array<int, N>) {
    @for v in values {
        @emit v
    }
}

show_all Array<int, 3> { __el0: 7, __el1: 8, __el2: 9 }

7 8 9

A construction can generate its field values the same way:

from std.array import Array

macro squares<const N: int>(_len: Array<int, N>) -> Array<int, N> {
    @return Array<int, N> {
        @for i in 0..N {
            __el`i`: i * i,
        }
    }
}

macro show_all<const N: int>(values: Array<int, N>) {
    @for v in values {
        @emit v
    }
}

show_all squares(Array<int, 4> { __el0: 0, __el1: 0, __el2: 0, __el3: 0 })

0 1 4 9

__el`i` builds the field names __el0, __el1, … See Spliced names.

Struct fields: pub and skip

Two keywords change how a field can be used: pub and skip.

Every field is part of the value either way: all of them are emitted, and all of them are packed by bitter.

pub: visibility

A field without pub is private to the file (module) that declares the struct. Other files can’t read it with .field, or supply it by name when constructing the struct.

Say shapes.basm declares a struct with one public and one private field:

pub struct Circle {
    pub radius: int,
    area_cache: int,
}

pub macro circle(r: int) -> Circle {
    @return Circle(r, 3 * r * r)
}

Another file can read radius, but not area_cache:

from .shapes import circle

macro show(value: int) {
    @emit value
}

show circle(2).radius

2

from .shapes import circle

macro show(value: int) {
    @emit value
}

show circle(2).area_cache

field `area_cache` of `Circle` is private to the module that declared it

A few things still work with private fields:

• Positional construction, like Circle(2, 12), from any file, since it names no fields.
• The struct’s own code, meaning its invariants, field defaults and conversions. These always run as part of the declaring file, whoever triggered them.

pub: iteration

@for x in value and x in value only see pub fields. A private field is treated as internal bookkeeping, not as one of the struct’s elements.

skip

pub skip marks a field that’s fully public, but isn’t one of the struct’s elements. @for and in pass over it.

std.array’s Array<T, N> is the example. Its len must be readable by anyone, but a loop over an array should see only its elements:

pub struct Array<T, const N: int>
    | invariant N >= 0
{
    @for i in 0..N {
        pub __el`i`: T,
    }

    pub skip len: int = N,
}

macro walk<const N: int>(arr: Array<int, N>) {
    @for x in arr {
        @emit x
    }
    @emit arr.len
}

walk Array<int, 2> { __el0: 7, __el1: 8 }

7 8 2

Without skip, the loop would visit len as a third element. String literals work the same way: their len is pub skip.

skip on a private field is allowed, but does nothing, since private fields are already left out.

Enums

An enum is a value that is exactly one of a fixed list of variants.

Declaring an enum

enum Name {
    Variant,
    Variant: PayloadType,
}

A variant can carry one value of a given type, its payload, or nothing. pub enum lets other files import it.

enum Endian {
    Little,
    Big,
}

enum Operand {
    Register: int,
    Immediate: int,
    None,
}

macro emit_it(o: Operand) {
    @emit o
}

emit_it Operand.Register(3)
emit_it Operand.None

Operand.Register(3)
Operand.None

Making a value

Write the enum’s name, a dot and the variant. Add the payload in parentheses:

Using a value

Compare with ==, or take it apart with @match:

enum Operand {
    Register: int,
    Immediate: int,
    None,
}

macro describe(o: Operand) {
    @match o {
        Register(n) => { @emit 100 + n }
        Immediate(v) => { @emit v }
        None => { @emit -1 }
    }
}

describe Operand.Register(3)
describe Operand.Immediate(42)
describe Operand.None

103 42 -1

Generic enums

An enum can be generic. std.option declares:

pub enum Option<T> {
    Some: T,
    None
}

Write the type arguments when making a value: Option<int>.Some(42) and Option<int>.None. They aren’t inferred:

from std.option import Option

macro emit_option(o: Option<int>) {
    @emit o
}

emit_option Option.Some(42)

`Option` expects 1 generic argument(s), but 0 were supplied

Enums as settings

An enum can be a const generic parameter, which makes it a good fit for options that are fixed at compile time. std.string uses Endian this way: Utf8String<5, Endian.Little>.

Enums and output

An evaluator decides what an emitted enum means. bitter has no layout for enums in general, so emitting one to bitter is an error, with one exception: std.bitter.deferred’s Deferred, which it resolves to a number. To put an enum in machine code, convert it to a bits<N> first.

Type aliases

type declares a new name for a type.

Syntax

type Name = ExistingType
type Name = ExistingType
    | invariant condition

pub type lets other files import it.

Plain aliases: just a new name

Without an invariant, an alias is simply another name for its type. The two are interchangeable:

from std.binary import bits

type Reg = bits<5>

macro use_reg(r: Reg) {
    @emit r
}

use_reg Reg(3)           # construct through the alias
use_reg 4 as bits<5>     # a bits<5> is a Reg

bits<5> { value: 3 }
bits<5> { value: 4 }

Architecture packages use plain aliases to make their types self-documenting. In std.riscv.impl, Reg, Opcode, Funct3 and Imm12 are all aliases of bits<N>.

Aliases with invariants: a new type

With an invariant, an alias becomes a distinct type with a rule. A value only becomes one through as, which checks the rule:

from std.binary import bits

type EvenByte = bits<8>
    | invariant v % 2 == 0

macro use_even(b: EvenByte) {
    @emit b
}

use_even 6 as EvenByte

bits<8> { value: 6 }

A plain bits<8> isn’t an EvenByte, even if its value is even, because nothing checked it:

from std.binary import bits

type EvenByte = bits<8>
    | invariant v % 2 == 0

macro use_even(b: EvenByte) {
    @emit b
}

use_even 6 as bits<8>

type mismatch for `b`: expected `EvenByte`, found `bits<8>`

And as rejects values that break the rule:

from std.binary import bits

type EvenByte = bits<8>
    | invariant v % 2 == 0

macro use_even(b: EvenByte) {
    @emit b
}

use_even 7 as EvenByte

was violated for `EvenByte`

Naming the value in an invariant

In an alias’s invariant, the value being checked can have any name that isn’t already declared: v above, x in std.ctypes. The compiler takes the one free name in the condition to mean the value. Using two different free names is an error.

Aliases of int

A struct produced by as remembers which alias checked it. A plain integer has nowhere to record that, so an alias of int works differently: wherever an int is used as one, as an argument, a struct field or a return value, the alias’s rule is checked right there. std.unsigned’s uint is an example:

from std.unsigned import uint

macro count(n: uint) {
    @emit n
}

count 5
count 6 as uint

5 6

from std.unsigned import uint

macro count(n: uint) {
    @emit n
}

count -1

invariant `(x >= 0)` was violated for `uint`

If a macro has overloads for both int and an alias of int, a plain integer picks the int one.

Generic aliases

An alias can take generic parameters. Each use substitutes its arguments into the alias’s target and invariants:

from std.binary import bits

type Word<const n: int> = bits<n>

type Aligned<const n: int> = bits<16>
    | invariant v % n == 0

macro emit_word(w: Word<12>) {
    @emit w
}

macro emit_aligned(a: Aligned<4>) {
    @emit a
}

emit_word 5 as bits<12>
emit_aligned 8 as Aligned<4>

bits<12> { value: 5 }
bits<16> { value: 8 }

Word<12> is just another name for bits<12>. Aligned<4> and Aligned<2> are different types, each with its own rule:

from std.binary import bits

type Aligned<const n: int> = bits<16>
    | invariant v % n == 0

macro emit_aligned(a: Aligned<4>) {
    @emit a
}

emit_aligned 8 as Aligned<2>

expected `Aligned<4>`, found `Aligned<2>`

Layers

An alias can be built on another type that has rules of its own. Converting with as checks every layer, from the outside in. std.ctypes declares uint8_t as a bits<8> whose value is at least zero, so as uint8_t checks x >= 0, then bits<8>’s own rule that the value fits in eight bits:

from std.ctypes import *

macro emit_byte(b: uint8_t) {
    @emit b
}

emit_byte 200 as uint8_t

bits<8> { value: 200 }

from std.ctypes import *

macro emit_byte(b: uint8_t) {
    @emit b
}

emit_byte (-1) as uint8_t

invariant `(x >= 0)` was violated for `uint8_t`

Note the parentheses in (-1) as uint8_t. as binds more tightly than -, so -1 as uint8_t would mean -(1 as uint8_t).

Invariants

An invariant is a rule that every value of a type must follow. It’s checked every time a value of the type is made, so a value that exists is known to be valid.

Syntax

struct Name
    | invariant condition
{
    fields
}

type Name = Type
    | invariant condition

A type can have several invariants, and all of them must hold.

On structs

A struct’s invariant can use its fields and its generic parameters. Refer to a field by its bare name or as source.field; both work.

struct Range
    | invariant lo <= hi
{
    pub lo: int,
    pub hi: int,
}

macro size(r: Range) -> int {
    @return r.hi - r.lo
}

macro show(value: int) {
    @emit value
}

show size(Range(2, 10))

8

struct Range
    | invariant lo <= hi
{
    pub lo: int,
    pub hi: int,
}

macro size(r: Range) -> int {
    @return r.hi - r.lo
}

macro show(value: int) {
    @emit value
}

show size(Range(10, 2))

invariant `(lo <= hi)` was violated for `Range`

It’s checked at every construction, in any form: Range(10, 2), Range(lo = 10, hi = 2), Range { lo: 10, hi: 2 }, or conversion with as.

bits<N> is an invariant

The standard library’s most important type is a struct with one invariant. From std.binary:

pub struct bits<const width: int>
    | invariant fits_inside_width(width, value)
{
    pub skip value: int
}

bits<8> is an integer that’s been checked to fit in 8 bits. An instruction field typed bits<5> therefore can’t be handed a register number of 40.

Sharing checks

The condition can call macros, so a rule used by several types can live in one place. That’s what fits_inside_width above is:

pub macro fits_inside_width(width: int, value: int) -> bool {
    @return value >= 0 && value < (1 << width)
}

On type aliases

An invariant on a type alias turns it into a new type that only as can produce. The value being checked can have any free name. See Type aliases.

from std.binary import bits

type Imm12 = bits<12>
    | invariant n % 4 == 0

macro emit_offset(offset: Imm12) {
    @emit offset
}

emit_offset 64 as Imm12

bits<12> { value: 64 }

Invariants versus @assert

An invariant may use the struct’s private fields, since it always runs as part of the file that declared the struct.

Conversions: as, to and from

Values never change type on their own. as converts a value explicitly:

value as Type

as binds more tightly than any operator, so put a compound expression in parentheses: (a + b) as T, (-1) as T.

The same conversion happens when a const has a type: const b: bits<8> = 65 means const b = 65 as bits<8>.

What as does

as tries these steps, in order:

1. Same type: nothing to do.
2. A conversion the types declare, with a to or from facet. See below.
3. A type alias: check the alias’s invariants, then convert to the type underneath. See Type aliases.
4. A struct with one field: wrap the value in that field, converting it to the field’s type, and check the struct’s invariants. This is how 65 as bits<8> works: bits<8> has a single field, value.

If nothing applies, it’s an error.

from std.binary import bits

macro emit_byte(b: bits<8>) {
    @emit b
}

emit_byte 65 as bits<8>

bits<8> { value: 65 }

Declaring conversions: to and from

A struct or type alias can declare conversions with facets, each naming a macro that performs one:

• | to f(source), on the type being converted from: how to turn this type into something else.
• | from f(source), on the type being converted to: how to make this type from something else.

In the facet, source is the value being converted. as T uses a conversion when its macro returns T and accepts source’s type.

struct Cents
    | to cents_to_int(source)
    | from dollars_to_cents(source)
{
    pub amount: int,
}

macro cents_to_int(c: Cents) -> int {
    @return c.amount
}

macro dollars_to_cents(dollars: int) -> Cents {
    @return Cents(dollars * 100)
}

macro show(value: int) {
    @emit value
}

show (3 as Cents).amount
show Cents(250) as int

300 250

A type can declare any number of each. If more than one conversion fits, the as is ambiguous, which is an error. std.decimal’s Decimal and Fraction use this to convert between each other and int.

Converting to a generic type: target

In a conversion to a generic type, target holds the destination type’s const parameters, by name. as Fixed<4> sees target.scale as 4:

struct Fixed<const scale: int>
    | from int_to_fixed(source, target.scale)
{
    pub raw: int,
}

macro int_to_fixed(n: int, scale: int) -> Fixed {
    @return Fixed<scale> { raw: n << scale }
}

macro emit_fixed(f: Fixed<4>) {
    @emit f
}

emit_fixed 3 as Fixed<4>

Fixed<4> { raw: 48 }

std.string uses target the same way, to convert to Utf8String<len, endian> with the length and byte order the caller asked for.

Writing conversion macros

A conversion macro is matched like an ordinary call: as passes it the facet’s arguments, infers its generic parameters, and checks that it returns the destination type.

• It can be generic, and its return type can use a wildcard:

struct Fixed<const scale: int>
    | to fixed_to_int(source)
{
    pub raw: int,
}

macro fixed_to_int<const S: int>(f: Fixed<S>) -> int {
    @return f.raw >> S
}

macro show(value: int) {
    @emit value
}

show (Fixed<4> { raw: 80 }) as int

5

• A conversion whose macro doesn’t accept the source is simply for other types, and as moves on to the next one.
• It must declare its return type, or as can’t tell what it converts to:

struct Cents
    | from dollars_to_cents(source)
{
    pub amount: int,
}

macro dollars_to_cents(dollars: int) {
    @return Cents(dollars * 100)
}

macro emit_cents(c: Cents) {
    @emit c
}

emit_cents 3 as Cents

conversion macro `dollars_to_cents` must declare its return type

Generics

A generic declaration takes parameters in angle brackets, so one declaration covers a whole family of types or macros. bits<8> and bits<32> are two types made from one generic struct, bits<const width: int>.

Two kinds of parameter

Structs, enums, type aliases and macros can all be generic.

Generic structs

struct Pair<T> {
    pub a: T,
    pub b: T,
}

macro emit_pair(p: Pair<int>) {
    @emit p
}

emit_pair Pair<int> { a: 1, b: 2 }

Pair<int> { a: 1, b: 2 }

A generic struct is constructed with braces, naming its arguments: Pair<int> { ... }. The Name(...) form is only for non-generic structs.

Generic enums work the same way. See Enums.

Generic macros

A generic macro’s parameters are inferred from its arguments. You never write them at the call:

struct Pair<T> {
    pub a: T,
    pub b: T,
}

macro first<T>(p: Pair<T>) -> T {
    @return p.a
}

macro show(value: int) {
    @emit value
}

show first(Pair<int> { a: 5, b: 6 })

5

Inside the macro, a const parameter is an ordinary value, and a type parameter can be used anywhere a type can.

A generic overload loses to a non-generic one that also fits. See Overloading.

In this chapter

• Const parameters: values in types, like bits<8> and Array<T, N + 1>.
• Wildcards: ...: accepting any argument without naming it.
• Macros as parameters: passing a macro to a macro.

Const parameters

A const parameter puts a compile-time value into a type. bits<8> and bits<16> are different types, because their width differs.

Syntax

struct Name<const N: int> { ... }
macro name<const N: int>(x: Type<N>) { ... }

A const parameter’s type can be int or an enum:

from std.binary import Endian

struct Word<const width: int, const order: Endian> {
    pub value: int,
}

macro emit_word(w: Word<16, Endian.Big>) {
    @emit w
}

emit_word Word<16, Endian.Big> { value: 1 }

Word<16, 1> { value: 1 }

In the output, an enum argument is recorded as its variant’s position in the enum: Endian.Big is 1, because it’s Endian’s second variant.

Using the value

Inside the declaration, a const parameter is an ordinary value. A struct can use it in its fields, defaults and invariants, and a macro can use it in its body:

from std.binary import bits

macro width_of<const W: int>(_b: bits<W>) -> int {
    @return W
}

macro show(value: int) {
    @emit value
}

show width_of(3 as bits<12>)

12

Computing types

A type argument can be any expression, including one built from other parameters. std.array’s appended returns an array one element longer than its argument:

pub macro appended<T, const N: int>(
    arr: Array<T, N>,
    value: T
) -> Array<T, N + 1>

from std.binary import Endian

struct Word<const width: int, const order: Endian> {
    pub value: int,
}

macro widen<const N: int>(w: Word<N, Endian.Big>) -> Word<N * 2, Endian.Big> {
    @return Word<N * 2, Endian.Big> { value: w.value }
}

macro emit_word(w: Word<32, Endian.Big>) {
    @emit w
}

emit_word widen(Word<16, Endian.Big> { value: 3 })

Word<32, 1> { value: 3 }

Generating fields from a parameter

A struct’s fields can depend on its const parameters through @for and @if. That’s how Array<T, N> has exactly N elements.

Wildcards: ...

In a parameter’s type, ... accepts any argument in that position without naming it.

from std.array import Array

macro count(arr: Array<int, ...>) -> int {
    @return arr.len
}

macro show(value: int) {
    @emit value
}

show count(Array<int, 2> { __el0: 1, __el1: 2 })
show count(Array<int, 3> { __el0: 1, __el1: 2, __el2: 3 })

2 3

... versus a named parameter

Both of these accept an array of any length:

macro count(arr: Array<int, ...>) -> int
macro count<const N: int>(arr: Array<int, N>) -> int

Use a named parameter when the macro needs the value as a type argument, for example to declare its return type as Array<int, N + 1>. Use ... when it doesn’t. The value is usually still available from the argument itself, like arr.len above.

In return types

... in a return type says the macro returns some instance of a generic type, decided by its body. std.bitfield’s field returns a bits<N> whose width depends on its arguments:

pub macro field(value: int, hi: int, lo: int) -> bits<...> {
    @return bits<hi - lo + 1> { value: slice(value, hi, lo) }
}

Mixing

Wildcards and named parameters can be mixed: Array<T, ...> names the element type and accepts any length. std.array’s get, updated and reversed all take an Array<T, ...>.

Macros as parameters

A macro can take another macro as an argument, and call it.

macro double(x: int) -> int {
    @return x * 2
}

macro apply_twice<F: Fn(int) -> int>(f: F, x: int) -> int {
    @return f(f(x))
}

macro show(value: int) {
    @emit value
}

show apply_twice(double, 5)

20

Syntax

macro name<F: Fn(ParamType, ...) -> ReturnType>(f: F, ...) { ... }

• F is an ordinary type parameter, with a bound: Fn(int) -> int describes the signature a macro must have to be passed as F.
• The parameter f: F receives the macro. Call it like any macro: f(x).
• Pass a macro by its name, with no parentheses: apply_twice(double, 5).
• -> ReturnType can be left off: Fn(int).

The bound is checked at the call

Passing a macro whose signature doesn’t match is an error at the call site, before the body runs:

macro add(x: int, y: int) -> int {
    @return x + y
}

macro apply<F: Fn(int) -> int>(f: F, x: int) -> int {
    @return f(x)
}

macro show(value: int) {
    @emit value
}

show apply(add, 5)

expected `Fn(int) -> int`, found `Fn(int, int) -> int`

Example: mapping an array

std.array’s mapped applies a macro to every element:

from std.array import Array, mapped

macro double(x: int) -> int {
    @return x * 2
}

macro show_all<const N: int>(values: Array<int, N>) {
    @for v in values {
        @emit v
    }
}

show_all mapped(Array<int, 3> { __el0: 1, __el1: 2, __el2: 3 }, double)

2 4 6

Its declaration reads:

pub macro mapped<T, U, F: Fn(T) -> U>(arr: Array<T, ...>, f: F) -> Array<U, ...>

Limits

• Only a non-generic macro can be passed.
• Fn(...) is the only kind of bound. There are no traits or interfaces.
• A macro is a compile-time value only. It can be passed around and called, but never emitted.

Splicing

Backticks mean “evaluate this now, and put the result here.”

`expression`

There are two uses:

• Building names. r`i` with i = 3 is the name r3. This is the most common use, covered in Spliced names.
• Freezing a value into code that runs later. A declaration generated by a macro is evaluated where it ends up, after the macro’s parameters are gone. A splice evaluates part of it while they still exist. See Generating declarations.

macro declare_scaled(n: int) {
    pub const SCALED`n` = `n * 100`
}

declare_scaled 7

macro show(value: int) {
    @emit value
}

show SCALED7

700

Here the name SCALED`n` becomes SCALED7, and the value `n * 100` becomes 700, both while declare_scaled runs.

Where it makes no difference

In ordinary expressions, which are evaluated anyway, a splice changes nothing: `1 + 2` is the same as 1 + 2.

macro show(value: int) {
    @emit value
}

show `1 + 2`

3

A literal backtick

To write a backtick that isn’t a splice, for example in a custom syntax pattern, escape it: \`.

Spliced names

A name can be built from pieces: r`id` is r followed by the value of id. With id = 3, it’s the name r3.

@for i in 0..4 {
    pub const k`i` = i * i
}

macro show_k(n: int) {
    @emit k`n`
}

show_k 3

9

The top-level @for declares k0 to k3, and k`n` in show_k reads the one named by n.

Where names can be spliced

The pieces can be any number of literal parts and splices, in any order: WORD`bits`_BYTES is WORD16_BYTES when bits is 16. A splice can hold any expression: arr.__el`arr.len - 1 - i`.

Arrays are built this way

std.array’s Array<T, N> has fields __el0, __el1, … up to N - 1, generated with spliced names, and its macros reach them the same way:

from std.array import Array

macro reversed_sum<const N: int>(arr: Array<int, N>) {
    @for i in 0..N {
        @emit arr.__el`N - 1 - i`
    }
}

reversed_sum Array<int, 3> { __el0: 1, __el1: 2, __el2: 3 }

3 2 1

The backtick must touch the name

k`n` is one spliced name. k `n`, with a space, is the name k followed by a separate splice of n.

Reading private constants

A spliced read finds the current file’s non-pub constants as well as pub ones.

A spliced name can’t carry values between iterations

A const declared inside a @for body exists only for that iteration. Spliced names can’t be used to pass a value from one iteration to the next. Use @fold for that.

Modules

Every .basm file is a module. A module sees its own declarations, plus exactly what it imports, and nothing else.

Module names

A module is named by its path, with . in place of / and without the extension:

A leading . makes the path relative to the importing file’s directory. Without it, the path is looked up in the search path.

A first import

shapes.basm:

pub struct Point {
    pub x: int,
    pub y: int,
}

pub macro emit_point(p: Point) {
    @emit p
}

main.basm, in the same directory:

from .shapes import Point, emit_point

emit_point Point(1, 2)

Point { x: 1, y: 2 }

Every module has its own namespace

Two modules can declare the same name without conflict. A name always means what it meant in the file that wrote it: a macro imported from a library keeps using the library’s helpers, even if the importing file declares something with the same name.

Libraries and architecture packages

The standard library, std, is made of ordinary modules. So is every architecture: std.riscv.native is a module that imports std.riscv.impl, and std.x86_64.nasm builds on std.x86_64.intel. There’s no special kind of module for an instruction set.

In this chapter

• Imports: the forms of from ... import, and where modules are found.
• Visibility and re-exports: pub, pub from, and what happens when names collide.

Imports

Syntax

from module import *              # every `pub` name in the module
from module import a, b, c        # only these names
pub from module import ...        # import, and re-export

from std.binary import *
from std.string import validate_ascii, string_from_struct
from .helpers import Pair

Importing names

import * brings in every pub declaration of the module, except pub labels, which must be imported by name (see Labels).

Listing names imports just those:

pub const WIDTH = 8
pub const HEIGHT = 4

from .consts import WIDTH

macro show(value: int) {
    @emit value
}

show WIDTH

8

Importing a name the module doesn’t export, or that isn’t pub, is an error. An import that’s never used gets the unused_import warning.

Importing a directory

If the module path names a directory, the listed names are modules in it: from std.riscv import native means from std.riscv.native import *.

from std.riscv import native

add a0, a1, a2

33 85 c5 00

The search path

A relative path starts with dots. One dot is the importing file’s own directory, and each extra dot goes up one more:

Here lib/double.basm imports from its parent directory:

pub const BASE = 21

from ..numbers import BASE

pub const DOUBLED = BASE * 2

from .lib.double import DOUBLED

macro show(value: int) {
    @emit value
}

show DOUBLED

42

An absolute path (std.binary) is looked up in these directories, in order:

1. The current directory.
2. Each directory in BITTERASM_PATH, which is separated like PATH.
3. ~/.bitterasm, where the installer puts std.

So a project can override a library by putting its own copy earlier in the search path.

Imports aren’t passed on

If a imports b, a file that imports a doesn’t see b’s names. It must import b itself, unless a re-exports them with pub from. See Visibility and re-exports.

Imports only affect names. a’s macros still use b however they’re called, because a name always means what it meant in the file that wrote it.

What an import brings with it

Importing a macro also brings:

• Its overloads. An imported macro’s overloads merge with same-named overloads from other imports and from the importing file. See Overloading.
• Its syntax. A custom syntax assigned to the macro applies in the importing file too.

Visibility and re-exports

pub

A declaration without pub is private to its file. Put pub in front to let other files import it:

pub const WIDTH = 8
pub macro nop() { ... }
pub struct Point { ... }
pub enum Endian { ... }
pub type Reg = bits<5>
pub start:                    # a label

Struct fields have their own pub. See Struct fields.

pub const PUBLIC = 1
const PRIVATE = 2

from .lib import PRIVATE

has no `PRIVATE`

Re-exporting with pub from

pub from ... import imports names and exports them again, as if this file had declared them. That’s how a dialect presents an instruction set plus its own syntax as one module:

• std.riscv.native does pub from .impl import *, and adds conventional syntax.
• std.x86_64.nasm re-exports std.x86_64.intel, which re-exports std.x86_64.impl.

A program then imports just the dialect.

pub const BASE = 100

pub macro show(value: int) {
    @emit value
}

pub from .base import *

pub const EXTRA = 5

from .extended import *

show BASE + EXTRA

105

When names collide

Your own declarations win. A file’s own declaration hides an imported one with the same name. So adding a new pub name to a library can’t break a file that already uses that name.

from .base import show

const BASE = 7

show BASE

7

Two imports of one name are ambiguous, but only if you use it. If two modules both export BASE, and a file imports both with *, using BASE is an error that names both modules:

pub const BASE = 200

from .base import *
from .other import *

show BASE

`BASE` is imported from more than one module

Importing by name picks one. A name imported by name takes precedence over one brought in by *:

from .base import *
from .other import BASE

show BASE

200

Macros are the exception. Same-named macros from different modules don’t collide. Their overloads merge into one set, and each call picks the overload that fits. See Overloading.

Programs

A program’s result is the list of values it emits, in order. Everything in this chapter is about arranging that list:

• Labels name positions in it.
• Sections group it into regions, like code and data.
• Linking combines the lists of several files.
• Executables put a header in front, so the result can run.

A complete program

This is examples/x86_64/hello.basm from the repository, a “Hello, world!” for Linux on x86-64:

from std.x86_64.nasm import *
from std.formats.elf import *

elf64_executable EM_X86_64, _start

const text = "Hello, World!\n"

section .rodata
msg:
    db text

section .text
pub _start:
    mov eax, 1          # sys_write
    mov edi, 1          # stdout
    lea rsi, [rel msg]  # buffer
    mov edx, text.len   # length
    syscall

    mov eax, 60         # sys_exit
    xor edi, edi        # status 0
    syscall

Every piece of it is ordinary BitterASM:

• elf64_executable is a macro from std.formats.elf that emits an ELF header. See Executables.
• section .rodata and section .text put the string and the code in separate sections.
• const text names the string, so db text can emit it and text.len gives its length.
• msg: and _start: are labels. pub exports _start.
• lea, mov, syscall and the rest are macros from std.x86_64.nasm, and db is NASM’s data directive.

Build and run it:

bitter build examples/x86_64/hello.basm -o hello
./hello

Top-level statements run in order

The statements at the top level of a file run from top to bottom. Each call appends whatever it emits. Declarations can appear anywhere, since they’re visible throughout the file.

Labels

A label names a position in the program’s output.

Syntax

name:
pub name:

A label goes on a line of its own. Its name can start with ., which is the convention for a label that’s only used nearby, like a loop. The dot is just part of the name: .loop isn’t scoped to anything, and every label name must be unique in its file.

A label’s value is a position

A label’s value is the index of the next value emitted after it: 0 for the first emitted value, 1 for the second, and so on. It’s an ordinary int:

macro show(value: int) {
    @emit value
}

start:
    show 10
    show 20
middle:
    show start
    show middle
    show end
end:

10 20 0 2 5

A label can be used before it appears in the file, like end above.

From positions to addresses

A position counts emitted values, not bytes. How many bytes each value takes up is only known once an evaluator packs them. So byte distances are left to the evaluator: std.bitter.deferred provides span(a, b), a value that bitter resolves to the number of bytes between positions a and b.

Wrap it in a Positioned<N> to give the result a width. Here a length byte is written before the data it measures:

from std.binary import bits
from std.bitter.deferred import Positioned, span

macro db(value: int) {
    @emit value as bits<8>
}

macro dw(value: int) {
    @emit value as bits<16>
}

macro length_byte(start: int, end: int) {
    @emit Positioned<8> { value: span(start, end) }
}

    length_byte body, done
body:
    db 1
    dw 2
done:

03 01 00 02

here() is the position of the value being emitted. A relative branch encodes span(here(), target), and that’s how every jump and branch in std.riscv and std.x86_64 works. See Packing bytes with bitter.

Labels across files

pub exports a label. Another file imports it by name; import * never brings in labels:

pub double:

from .util import double

macro show(value: int) {
    @emit value
}

show double

<double>

The importing file can’t know where double is: that depends on how the files are laid out when they’re linked. So the value is left unresolved, and bitter build fills it in. See Linking multiple files.

Sections

A section is a named region of the output, such as code or read-only data.

Syntax

section name

Everything emitted after a section statement belongs to that section, until the next section statement. A name can be reopened any number of times.

The name means nothing to the compiler, or to bitter: .text, .rodata and code are all just names.

Sections are grouped

When bitter packs a program, it groups each section’s values together. Sections appear in the order each was first opened, and anything emitted before the first section statement comes before all of them:

from std.binary import bits

macro db(value: int) {
    @emit value as bits<8>
}

    db 1
section .data
    db 0xaa
section .text
    db 2
section .data
    db 0xbb

01 aa bb 02

With several input files, bitter build also joins same-named sections across files. See Linking multiple files.

Sections inside macros

A section statement inside a macro only lasts until the macro returns. The caller’s section is then restored, so calling a macro can’t move the caller’s code by accident:

from std.binary import bits

macro db(value: int) {
    @emit value as bits<8>
}

macro stash(value: int) {
    section .data
    db value
}

section .text
    db 1
    stash 0xaa
    db 2

01 02 aa

A macro whose job is to switch the caller’s section, like a shorthand for section .data, declares the leaks_section facet:

from std.binary import bits

macro db(value: int) {
    @emit value as bits<8>
}

macro data()
    | leaks_section
{
    section .data
}

section .text
    db 1
data
    db 0xaa
section .text
    db 2

01 02 aa

Linking multiple files

A program can be split across files, and bitter build links them into one image:

bitter build main.basm util.basm -o program

What linking does

1. Each input is compiled on its own.
2. Same-named sections are joined across all inputs, in command-line order: every file’s .text, then every file’s .data, and so on.
3. Every pub label that one file imports and another declares is resolved to its final position.
4. The result is packed into bytes, and written marked as executable.

Example

main.basm calls a routine in util.basm:

# main.basm
from std.riscv.native import *
from .util import double

section .text
pub _start:
    addi a0, zero, 21
    jal ra, double

# util.basm
from std.riscv.native import *

section .text
pub double:
    add a0, a0, a0
    jalr zero, ra, 0

bitter build main.basm util.basm -o prog.bin

prog.bin holds four instructions. jal ra, double is encoded as a jump of 4 bytes forward, to where double landed.

Things to know

• The first input goes first. An executable header must be emitted by the first file on the command line, before any section statement.
• Positions inside a file are kept correct. A branch to a label in the same file still lands on it after sections from other files are merged in around it.
• bitter encode doesn’t link. It packs a single .em file, and fails if the file refers to a label in another file.

Positions bitter provides

std.bitter.link declares two labels that bitter resolves against the whole linked image, the way a linker defines symbols like _end:

from std.bitter.link import image_start, image_end

span(image_start, image_end) is the image’s size in bytes, and span(image_start, label) is a label’s offset into the image. That’s what an executable header needs.

Executables

bitter build writes its output marked as executable, but adds nothing to it. An executable file format’s header is BitterASM code that the program writes itself, like any other data.

Adding a header

Call a header macro first thing in the first input file, before any section statement, so the header starts the image:

from std.formats.elf import *

elf64_executable EM_X86_64, _start

The last argument is the entry point, a pub label that can be in any input file.

Optional parameters:

• ELF: load_address, segment_flags (PF_R, PF_W, PF_X), flags.
• PE: image_base.
• Mach-O: vm_address.

Without a header, bitter build writes a flat binary, like nasm -f bin.

What the headers support

Each format maps the whole image as one segment, readable and executable by default. There’s no dynamic linking, no imports and no relocations.

Writing a format of your own

The headers are built from pieces any other format can use:

• std.bitter.link’s image_start and image_end, positions bitter resolves against the linked image. span(image_start, image_end) is the image’s size in bytes. See Linking.
• std.bitter.deferred’s arithmetic: add, sub, band, shr and more, which work on positions that aren’t known until bitter lays the image out.
• std.bitter.layout’s align n, which emits zero bytes up to the next multiple of n.
• std.bitter.layout’s pad_image n, which pads the finished image with zeros to a multiple of n. It takes no space where it’s written, so a header at the start can still pad the end.

Reading std/formats/elf.basm is a good way to see how they fit together.

Evaluators

The compiler, bitterasm, never produces machine code. It runs a program and records the values it emits, in order, in a .em file. An evaluator reads that file and decides what the values mean.

prog.basm ──bitterasm compile──▶ prog.em ──evaluator──▶ output

bitter is the evaluator that ships with BitterASM. It packs values into bytes: binary machine code, or an executable. See Packing bytes with bitter.

Why split it this way

The language never assumes a program’s output is binary. A bits<8> is a struct from the standard library, not a language feature. Only bitter knows that bits<8> means “eight bits.”

So a different evaluator could read the same .em file and produce something else entirely: a hex dump for a teaching tool, a listing, words for a 36-bit machine, trits for a ternary one. The language, and every library that doesn’t depend on bitter, stays the same.

Which types an evaluator knows

In .em, every struct and enum is identified by its module path and name, such as std.binary.bits. An evaluator gives meaning to the ids it knows, and treats everything else however its contract says. bitter knows a handful of ids from std.binary and std.bitter, and packs any other struct as the concatenation of its fields.

In this chapter

• The .em format: the specification an evaluator reads.
• Packing bytes with bitter: how bitter turns values into bytes.

The .em format

bitterasm compile writes a program’s emitted values to a .em file, and an evaluator such as bitter reads it. This is the contract between them; anything that reads .em should follow it.

A .em file is one JSON object:

{
  "version": 1,
  "requires": ["sections", "extern-labels"],
  "module": "spec",
  "exports": { "start": 0 },
  "entries": [
    { "kind": "Struct", "id": "std.binary.bits",
      "args": [{ "kind": "Const", "value": "8" }],
      "fields": [["value", { "kind": "Int", "value": "7" }]],
      "section": ".text" },
    { "kind": "Enum", "id": "spec.Mode", "args": [], "variant": "Slow",
      "payload": { "kind": "Int", "value": "3" }, "section": ".text" },
    { "kind": "Deferred", "module": "spec_dep", "symbol": "far", "section": ".text" }
  ]
}

• version is 1. It changes only when the file’s structure changes incompatibly. A reader must refuse any version it doesn’t know, and must refuse the unversioned plain-list files older compilers wrote.
• requires lists the language features the program actually uses. A reader must refuse a file that requires a feature it doesn’t know, because ignoring one produces wrong output with no error:
  • sections: some entry has a section. Lay entries out grouped by section name, sections in order of first appearance, entries within a section in file order.
  • extern-labels: some value is a Deferred (see below), which only a linker with the other file’s .em can resolve.
• module is the compiled file’s module path: its path relative to the deepest search root containing it, with dots (examples.x86_64.hello). A file under no search root is named relative to the working directory, with one leading . per level up plus one (..shared.util).
• exports maps each top-level pub label to its position: how many entries precede it.
• entries is the emitted values, in emission order. Each is one of these, tagged by kind, plus an optional section:
  • Int: value is a decimal string, since integers are unbounded.
  • Struct: id, generic args, and fields as [name, value] pairs in declaration order.
  • Enum: id, generic args, variant, and an optional payload.
  • Deferred: the value of pub label symbol in the file whose module is given, not known until link time.

A generic argument is {"kind": "Const", "value": "8"} or {"kind": "Type", "type_kind": ..., ...}, where the type is {"type_kind": "Builtin", "name": "int"}, or Struct/Enum with an id and its own args.

Ids. A struct or enum’s id is its declaring module’s path plus its name: std.binary.bits, spec.Mode. Ids are unique within one program, and they’re what an evaluator matches on. Which ids an evaluator gives meaning to is up to that evaluator. bitter understands std.binary.bits, std.bitter.byte_order.LittleEndian, and std.bitter.deferred’s Positioned, Deferred, BinOp and Op, and packs any other struct as the concatenation of its fields.

A later version-1 file may add top-level fields that a reader can safely ignore. Anything a reader must understand to produce correct output is either a new requires feature or a new version.

Packing bytes with bitter

bitter turns each emitted value into bits, and each value’s bits into whole bytes.

bits<N>: a number with a width

std.binary’s bits<N> is the basic unit: an integer that fits in N bits. It packs to exactly N bits.

from std.binary import bits

macro db(value: int) {
    @emit value as bits<8>
}

macro dw(value: int) {
    @emit value as bits<16>
}

db 0x41
dw 0x1234

41 12 34

A bare int has no width, so bitter rejects it. Neither does an enum, which is rejected too.

Structs: fields in order

Any other struct packs as its fields, concatenated in declaration order. The first field goes in the most significant bits:

from std.binary import bits

struct Nibbles {
    hi: bits<4>,
    lo: bits<4>,
}

macro nibbles(hi: int, lo: int) {
    @emit Nibbles(hi as bits<4>, lo as bits<4>)
}

nibbles 0xA, 0xB

ab

That’s the whole instruction-encoding model. An instruction format is a struct whose fields add up to the instruction’s width, and bitter knows nothing about opcodes or registers.

Rounding up to bytes

Each top-level value is padded with zero bits at the top to a whole number of bytes:

from std.binary import bits

macro emit12(value: int) {
    @emit value as bits<12>
}

emit12 0xabc

0a bc

Byte order

With nothing else said, bitter writes the most significant byte first (big-endian). That’s the only order that makes sense for a machine that isn’t byte-addressed at all.

An architecture that wants little-endian output wraps each value in std.bitter.byte_order’s LittleEndian<T, width>, and bitter reverses its bytes. width must match the wrapped value’s width, and be a multiple of 8.

from std.binary import bits
from std.bitter.byte_order import LittleEndian

macro dw_le(value: int) {
    @emit LittleEndian<bits<16>, 16> { value: value as bits<16> }
}

dw_le 0x1234

34 12

std.riscv and std.x86_64 wrap every instruction this way.

Values not known yet: Positioned<N>

Some values depend on where things end up, such as the distance to a branch target. std.bitter.deferred builds such values as a Deferred expression, and Positioned<N> gives one a width:

bitter lays the image out first, then resolves each Positioned<N> and packs it into N bits. See Labels for an example.

Only use here() directly inside the span of the value being emitted. Stored and used by a different value, it silently refers to that other value’s position instead.

Layout: align and pad_image

std.bitter.layout provides two directives that only bitter can resolve, because they depend on the final layout:

• align n emits zero bytes until the next value starts at a multiple of n bytes from the start of the image.
• pad_image n pads the end of the finished image with zeros to a multiple of n bytes, wherever it’s written.

from std.binary import bits
from std.bitter.layout import align

macro db(value: int) {
    @emit value as bits<8>
}

db 1
align 4
db 2

01 00 00 00 02

Both must be emitted as whole values, never as fields inside another struct.

Sections

Before packing, bitter groups values by section. With several input files, bitter build also links them. See Linking multiple files.

Tools

Besides compiling, bitterasm has commands that help while writing code:

Both format and the lint settings read an optional bitterasm.toml, found by searching the file’s directory and then its parents.

An editor language server, bitterasm-lsp, can be installed alongside the compiler. See Installation.

For the full list of commands, see The toolchain.

Formatting

bitterasm format (or fmt) rewrites .basm files in a consistent style:

bitterasm format program.basm     # one file
bitterasm fmt std/                # every .basm file below a directory
bitterasm format --check .        # change nothing; fail if anything would change

--check is meant for CI: it exits with a non-zero status if any file isn’t formatted.

What it changes

• Indentation, following (), [] and {}, plus one level for the lines under a top-level label.
• Facets, each moved to its own indented line.
• Trailing whitespace, runs of blank lines, and the final newline.
• Comments longer than comment_width, which are wrapped. In doc comments, code blocks, tables and headings are left as written.
• Long lines, which are wrapped at commas inside (), [] and {}. A line with no such comma stays long, since a newline would end the statement.

It keeps every comment and never changes what the code means.

Configuration

The formatter reads bitterasm.toml (or .bitterasm.toml), searching the file’s directory and then its parents, like rustfmt. Pass --config path/to/bitterasm.toml to choose one. Every setting is optional:

indent_width = 2
max_width = 90

The same file holds lint settings, under [lints].

Diagnostics and lints

Errors

Every error points at the source that caused it, with a file, line and column, the line itself, and a label:

error: shift amount must be 0 to 31
  --> prog.basm:2:5
  |
2 |     @assert n >= 0 && n < 32, "shift amount must be 0 to 31"
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ error occurs here

--diagnostic-format picks the output: terminal (the default), plain, or json for editors and build tools. --color auto|always|never controls color; auto also respects the NO_COLOR environment variable.

Lints

Warnings are lints. Each has a name, and a level that decides what happens when it fires.

Two groups name several at once: unused (unused_import, unused_parameter and unused_doc_comments) and all.

Levels

Setting levels

On a declaration, with facets named after the level. Give one lint, or several in parentheses:

macro compatibility(value: int)
    | allow unused_parameter
    | deny(unreachable_code, generated_declarations)
{
}

expect documents a lint you know about, and tells you once it’s gone:

macro uses_it(x: int)
    | expect unused_parameter
{
    @emit x
}

uses_it 3

expected `unused_parameter` warning was not produced

(Warnings count as errors in this book’s examples.)

For a project, in bitterasm.toml:

[lints]
unused = "warn"
unreachable_code = "deny"

On the command line, which overrides the project file:

bitterasm compile program.basm -A unused_parameter
bitterasm compile program.basm -D unreachable_code

-A, -W, -D and -F set allow, warn, deny and forbid. They apply left to right, so a later flag overrides an earlier one: -D all -A unused denies every lint except the unused group. A forbidden lint can’t be lowered again, by a later flag or by a facet.

Checking without compiling

bitterasm check runs every check compile does, including lints, but writes no .em file. It takes the same options.

Generating docs

bitterasm doc turns a module’s doc comments into reference pages, and checks the examples in them. The std reference is built by this command, exactly as your own modules would be.

Syntax

bitterasm doc <paths>... [-o <dir>]          # write pages (default: ./doc)
bitterasm doc <paths>... --summary SUMMARY.md # and list them in an mdBook
bitterasm doc <paths>... --test               # compile the examples in doc comments
bitterasm doc <paths>... -o <dir> --check     # fail if <dir> is out of date

Each path is a .basm file or a directory to search.

Where pages go

The pages follow the modules’ folders. The folder every module shares is left off, so documenting myarch writes:

doc/
  index.md          # myarch: what's in it, each with its summary
  util.md           # myarch.util
  x86/
    index.md        # myarch.x86's contents
    native.md       # myarch.x86.native

Each page’s title is the module’s own name, with the path to it underneath: myarch › x86 › native, linking back to each folder. A module with a folder of the same name next to it (x86.basm and x86/) becomes that folder’s index.md, followed by the folder’s contents.

Adding the pages to an mdBook

mdBook only shows pages its SUMMARY.md lists. Put two marker lines under the entry the pages belong to:

- [Reference](reference/index.md)
    <!-- bitterasm doc: begin -->
    <!-- bitterasm doc: end -->

and pass --summary. bitterasm doc replaces whatever is between the markers with the pages, nested by folder and indented like the markers:

bitterasm doc myarch -o book/src/reference --summary book/src/SUMMARY.md

What goes on a page

Almost everything on a page comes from the code. Doc comments only add the prose.

• Macros, one section per name, with a row for each overload: how it’s written, its parameters, and what it returns (-> T) or emits (| emits T).
• Types: structs with their pub fields, enums with their variants, and type aliases.
• Constants and pub labels.

The syntax column shows how a macro is written in that module. Suppose a module declares an instruction and two dialects re-export it:

## Adds two registers.
pub macro add(rd: int, rs1: int, rs2: int) {
    @emit rd + rs1 + rs2
}

pub from .impl import *

pub from .impl import *

syntax add(rd, rs1, rs2) = { $rd$ = $rs1$ + $rs2$ }

The page for native shows add rd, rs1, rs2, and the page for c_like shows rd = rs1 + rs2. Both work:

from .c_like import *

const x = 1
x = 2 + 3

6

A module’s page includes everything it re-exports with pub from. Re-exported macros are listed in full, since a dialect may spell them differently, with a column saying which module declares each overload. Re-exported types and constants read the same everywhere, so they’re listed by name with a link to their own module’s page.

When a name has several overloads, each row shows the first paragraph of that overload’s doc, and any longer doc appears in full below the table.

Testing examples

--test compiles every example in the doc comments of the given modules, following the same rules as this book’s examples (see Writing the docs). A fence with no language is BitterASM, so an instruction’s encoding can be checked right where it’s documented:

## Returns from the current function.
##
## ```
## from myarch.native import *
##
## ret
## ```
##
## ```bytes
## c3
## ```
pub macro ret() | emits Byte { ... }

Examples are compiled from the current directory, so they import your modules the way a program would. Checking bytes needs bitter, found next to bitterasm or on PATH. A failure names the example’s line:

error: myarch/native.basm:12: expected the bytes c3, but got c2

Keeping pages up to date

--check writes nothing, and fails if any page in the output directory differs from what bitterasm doc would write, or belongs to a module that no longer exists. With --summary, it also fails if the list in SUMMARY.md is out of date. Run it in CI next to --test:

bitterasm doc myarch --test
bitterasm doc myarch -o book/src/reference --summary book/src/SUMMARY.md --check

Writing never deletes anything: a page left over from a module that’s gone is pointed out, for you to delete.

To make sure everything public is documented, turn on the missing_docs lint, which is allowed by default. It reports each pub item without a ## comment, and a file without a #! block. A macro counts as documented when any of its overloads in that file is.

bitterasm check myarch/native.basm -W missing_docs

The standard library

std is written entirely in BitterASM. Nothing in it is built into the compiler: bits, strings and whole instruction sets are ordinary modules you could have written yourself, and can read in the repository’s std/ directory.

Core

For bitter

These define the types the bitter evaluator understands. See Packing bytes with bitter.

Executable formats

See Executables.

Architectures

Each architecture has an impl module with its registers, instruction formats and instructions, plus one or more dialects that give the instructions a syntax. Import a dialect. See Custom syntax.

from std.riscv.c_like import *

a0 = a1 + a2

33 85 c5 00

The same add instruction as in Your first program, through the C-like dialect.

Reference

The std reference lists every public declaration of every module, generated from std’s doc comments by bitterasm doc. See Generating docs to do the same for your own modules.

std

array

std › array

Array<T, N>: N values of type T, and ways to build new arrays from old ones. Every value is immutable, so each operation returns a new array.

from std.array import *

macro show_all<const N: int>(values: Array<int, N>) {
    @for v in values {
        @emit v
    }
}

macro double(x: int) -> int {
    @return x * 2
}

const values = Array<int, 3> { __el0: 10, __el1: 20, __el2: 30 }

show_all reversed(values)
show_all mapped(appended(values, 40), double)

30 20 10
20 40 60 80

An array is built with its elements named __el0, __el1, …, or by an @for inside the construction. @for v in values visits the elements in order.

Macros

get

The element at index, counting from 0. An index outside the array is a compile error.

updated

A copy of arr with the element at index replaced by value.

reversed

A copy of arr in reverse order.

popped

A copy of arr without its last element. arr can’t be empty.

first

The first element. arr can’t be empty.

last

The last element. arr can’t be empty.

mapped

A new array holding f of each element, in order. f is any macro that takes a T and returns a U.

array_from_struct

An Array<int, N> of a struct’s __el0..__el{len - 1} fields, such as a String’s characters or a Range’s values.

enumerate

Each element paired with its index, as an Enumerated<T>.

appended

A copy of arr with value added at the end.

Types

Array

struct Array<T, const N: int>

N values of type T, in order.

Some of its fields are generated by @for or @if.

binary

std › binary

Fixed-width binary values: bits<N>, signed<N>, bool, and byte order.

bits<N> is how std gives an int a width. Its value must fit in N bits, which is checked when the value is built, so an encoder can’t silently emit a field that overflows.

from std.binary import *

macro show<T>(value: T) {
    @emit value
}

show bits<8> { value: 65 }
show bit_width(255)

bits<8> { value: 65 }
8

Macros

signed_from_int

x as a signed<width>. It must fit: from -2^(width - 1) up to 2^(width - 1) - 1.

signed_to_int

The int a signed<width> holds, sign-extended from its top bit.

fits_inside_width

1 if value fits in width bits (0 <= value < 2^width), else 0.

bit_width

The number of bits needed to write n, which must not be negative. Zero still takes one bit.

from std.binary import bit_width

macro show(value: int) {
    @emit value
}

show bit_width(0)
show bit_width(255)
show bit_width(256)

1 8 9

byte_width

The number of whole bytes needed to write n, which must not be negative: byte_width(255) is 1 and byte_width(256) is 2.

Types

bits

struct bits<const width: int>

An unsigned value width bits wide: 0 <= value < 2^width.

from std.binary import *

const too_big = bits<4> { value: 16 }

invariant `fits_inside_width(width, value)` was violated for `bits`

signed

struct signed<const width: int>

A signed value width bits wide, stored in two’s complement: -2^(width - 1) <= value < 2^(width - 1). Convert an int to one with as, and back the same way.

from std.binary import *

macro db(value: signed<8>) {
    @emit value
}

db (-1) as signed<8>
db 100 as signed<8>

ff 64

from std.binary import *

const too_small = (-129) as signed<8>

value doesn't fit in the signed width

bool

type bool = bits<1>

A single bit: true or false.

Endian

enum Endian

Byte order, for code that can lay out values either way.

Constants

bitfield

std › bitfield

Bit ranges, written the way ISA manuals write them. slice(x, 10, 5) is the manual’s x[10:5]: hi and lo are inclusive bit numbers, so a one-bit field is (n, n). The shift, the mask and the result’s width all come from those two numbers, so they can’t disagree.

from std.bitfield import *

macro show(value: int) {
    @emit value
}

show slice(0b1101_0110, 7, 4)
show place(3, 7, 6) | place(2, 5, 3) | place(1, 2, 0)

13 209

slice and field also take a Deferred value, such as a branch offset bitter works out later, and give back a Deferred or Positioned<N>.

Macros

mask

width one-bits: mask(5) is 0b11111.

bit

Bit n of value, as 0 or 1.

slice

field

truncate

The low width bits of value, as a bits<width>. It truncates rather than rejecting, so a negative immediate becomes its two’s-complement encoding: truncate(-1, 12) is 0xFFF, where bits<12> { value: -1 } would fail bits’s range check.

place

value’s low hi - lo + 1 bits, moved up to bits hi down to lo: slice’s inverse, for building a word out of fields with |. place(mod, 7, 6) | place(reg, 5, 3) | place(rm, 2, 0) is a ModRM byte.

bitter

std › bitter

byte_order

std › bitter › byte_order

Byte order for bitter. Its default is most significant byte first; LittleEndian asks for the reverse.

from std.binary import bits
from std.bitter.byte_order import LittleEndian

macro dw_le(value: int) {
    @emit LittleEndian<bits<16>, 16> { value: value as bits<16> }
}

dw_le 0x1234

34 12

Types

LittleEndian

struct LittleEndian<T, const width: int>

value, packed with its least significant byte first. width is value’s width in bits, and must be a multiple of 8.

deferred

std › bitter › deferred

Values that depend on where things end up, such as the distance to a branch target. They’re built as Deferred expressions that bitter resolves once the image is laid out, and given a width by Positioned<N>.

from std.binary import bits
from std.bitter.deferred import *

macro db(value: int) {
    @emit value as bits<8>
}

macro offset_to(target: int) {
    @emit Positioned<8> { value: span(here(), target) }
}

offset_to end
db 0xAA
db 0xBB
end:

03 aa bb

add, sub, mul, shr and band work on ints, giving an int, and on Deferreds, giving a Deferred, so an encoder is written the same way whether its operand is known yet or not.

Macros

here

The position of the value being packed. Use it only inside the span of the value being emitted: stored and used by a different value, it refers to that value’s position instead.

add

sub

mul

shr

band

span

Types

Op

enum Op

The operation of a BinOp.

BinOp

struct BinOp

An operation on two Deferred values.

Deferred

enum Deferred

A value bitter works out after laying out the image. Build one with here, span and the arithmetic macros rather than by hand.

Positioned

struct Positioned<const width: int>

A Deferred value, packed into width bits once bitter resolves it: what bits<N> is to an int. A negative value is packed in two’s complement.

layout

std › bitter › layout

Padding that depends on the final layout, which only bitter knows: align and pad_image. Emit them as whole values, never as fields inside another struct.

from std.binary import bits
from std.bitter.layout import align

macro db(value: int) {
    @emit value as bits<8>
}

db 1
align 4
db 2

01 00 00 00 02

Macros

align

Pads with zeros so the next value starts at a multiple of n bytes from the start of the image.

pad_image

Pads the finished image with zeros to a multiple of n bytes, wherever it’s written, for formats whose size must be rounded up (PE rounds its sections to 512 bytes). It takes no space where it appears, so span and std.bitter.link’s image_end measure the image without the padding.

Types

Align

struct Align<const n: int>

Zero bytes up to the next multiple of n bytes from the start of the image. align emits one. A span across it counts the padding.

PadImage

struct PadImage<const n: int>

Zero bytes at the end of the image, up to a multiple of n bytes. pad_image emits one.

link

std › bitter › link

Positions bitter defines when it links a program, the way a linker defines _end. span(image_start, image_end) is the image’s size in bytes, and span(image_start, label) is label’s offset into it, however many files the program spans: what an executable header needs.

from std.bitter.deferred import *
from std.bitter.link import image_start, image_end

macro size_byte() {
    @emit Positioned<8> { value: span(image_start, image_end) }
}

size_byte
size_byte

02 02

Labels

ctypes

std › ctypes

C’s fixed-width integer names. The signed ones are signed<N>, stored in two’s complement; the unsigned ones are bits<N> that can’t be negative.

from std.ctypes import *

macro db(value: int8_t) {
    @emit value
}

macro dw(value: uint16_t) {
    @emit value
}

db (-2) as int8_t
dw 0x1234 as uint16_t
db (((-2) as int8_t) as int + 5) as int8_t

fe 12 34 03

Types

int8_t

type int8_t = signed<8>

An 8-bit signed value, -128 to 127.

uint8_t

type uint8_t = bits<8>

An 8-bit unsigned value, 0 to 255.

int16_t

type int16_t = signed<16>

A 16-bit signed value.

uint16_t

type uint16_t = bits<16>

A 16-bit unsigned value.

int32_t

type int32_t = signed<32>

A 32-bit signed value.

uint32_t

type uint32_t = bits<32>

A 32-bit unsigned value.

int64_t

type int64_t = signed<64>

A 64-bit signed value.

uint64_t

type uint64_t = bits<64>

A 64-bit unsigned value.

decimal

std › decimal

Exact non-integer numbers, for compile-time math: Decimal, a value scaled by a power of ten, and Fraction, a numerator over a denominator. Both convert to and from int with as.

from std.decimal import *

macro show(value: int) {
    @emit value
}

const half = Fraction(n = 1, d = 2)
const d = fraction_to_decimal(half, 3)
show d.value
show d.scale
show Decimal(value = 42, scale = 0) as int

500 3 42

Macros

decimal_to_int

x as an int. x.scale must be 0.

decimal_from_int

x as a Decimal with scale 0.

fraction_to_int

x as an int. x.d must be 1.

fraction_from_int

x over 1.

decimal_to_fraction

x as x.value over 10^x.scale, not reduced.

fraction_to_decimal

x as a Decimal with precision decimal places, rounded toward zero.

Types

Infinity

enum Infinity

A signed infinity.

Decimal

struct Decimal

value / 10^scale: Decimal(value = 314, scale = 2) is 3.14. scale can’t be negative. as int works when scale is 0.

Fraction

struct Fraction

n / d, where d isn’t 0. as int works when d is 1, and as Decimal keeps 10 decimal places.

enumerated

std › enumerated

Enumerated<T>: a value paired with its position.

Types

Enumerated

struct Enumerated<T>

A value and its index, as enumerate in std.array produces.

formats

std › formats

elf

std › formats › elf

ELF static executables, for Linux and the BSDs.

Invoke one header macro first thing in the program’s entry file, before any section statement, so its bytes start the image. This one is a complete Linux x86-64 program that exits with status 0:

from std.formats.elf import *
from std.x86_64.nasm import *

elf64_executable EM_X86_64, _start

_start:
    mov eax, 60     # exit
    xor edi, edi    # with status 0
    syscall

The header maps the whole image as one segment at load_address and starts execution at entry, a label in this file or imported from another one. Its sizes and entry point come from span over the linked image (std.bitter.link), so they stay correct however the program’s sections and files are laid out.

What this doesn’t produce: section headers, dynamic linking, or separate segments per section. The single segment is readable and executable by default; pass segment_flags (a combination of PF_R, PF_W, PF_X) to change that. Every multi-byte field is little-endian, as x86-64 and RISC-V are.

Macros

elf64_executable

A 64-bit ELF header and its one program header, 120 bytes. machine is EM_X86_64 or EM_RISCV, entry is the label execution starts at, and flags is the header’s e_flags, which some architectures give meaning.

elf32_executable

A 32-bit ELF header and its one program header, 84 bytes, e.g. for RV32. The parameters mean what they do for elf64_executable.

Constants

macho

std › formats › macho

Mach-O 64 executables, for macOS.

Invoke the header macro first thing in the program’s entry file, before any section statement, so its bytes start the image:

from std.formats.macho import *
from std.x86_64.nasm import *

macho64_executable CPU_TYPE_X86_64, CPU_SUBTYPE_X86_64_ALL, _start

_start:
    ret

The whole image is one __TEXT segment at vm_address, readable and executable, and entry (a label in this file or imported from another one) is where execution starts. A modern macOS kernel refuses an executable without a dynamic linker even if it never calls a shared library, so the header names /usr/lib/dyld; current macOS may still refuse an unsigned binary depending on Gatekeeper policy.

Not verified on macOS: this reproduces the Rust writer it replaced byte for byte, and llvm-readobj accepts its output.

Macros

macho64_executable

The Mach-O header and its three load commands (the __TEXT segment, the dynamic linker and the entry point), 160 bytes. entry is the label execution starts at, and the segment loads at vm_address.

Constants

pe

std › formats › pe

PE32+ (64-bit Windows) console executables.

Invoke the header macro first thing in the program’s entry file, before any section statement, so its bytes start the image:

from std.formats.pe import *
from std.x86_64.nasm import *

pe64_executable IMAGE_FILE_MACHINE_AMD64, _start

_start:
    ret

The image is the headers (padded to 512 bytes), then everything after them as one read+execute .text section at RVA 0x1000, padded to 512 bytes at the end. entry is a label in this file or imported from another one. No imports, exports or relocations: a program that calls into Windows DLLs needs more than this provides.

Not verified on Windows: this reproduces the Rust writer it replaced byte for byte, and llvm-readobj accepts its output.

Macros

pe64_executable

The DOS, PE and optional headers plus the .text section header, 368 bytes, padded to 512. entry is the label execution starts at, and the image loads at image_base.

Constants

iter

std › iter

Stepped ranges of integers, for @for.

from std.iter import range

macro countdown() {
    @for i in range(10, 0, -3) {
        @emit i
    }
}

countdown

10 7 4 1

Macros

range

A Range from start to stop, not including stop, every step.

Types

Range

struct Range<const start: int, const stop: int, const step: int>

The integers from start up to (or down to) stop, not including it, every step. range builds one. step can’t be 0, and has to point from start towards stop.

Some of its fields are generated by @for or @if.

math

std › math

Integer math, and fixed-point math on Decimal and Fraction, all evaluated at compile time.

from std.math import *

macro show(value: int) {
    @emit value
}

macro demo() {
    show gcd(12, 18)
    show div_floor(-7, 2)
    show sqrt(2, 4).value
    show sin(PI(10), 6).value
}

demo

6 -4 14142 0

Functions that give a Decimal take a precision: the number of decimal places to keep, DEFAULT_PRECISION unless given. Results are truncated to that many places, so sqrt(2, 4) is 1.4142. Angles are in radians.

Re-exports std.decimal.

Macros

abs

min

The smaller of a and b.

max

The larger of a and b.

sign

copysign

abs(x) with the sign of y: abs(x) * sign(y), so 0 when y is 0.

clamp

x, moved into lo..=hi if it’s outside. lo can’t be more than hi.

pow

gcd

The greatest common divisor of a and b, never negative. gcd(0, 0) is 0.

lcm

The least common multiple of a and b, never negative.

div_floor

a / b rounded down: div_floor(-7, 2) is -4, where / gives -3.

div_ceil

a / b rounded up: div_ceil(7, 2) is 4.

rem_euclid

The remainder of a / b that’s never negative: rem_euclid(-7, 3) is 2, where % gives -1.

div_euclid

The quotient that goes with rem_euclid, so div_euclid(a, b) * b + rem_euclid(a, b) == a.

pow_mod

base^exponent % modulus, without computing base^exponent in full. exponent can’t be negative, and modulus must be positive.

isqrt

The square root of x, rounded down. x can’t be negative.

popcount

How many bits of x are 1. x can’t be negative.

ctz

How many 0 bits come below x’s lowest 1 bit. ctz(0) is 0.

clz

How many 0 bits come above x’s highest 1 bit, in a width-bit value. x must fit in width bits.

rotate_left

x rotated left by amount bits within a width-bit value: bits shifted out at the top come back in at the bottom.

rotate_right

x rotated right by amount bits within a width-bit value: bits shifted out at the bottom come back in at the top.

is_pow_of_two

1 if x is a power of two, else 0. 0 isn’t one.

next_pow_of_two

The smallest power of two that’s at least x: next_pow_of_two(5) is 8, and next_pow_of_two(0) is 1.

floor

ceil

trunc

round

fract

PI

π to precision decimal places, at most 60.

TAU

τ = 2π to precision decimal places, at most 60.

E

e to precision decimal places, at most 60.

SQRT2

√2 to precision decimal places, at most 60.

LN2

ln 2 to precision decimal places, at most 60.

LN10

ln 10 to precision decimal places, at most 60.

root

sqrt

hypot