1.1 "No Magic"

In BedRock, every operation maps to a known, fixed sequence of machine instructions. There are no hidden runtime allocations, no garbage collector, no implicit type coercions, and no virtual dispatch. What you write is exactly what executes.

This is enforced by design — the table below shows the exact 1-to-1 mapping for common constructs:

1.2 "Byte-Level Validation"

Numbers in BedRock are unsigned 64-bit integers at parse time, collapsed to 32-bit at code generation. All memory addresses are 32-bit values. There are no floating-point types, no signed arithmetic in the type system, and no implicit widening or truncation.

The compiler validates output at the byte level by:

• Encoding all instructions as big-endian 32-bit words via to_be_bytes()
• Writing a raw .bin file with zero padding assumptions
• Optionally writing a 1.44 MB floppy image (bedrock_os.img) by embedding the binary at sector 0

1.3 "Direct Hardware Control"

BedRock provides five mechanisms for hardware access that map directly to bare-metal MIPS operations. There is no operating system abstraction layer.

2.1 Keywords

The following identifiers are reserved and cannot be used as variable or function names.

2.2 Operators

Arithmetic Operators

Bitwise Operators

Comparison Operators

Assignment

2.3 Literals

Integer Literals

BedRock supports decimal and hexadecimal integer literals. All integers are stored as u64 during lexing.

String Literals

Strings are delimited by double quotes, stored in the DATA segment as null-terminated byte arrays (C-style). Escape sequences are not processed — see §8.8.

Array Literals

Arrays are comma-separated lists of integer literals only enclosed in [ ]. Variables and expressions are not permitted as elements — see §8.2.

2.4 Comments & Include Directive

The include directive is a preprocessor feature handled before lexing. It performs textual substitution of the named file's content into the current file. Include paths are resolved relative to the source file's directory and processed recursively.

3.1 Address Space

BedRock uses a flat 32-bit address space. The layout is determined by three root declarations:

3.2 Segment Layout

3.3 let — Static Variable

let declares a static variable. In global scope, the compiler allocates a fixed address in the DATA segment and emits sw (store word) instructions to initialize it. Variables do not occupy stack space in global scope.

3.4 root — Hardware / Environment Constant

root declares a compile-time constant mapping a name to a fixed 32-bit address or value. Unlike let, a root symbol is never dereferenced. When used in an expression, it evaluates to the raw address value itself — not the value stored at that address.

3.5 Stack Frame Structure

Every function call creates a 32-byte stack frame:

Prologue (emitted automatically)

Epilogue (emitted automatically)

3.6 Register Allocation

BedRock uses a pool of 8 temporary registers ($t0–$t7, MIPS registers 8–15) for all expression evaluation. Registers are allocated from the front of the pool and freed back to the rear (FIFO with free-list).

4.1 Variable Declarations

4.2 Arrays & Strings

Array Definition & Access

Arrays are statically allocated in the DATA segment. Only integer literals are permitted as element values. The compiler scales all indices by 4 (sll idx, idx, 2) — each element is a 32-bit word.

String Definition

Strings are stored as null-terminated byte arrays in the DATA segment, padded to the next 4-byte boundary.

4.3 Arithmetic & Expressions

Precedence rules: * and / bind tightly (handled in parse_term). All other operators — +, -, ==, !=, >, <, &, |, ^ — share the same lower precedence level (parse_expression). Use parentheses liberally — see §8.6.

4.4 Function Definitions

4.5 Control Flow

if / else

while

loop / break

An infinite loop. Exits only via break or a return from the enclosing function.

4.6 Inline Assembly

Emits a single 32-bit MIPS instruction directly into the code stream. The argument must be the exact 32-bit encoding as a hex string — without the 0x prefix.

5.1 Compiler Pipeline

The compiler operates in a single pass with eight sequential phases:

5.2 Load Immediate (emit_li)

All constant loading uses the following pattern based on the value's bit width:

5.3 Binary Operation Code Generation

All binary operations follow the pattern: allocate regs → gen left → gen right → emit instruction → free regs.

Arithmetic Encodings

