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

The IR backend (default) uses a pool of 18 physical registers (MIPS regs 8–25: $t0–$t9 and $s0–$s7) for virtual register allocation. The legacy bridge path (--bridge) uses 14 registers. Allocation is done by the RegAlloc struct — if the pool is exhausted, the variable is spilled to a stack slot and loaded/stored as needed.

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 — three levels (highest to lowest):
High: *, /, <<, >> (handled in parse_factor)
Medium: +, -, &, |, ^ (handled in parse_term)
Low: ==, !=, >, <, >=, <= (handled in parse_expression)
Use parentheses liberally to make intent explicit — 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.

4.7 call() — Function Pointers

The call(expr) statement jumps to a runtime address stored in a variable or computed from an expression. Unlike a regular function call which uses an absolute jal, call() emits a jalr instruction — it loads the target address at runtime from whatever expression is given.

Syntax

Basic Usage — Stored Address

MIPS Instructions Generated

Encoding of jalr $ra, $tX

Dynamic Dispatch — Computed Address

The expression inside call() can be any valid BedRock expression — not just a simple variable. The compiler evaluates the full expression and jumps to the resulting address.

Comparison: call() vs Named Call

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

BedRock has three precedence levels. High: *, /, <<, >>. Medium: +, -, &, |, ^. Low: ==, !=, >, <, >=, <=. Bitwise operators like & bind before comparisons, but after shifts — still use parentheses to make intent explicit.

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 Register Pool Exhaustion (Legacy Bridge Path Only)

In the legacy bridge path (--bridge), the register pool contains 14 registers. If exhausted, alloc_reg() silently returns register 8 ($t0), corrupting a live value without any warning. The default IR pipeline spills to stack instead — no silent corruption.

8.10 Shift Operators (<< / >>)

BedRock includes native shift operators in the lexer and codegen. Both logical left-shift (<<) and logical right-shift (>>) are first-class operators and compile to the corresponding MIPS sllv / srlv instructions.

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.

9.1 Defining a Struct

Use the struct keyword followed by the type name and a list of fields. Each field has a name and a type.

9.2 Instantiating a Struct

Use the StructInstance statement to bind a variable name to a struct type. The compiler allocates one virtual register per field, named varname__fieldname.

9.3 Field Access

Fields are accessed with dot notation. A read generates a get IR op (→ lw), a write generates a mov IR op (→ sw).

9.4 Struct Internals (Compiler View)

Structs are a purely compile-time construct. The IrBuilder reads Statement::StructDefine to build an internal layout table mapping each field name to a byte offset. When a StructInstance is lowered, it emits one Const IR op per field, creating named virtual registers like p__x, p__y.

10.1 Defining an Interrupt Handler

Use the int keyword to define an interrupt service routine (ISR). The body executes in interrupt context and should return as quickly as possible. The compiler automatically appends an ERET (exception return) at the end.

10.2 Enabling Interrupts — int_enable

The int_enable(vector, handler) statement installs an ISR at a specific interrupt vector. The first argument must be a compile-time constant — the vector number. The second is the handler label defined with int.

10.3 Disabling Interrupts — int_disable

The int_disable statement (no arguments) globally disables all hardware interrupts by clearing the IE bit in the MIPS Status coprocessor register.

10.4 Complete Example

10.5 IR Lowering

The three interrupt keywords lower to the following IR operations:

11.1 Optimizer Levels

11.2 Pass 1 — Pruner (Constant Folding & DCE)

The Pruner performs two transformations in sequence:

• Constant Folding: If both operands of a binary expression are compile-time constants, the compiler evaluates the expression at compile time and replaces it with a literal. All operators are supported: arithmetic, bitwise, shifts, and comparisons.
• Dead Code Elimination (DCE): Variables and arrays that are declared but never read (no use in any expression) are removed from the output. Function names and assignments to live variables are always preserved.

11.3 Pass 2 — Transformer (LICM & Strength Reduction)

The Transformer applies two analyses to every function and loop body:

• Loop-Invariant Code Motion (LICM): Statements whose right-hand-side operands are never modified inside a loop body are hoisted out to before the loop. This eliminates redundant recomputation on every iteration.
• Strength Reduction: Multiplications and divisions by powers of two are replaced with shift instructions (*2ⁿ → << n, /2ⁿ → >> n, %2ⁿ → & (2ⁿ-1)), which are faster and smaller on MIPS.

11.4 Pass 3 — Quantum (Register Allocation & Scheduling)

The Quantum pass implements a linear-scan register allocator and an instruction scheduler. It models 18 available machine registers.

• Live interval computation: Scans the entire program to determine the first-definition (start) and last-use (end) of every variable.
• Linear-scan allocation: Assigns physical registers to variables in order of their start time. When all 18 registers are busy, the variable with the longest remaining live range is spilled.
• Pipeline scheduling: Reorders statements within a block, placing independent operations (non-spilled variables) before spill-dependent ones to hide memory latency.

12.1 Pipeline Overview

12.2 IR Opcodes

The BedRock IR uses a simple three-address code format. Every instruction has an opcode and 0–3 operands.

12.3 Targets & CLI Flags

12.4 Source Map

After compilation, the MIPS backend writes a .map.json file alongside the binary. Each entry records the BedRock source line, the output binary address, the raw 32-bit instruction word, and a human-readable description.

This source map is consumed by the VS Code debugger extension for live MIPS breakpoints correlated to BedRock source lines.