Backend

Target and toolchain

The only target is little-endian RISC-V RV32IM with the ILP32 data model. External C and REIMU interfaces use the base-integer RISC-V ELF psABI, the processor-specific application binary interface that defines how separately compiled code interoperates. Internal calling conventions are implementation-defined.

ComponentRequired configuration
Clang/LLVMVersion 22
Targetriscv32-unknown-elf
ISA and ABI-march=rv32im -mabi=ilp32
REIMUTo be determined
Execution memory--memory=256M
Stack--stack=1M

The compiler emits GNU-style text assembly accepted by both the Clang integrated assembler and the pinned REIMU version. Any failure during Clang assembly or REIMU parsing, linking, or execution constitutes a contract violation. Assembly syntax accepted by Clang but unsupported by REIMU must not be emitted. Tests do not require a specific instruction selection, stack-frame shape, register allocator, symbol layout, or assembly text.

RISC-V instruction behavior follows the course-pinned RISC-V Unprivileged ISA specification. External calling behavior follows the course-pinned RISC-V ELF psABI. Both versions remain fixed for the course run.

LLVM IR and code generation

Students must use LLVM IR as their intermediate representation and be able to emit valid textual LLVM IR (.ll) accepted by Clang/LLVM 22 for the course target. The IR must preserve Rx semantics and use a target triple and data layout consistent with RV32IM/ILP32.

During frontend development, students may compile this IR with Clang and run the resulting assembly in REIMU to check program behavior before their own backend is ready. The completed compiler must generate RISC-V assembly from the LLVM IR using a student-implemented backend. Clang or LLVM code generation may be used for validation, but cannot replace that backend.

Clang may compile the C runtime, and generated programs may call custom helpers. A runtime helper must not interpret the source program or IR in place of code generation. Course staff may use other tools to produce reference results and performance baselines.

Frontend validation with LLVM IR

Given the frontend’s student.ll and the course runtime-example.c, compile both to text assembly and execute them together:

clang --target=riscv32-unknown-elf -march=rv32im -mabi=ilp32 \
  -O0 -S student.ll -o frontend-check.s
clang --target=riscv32-unknown-elf -march=rv32im -mabi=ilp32 \
  -O2 -fno-builtin -S runtime-example.c -o runtime.s
reimu --file=frontend-check.s,runtime.s --memory=256M --stack=1M \
  --output=frontend-check.out

Compare frontend-check.out with the expected source behavior to test the frontend independently of the student backend. The program reads from standard input; --output keeps its output separate from REIMU’s status messages. Use the same RV32 target for this check, including 32-bit addresses and usize/isize.

Data layout

Source integers and addresses are 32 bits. The table below gives the reference storage layout; student implementations may use another internal layout when source behavior and external interfaces remain correct.

TypeSize (bytes)Alignment (bytes)Representation
i32, u324432-bit two’s-complement or unsigned integer
isize, usize44Same width as an address
bool11false = 0, true = 1
&T, &mut T44One machine address
()01No data

The representation of internal registers and compiler-generated intermediate values is otherwise implementation-defined, provided that observable source behavior and all external interfaces are preserved. References carry no runtime lifetime information. Unit return values use no return register.

Reference aggregate layout

The course implementation uses the following convenient layout, but student implementations may choose another internal layout:

  • [T; N] has T’s alignment and size size(T) * N; element i begins at i * size(T).
  • Struct fields appear in declaration order, each at the first offset satisfying its alignment.
  • A struct’s alignment is the maximum field alignment, and its size is rounded up to that alignment.
  • Padding bytes have unspecified values and need not be preserved when a value is copied.
  • &[T; N] is one word, not a slice fat pointer.

Code crossing a selected runtime interface must use the same layout on both sides.

Calling conventions and value semantics

Ordinary functions, methods, recursion, and private assembly helpers may use any consistent internal convention. The psABI is recommended for convenience but is required only at actual external boundaries such as machine main, the course C runtime, and REIMU libc.

The psABI’s calling convention specifies where arguments and return values go, which registers a caller may expect to survive a call, and how the stack is aligned. For ordinary 32-bit integer or reference arguments, the first eight use a0 through a7, and further arguments use the stack; a 32-bit scalar result uses a0. Callees preserve s0 through s11 and restore sp. A caller that needs a value in caller-saved registers (a0 through a7, t0 through t6, or ra) to survive a call is responsible for saving and restoring it. At these external boundaries, the stack must follow the psABI’s 16-byte alignment rule. The linked specification covers aggregate arguments and the remaining rules.

Machine-level indirection must preserve source by-value semantics. For example, mutating the parameter inside fn f(mut x: [i32; 3]) must not modify the caller’s value. Storage may be reused after a move when the old value is no longer observable.

Methods may lower the receiver to an explicit parameter. Fixed-size arrays remain source-level by-value aggregates and do not undergo C-style array-to-pointer decay.

Symbols, entry, and runtime

The global machine symbol main must provide a C ABI entry point with behavior equivalent to int main(void). It invokes the source entry function and, after that invocation completes, returns the signed 32-bit value 0 in a0. It must obey the psABI, including stack alignment and register preservation.

The recommended lowering gives the source main a unique mangled internal symbol and generates a wrapper exporting the machine symbol main. Source calls to main, including recursive calls, target the internal source function and use its ordinary unit-returning calling convention. Returning from that function resumes its caller; returning from the wrapper ends the program normally. The source signature remains fn main() -> ().