Comparison Encodings

5.4 Control Flow Code Generation

if Statement

while Loop

loop (Infinite)

Function Call (jal)

5.5 Memory Operations

5.6 Binary Output Format

The compiler emits a flat binary of 32-bit big-endian MIPS instructions:

6.1 Direct Memory Writes — poke

poke writes a 32-bit value to an absolute physical address. No bounds checking occurs.

Machine Code Generated

6.2 Direct Memory Reads — peek

peek reads a 32-bit value from an absolute physical address and returns it as an expression value (in $v0 / the allocated register).

6.3 I/O Port Access — outb / inb

BedRock implements I/O as MMIO. outb and inb are functionally identical to poke and peek at the machine code level — both emit sw and lw instructions respectively. The distinction is semantic only, signaling programmer intent.

6.4 VGA Text Mode — Practical Reference

VGA text mode buffer begins at physical address 0xB8000. Each character cell is 2 bytes.

Color Constants (Foreground)

Cell Address Formula

Example — Print 'H' in White on Black at (0,0)

Example — Clear Entire Screen

6.5 Keyboard Input — in

The keyword in (used as an expression) reads from the keyboard input address 0x80020000 (hardcoded in the compiler). Use inb with an explicit port address to override.

6.6 Raw Instruction Injection — asm

Use asm for instructions not expressible in BedRock's grammar. Always document the encoding.

7.1 The Address Library Pattern

Declare all hardware addresses as root constants in a dedicated include file. This creates a zero-cost hardware abstraction layer and eliminates magic numbers from your code.

❌ Without Address Library (Avoid)

✅ With Address Library (Preferred)

7.2 Write Pure Functions

Functions that only operate on their parameters and local variables are predictable, testable, and cacheable. Avoid functions that modify hardware state without naming what they target.

7.3 Use Loops for Bulk Hardware Operations

7.4 Always Set BASE, DATA, STACK Explicitly

7.5 Use asm Sparingly and Document It

Inline assembly breaks the readability contract of BedRock. When you must use it, always document the instruction's human-readable name and effect.

8.1 root Requires Literal Number Values

The right-hand side of a root declaration must be a literal integer. Expressions are not evaluated.

8.2 Array Literals Allow Only Integer Literals

Array literal values must be compile-time integer constants. Variables and expressions are not permitted — the parser will panic.

8.3 Unresolved Variable Panics at Codegen

Referencing an undeclared variable causes a panic! in the codegen phase. There is no graceful error recovery — the compiler process terminates.

8.4 Function Call Arguments Are Positional Only

BedRock has no named parameters at call sites. Arguments are matched by position. The number of arguments passed is not validated by the parser.

8.5 Return Value Is Always $v0

There is only one return register ($v0 = register 2). Multiple return values are not supported. Calling two functions in a complex expression may overwrite $v0 before it is consumed.

8.6 No Operator Precedence for Bitwise / Comparison

All of +, -, ==, !=, >, <, &, |, ^ share the same precedence level. Only * and / bind more tightly.

8.7 ! Without = Is a Lexer Error

The lexer only recognizes !=. A lone ! produces Token::EOF and terminates lexing silently — not an error message.

8.8 String Literals Do Not Support Escape Sequences

The lexer reads string content character-by-character until the closing ". Backslash sequences are stored literally as two characters.

8.9 Maximum 8 Concurrent Temporary Registers

The register pool contains 8 registers ($t0–$t7). If the pool is exhausted, alloc_reg() silently returns register 8 ($t0), corrupting a live value without any warning.

8.10 No Shift Operators (<< / >>)

These operators are absent from the lexer and parser. Use asm for all bit-shift operations.

8.11 Integer Overflow Is Silent

All arithmetic uses unsigned MIPS addu/subu. Overflow wraps silently at 2³² − 1. There are no overflow traps or checks at compile time or runtime.

8.12 Division by Zero Is Undefined

BedRock emits a raw MIPS div instruction. On MIPS, division by zero produces an unpredictable value in LO and does not raise an exception unless the hardware is explicitly configured to do so. There is no compile-time or runtime guard.