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/le-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/le-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.

13.1 Overview & Target Flag

The RISC-V backend consumes the same IrModule as the MIPS IR-native backend. It sits at the same point in the pipeline, downstream of the optimizer and IrBuilder. No BedRock source changes are required to retarget a program; only the --target flag changes.

Root Symbol Handling

Address-space layout works the same way as §3. root BASE, root DATA, and root STACK configure the code start address, static data segment, and initial stack pointer. The default BASE is 0x80000000, matching the generic RISC-V virt-machine convention used by QEMU and many bare-metal RV32 boards. It's the same numeric default as the MIPS backend, for a different reason.

13.2 Register Mapping

The backend defines a fixed set of role registers. Each one is chosen as a direct analogue of a MIPS role register from the MIPS backend, so the two backends stay easy to compare.

Allocatable Pool (Virtual Register Allocation)

19 physical registers are available to the linear allocator for user variables, one more than the 18 the MIPS IR-native backend uses. RISC-V's role registers leave a slightly larger free set: s0, s1, a1–a7, s2–s11 (x8, x9, x11–x17, x18–x27). tp (x4) is reserved and never allocated. If the pool is exhausted, the variable is spilled to a stack slot at sp + offset, with the same spill semantics as §3.6. The immediate on lw/sw is a 12-bit signed value (±2048 bytes) rather than MIPS's 16-bit range, so a program with heavy spilling has a smaller spill window on RISC-V.

13.3 Instruction Encoding

RISC-V uses six base instruction formats. The backend implements each as a dedicated encoder function operating on raw field values.

Every instruction word this backend produces has been checked against a real disassembler (objdump -m riscv:rv32), so the mnemonics in this section reflect what actually gets emitted.

13.4 Load Immediate

RISC-V has no single instruction that loads an arbitrary 32-bit constant. The backend uses the standard LUI + ADDI pattern, with rounding to compensate for ADDI's sign-extended 12-bit immediate.

13.5 Arithmetic & Logic Operations

Bitwise NOT

RV32I has no dedicated NOR/NOT instruction. The backend synthesizes it as XORI rd, rs, -1. XOR-ing with an all-ones mask flips every bit, since the 12-bit immediate -1 sign-extends to 0xFFFFFFFF at execution time.

Shift Semantics

Both the immediate (SLLI/SRLI) and register (SLL/SRL) shift forms are the logical variants. Shifting right always fills with zero, never the sign bit. This matches the MIPS backend's use of srlv (not srav) for >>, so shift behavior stays identical across both targets.

13.6 Comparisons & Branches

MIPS has no direct "branch if less than" instruction, so it has to synthesize comparisons with slt before branching on the result. RISC-V's base ISA includes signed comparison branches natively, and the backend uses them directly, with no intermediate compare-then-branch step.

Comparisons use the signed branch forms, BLT/BGE, not BLTU/BGEU. This matches the MIPS backend's use of signed slt for the same operators.

Unconditional Jump

loop/Go lowers to JAL x0, label, a jump that discards the link address by writing it to x0 (hardwired to zero, so the write is dropped). This is the standard RISC-V idiom for an unconditional jump, equivalent to the pseudo-instruction j label.

Branch/Jump Target Resolution

Forward references, a branch to a label not yet emitted, are resolved with a two-pass patch mechanism. A placeholder word is emitted at the branch site, and once every label's final address is known, the backend re-encodes that site with the correct signed byte offset using the same B-type/J-type encoders. RISC-V branch and jump offsets are PC-relative, so the numeric value of root BASE cancels out of every intra-program offset. Only absolute loads, like the stack pointer or a hardware address, are affected by BASE's actual value.

13.7 Function Calls & Returns

Call

A named function call saves the caller's return address into a scratch register before the call and restores it right after, so the caller's own ra survives nested calls without a dedicated stack save.

Return

If the function returns a value, it's moved into a0 (skipped if already there). The function then returns via jalr x0, ra, 0, the standard RISC-V ret pseudo-instruction.

call(): Function Pointers

The §4.7 call(expr) mechanism lowers the same way as a named call, except the target address is loaded from the evaluated expression into a register at runtime instead of being a compile-time label. The underlying jump still uses jalr, RISC-V's indirect-jump instruction. This is the direct structural equivalent of the MIPS jalr $ra, $tX form documented in §4.7.

13.8 Memory Operations

As with the MIPS backend, outb/inb are the same instructions as poke/peek. The distinction is only there to signal programmer intent about memory-mapped I/O versus general memory.

13.9 Interrupts (CSR-Based)

The RISC-V backend implements the §10 interrupt keywords using RISC-V's native control-and-status-register (CSR) mechanism, instead of the CP0-style register manipulation the MIPS backend uses.

int_enable: Handler Address Load

Installing a handler loads its address into a scratch register using the same forward-patchable LUI + ADDI pair described in §13.4, resolved once the handler's label address is known.

int_disable: CSR Instruction

The MIPS backend clears the IE bit via mtc0 on the CP0 Status register. The RISC-V backend clears the MIE (Machine Interrupt Enable) bit directly with a CSR instruction.

CSRRCI (funct3 = 111, opcode = SYSTEM / 0x73) clears the CSR bits specified by its 5-bit immediate and writes the CSR's prior value to the destination register. Here the destination is x0, so the old value is discarded and only the clear side-effect is kept.

13.10 MIPS vs RISC-V: Quick Reference

Both backends consume the same IrModule, so any BedRock program that doesn't use raw asm() injection (§4.6/§6.6, since those hex words are architecture-specific by definition) compiles correctly to either target with just a change of the --target flag.

14.1 Overview & Target Flag

The x86 backend consumes the same IrModule as MIPS and RISC-V. Select it with:

The result is an ET_EXEC ELF64 for Linux. Mark it executable and run:

14.2 ELF Layout

14.3 Syscalls & Hosted I/O

Hosted programs use the language-level syscall(...) form. Arguments follow the Linux x86-64 System V convention: number in RAX, arguments in RDI, RSI, RDX, R10, R8, R9.

14.4 vs RISC-V

15.1 Compilation Speed

Average time in ms — lower is better.

15.2 Binary Size Footprint

Average size in bytes — lower is better.

15.3 Detailed Breakdown

16.1 ESP32-C3 Live Firmware

Serial live plot from a physical ESP32-C3 running BedRock-generated firmware. The monitored channel holds a steady reading at 72, validating the UART output path from the bare-metal payload.

Figure — Live reading from ESP32-C3 (BedRock firmware). Latest: 72.

16.2 Wokwi Simulation

Wokwi project used for heart-rate style prototyping before flashing hardware: MCU, sensor path, and 1602-class LCD labeled Heart Rate Sim.

Figure — Wokwi simulation (ESP32 family) with Heart Rate Sim LCD and serial monitor.

16.3 Recommended Flow

1. Iterate pure logic with --target x86 when no MMIO is required.
2. Compile the firmware payload with --target riscv.
3. Validate pin-level behavior in Wokwi when the diagram matches the board.
4. Flash the ESP32-C3; confirm UART / display with a live serial plot as in §16.1.