For example, the following C-like sketch illustrates the split:

static void __rx_source_main(void) {
    /* Lowered source main body. */
}

int main(void) {
    __rx_source_main();
    return 0;
}

The internal symbol spelling is illustrative. Source and helper symbol names are implementation-defined but must be unique and must not collide with the machine entry or runtime symbols. The source function may use any supported internal calling convention. Equivalent lowering is permitted if it preserves both ordinary unit-returning source calls and the machine entry contract; a separate wrapper and internal function need not remain in the emitted code.

The source I/O builtins use this C ABI:

int32_t get_i32(void);
void print_i32(int32_t value);
void println_i32(int32_t value);

Their input and output behavior is defined by Builtin I/O. Students may use the course runtime or provide a compatible implementation. A runtime symbol is linked exactly once.

Reference C runtime

The repository includes this complete reference implementation:

/* Reference I/O and program-lifetime heap allocation for RV32/ILP32. */
typedef int int32_t;
typedef unsigned int uint32_t;

/* Compile-time size checks: a negative array length makes compilation fail. */
typedef char rx_int32_is_four_bytes[(sizeof(int32_t) == 4) ? 1 : -1];
typedef char rx_uint32_is_four_bytes[(sizeof(uint32_t) == 4) ? 1 : -1];

extern int printf(const char *format, ...);
extern int scanf(const char *format, ...);
extern void *malloc(uint32_t size);

/*
 * Valid course allocations have nonzero size and alignment 1 or 4. REIMU's
 * malloc result satisfies both alignments. Objects are not individually freed.
 */
void *__rx_alloc(uint32_t size, uint32_t align) {
  (void)align;
  return malloc(size);
}

int32_t get_i32(void) {
  int32_t value;
  (void)scanf("%d", &value);
  return value;
}

void print_i32(int32_t value) { (void)printf("%d", value); }

void println_i32(int32_t value) { (void)printf("%d\n", value); }

The local int32_t and uint32_t typedefs avoid requiring target C library headers. The rx_int32_is_four_bytes and rx_uint32_is_four_bytes typedefs are compile-time size checks: each declares an array type of length 1 when the corresponding integer type occupies four bytes, or an invalid negative length otherwise. They allocate no storage and generate no runtime instructions.

It can be compiled with:

clang --target=riscv32-unknown-elf -march=rv32im -mabi=ilp32 \
  -O2 -fno-builtin -S runtime-example.c -o runtime.s

Heap allocation interface

Generated code using the course runtime allocates Box and Vec storage through this fixed C ABI, which is not source-visible:

void *__rx_alloc(uint32_t size, uint32_t align);

size and align are byte counts. Valid calls have nonzero size and alignment 1 or 4. The function returns at least size accessible bytes at the requested alignment, disjoint from every allocation that has not been reused. Allocation succeeds for valid tests; failure behavior is unspecified.

There is no required __rx_dealloc. A custom runtime may instead use a private allocator, call REIMU malloc, or inline equivalent behavior. In every case, the compiler computes type size, alignment, element stride, and container capacity while the runtime manages untyped storage. Valid allocation calculations fit usize, so dynamic overflow checks and panic support are unnecessary.

REIMU also provides psABI-compatible memcpy, memmove, and memset. Use memcpy only for known-disjoint ranges and memmove when ranges may overlap.

Suggested compiler/runtime split
OperationCompiler responsibilityRuntime responsibility
Box constructionEvaluate, calculate layout, initialize, and return the ownerAllocate aligned bytes
Vec growthCalculate capacity, maintain metadata, and move live elementsAllocate a new buffer; optionally provide a helper
By-value operationsSelect copy or move and preserve value semanticsOptionally copy raw bytes
Container cloneRecursively clone the concrete TAllocate result storage
Program endNo typed destruction is requiredReclaim the execution’s heap

Resource guarantees

Tests run with 256 MiB total execution memory and a 1 MiB stack.

Assembly and execution

REIMU accepts text assembly files and assembles, links, and executes them internally. After compiling the selected C runtime to runtime.s as shown above, run the student backend’s student.s with:

reimu --file=student.s,runtime.s --memory=256M --stack=1M \
  --output=student.out

Both assembly inputs are text .s files; the program reads from standard input and writes to student.out. REIMU resolves calls to its supported libc functions, such as printf, scanf, and malloc. No object file or ELF binary is passed to REIMU. A custom runtime supplies its own assembly in place of runtime.s.

Normal source completion returns status 0, and every output byte, including whitespace, is observable.

Valid programs may contain integer constants and stack offsets that exceed the 12-bit signed immediate range, as well as control-flow jumps that exceed the reach of a single conditional branch instruction. The specification places no separate limit on source size, compile time, compiler memory, or generated assembly size.

Submission commands and grading policy are course administration rather than language or execution semantics.

Optimization and execution cost

No specific optimization is mandatory. A stack-slot baseline is valid if it handles calls, finite registers, and all valid control flow. Optimizations may change IR, registers, storage, and instruction sequences but must preserve observable source behavior and external interfaces.

Performance uses Total cycles reported by the pinned REIMU version with its default weights and no cost-model-changing options. The count includes generated code, runtime instructions, and priced libc operations. Baselines, aggregation, scores, and rankings are separate assessment policy.