Celene-8

A complete 8-bit computing stack: Custom ISA, assembler, emulator, C-like compiler, syscall-based runtime, and a synthesizable Verilog CPU.

Pipeline

                   ┌──────────────────┐
   foo.cel  ────►  │   celc (Python)  │  ──► foo.s
                   │  lex/parse/code  │
                   └──────────────────┘
                            │
   foo.s    ────►  ┌──────────────────┐  ──► foo.bin   (flat 64KiB image)
                   │  celasm (Python) │      foo.sym   (label → address)
                   │   2-pass         │
                   └──────────────────┘
                            │
                            ├───────────────────────────────────┐
                            ▼                                   ▼
              ┌──────────────────────────┐         ┌─────────────────────────┐
              │   celemu (Python)        │         │   Verilog CPU + TB      │
              │   trap-based syscalls    │         │   syscall = trap output │
              │   MMIO console + halt    │         │   $write on UART addr   │
              └──────────────────────────┘         └─────────────────────────┘

CPU implementation

The Verilog CPU (hardware/celene8_cpu.v) is a multi-cycle FSM:

                    +────────+
   reset ─────────► │ FETCH1 │ ─► (read opcode byte)
                    +────────+
                         │
                         ▼
                    +────────+      varies per opcode (0–3 extra fetches,
                    │ DECODE │ ───► some loads/stores, ALU writeback)
                    +────────+
                         │
                         ▼
                    +────────+
                    │ EXEC   │
                    +────────+
                         │
                         ▼
                    back to FETCH1

Layout

Path	What's there
tools/	celasm, celemu, celc (Python, one package: celene)
runtime/	crt0.s startup, std.s standard library
hardware/	Verilog CPU + testbench (Icarus Verilog compatible)
examples/	hello.cel, fib.cel, fizzbuzz.cel, echo.cel, primes.s
tests/	Unit + end-to-end tests

Quick start

# Install the toolchain (just Python ≥3.8, no deps)
pip install -e tools/

# Compile, assemble, and run "hello world"
cel cc examples/hello.cel -o build/hello.bin
cel emu build/hello.bin

# Or in one shot:
cel run examples/hello.cel

# Run on the Verilog CPU (requires icarus-verilog)
make hw-hello

What it does

• ISA: 8 registers, 16-bit address space, ~30 instructions, ZCN flags, variable-length encoding (1–4 bytes).
• Assembler: labels, .org, .byte, .word, .ascii, .asciz, .include, character/numeric literals, expressions in immediates.
• Emulator: cycle-accurate-ish, traps SYS for host I/O, --trace, --debug for stepping, MMIO console.
• Compiler: C-flavored language with byte/word, pointers, arrays, functions, recursion, if/while/return, inline asm(), string literals.
• Runtime: putchar, getchar, print_str, print_dec, read_line, __mul8, __div8, __mod8.
• Hardware: multi-cycle Verilog CPU with separate ALU, register file, memory + MMIO, testbench that loads a .bin and prints UART output.

A complete tiny program

; print "hi\n" then exit
.org 0x0000

start:
    LDI R6, #hi(msg)
    LDI R7, #lo(msg)
    SYS #3                ; print_str
    LDI R0, #0
    SYS #2                ; exit(0)

msg: .asciz "hi\n"

Build & run:

cel asm hi.s -o hi.bin
cel emu hi.bin