From datasheet to silicon
How a 196-line Nintendo Entertainment System emulator in Instacalc compiles ASCII register diagrams down to eight bytes of ARM64 machine code.
Hardware manuals are written in tables, bit-field boxes and memory maps; emulators are usually written in walls of bit-shifting arithmetic. In between lies a tedious translation step where off-by-one mask errors hide for years. Instacalc's .ic language closes that gap by letting programmers declare small, domain-specific notations directly inside a sheet and expand them to plain core functions before compilation begins.
The Nintendo Entertainment System emulator in examples/nes/nes.ic is a stress test of that idea. Its Ricoh 2A03 processor, memory bus, 2C02 picture-processing unit and iNES cartridge loader are completely self-contained. Rather than hard-coding bitmasks for the 6502 status register or hand-writing a sprawling address-decoding switch, the emulator expresses them as readable ASCII diagrams using forms such as @bits, @bus, @modes and @opcodes. Those forms are not built into the compiler; they live in the file's own @syntax appendix at the bottom of nes.ic, powered by a self-hosted macro and packrat PEG layer.
The codebase at a glance
Five .ic files span the entire stack, from the packrat parser runtime to the self-contained emulator and CRT bezel.
| File | Layer | Responsibility | Tokens | sLOC | LOC |
|---|---|---|---|---|---|
| User-Defined Application (examples/nes/) | |||||
examples/nes/nes.ic |
User · L0/L1 | Self-contained 6502 CPU (@table op, @bits, @modes, @opcodes, @exec), memory bus (@bus), 2C02 PPU, iNES loader (210 sLOC) and inline @syntax appendix (169 sLOC). |
4,970 | 379 | 526 |
examples/nes/web.ic |
User · UI | TrueColor half-block, ASCII and SVG renderers, render_tv CRT bezel and @view card. |
1,916 | 98 | 175 |
| Subtotal — User Code (2 files) | User | Everything written specifically for the NES emulator and display. | 6,886 | 477 | 701 |
| Standard .ic Core (packages/engine/src/stdlib/) | |||||
stdlib/forms/syntax.ic |
Core · L2 | General macro helpers: splice, refuse, syntax_rows, pipe_cells, table_rows, bit_lens, emit_match. |
2,681 | 77 | 191 |
stdlib/forms/form-decl.ic |
Core · L2 | Self-hosted @form and @syntax compiler. |
3,452 | 88 | 211 |
stdlib/language/peg-runtime.ic |
Core · L2 | Packrat PEG parser runtime (makeLanguage). |
2,779 | 138 | 220 |
| Subtotal — Standard .ic Core (3 files) | Core | Reusable language machinery shipped with Instacalc (zero NES-specific code). | 8,912 | 303 | 622 |
| Total (5 files) | All | Complete NES emulator, presentation layer, macro system and PEG runtime in pure .ic. |
15,798 | 780 | 1,323 |
nes.ic:
word32.ic (u8, u16, s8, hi8, word16, hex2, bit_at, and32, or32, xor32, shl32, shr32_unsigned) and
lists/core (slice, concat, append, range, reduce, any, mod, int).
Inspecting the five layers of source code
Select any file below to read the exact .ic source embedded from the repository.
.ic directives (red), keywords (blue), strings (green) and literals (ochre).
Source: Instacalc repository
How an ASCII register diagram becomes eight bytes of silicon
Macro expansion folds all bitfield geometry at compile time. What reaches the bytecode VM, JavaScript AOT backend and native C99 compiler is branchless 32-bit arithmetic.
@bits p_reg)
examples/nes/nes.ic
The 6502 processor status register P is written directly as a datasheet diagram instead of fourteen hand-coded bitmasks and shift offsets. Each cell names a flag (N Negative, V Overflow, U Unused, down to C Carry) above its bit index.
@bits p_reg
| N | V | U | B | D | I | Z | C |
7 6 5 4 3 2 1 0
@syntax bits(form) & bit_lens(spec)
examples/nes/nes.ic (@syntax appendix)
At compile time, the macro engine hands the indented block to @syntax bits(form) via on_rows(form, ...). It zips pipe_cells(rs[0]) with re_split(rs[1], /\s+/), skips unused _ slots, and calls bit_lens(pair[1]) in syntax.ic to compute lo, mask and inv, emitting getter, setter and patch functions.
@syntax bits(form) = on_rows(form, (nm, rs) => {
pairs = zip(pipe_cells(rs[0]), re_split(rs[1], /\s+/))
|> filter(pair => re_test(pair[0], /^[A-Za-z_]\w*$/) and pair[0] != "_")
fns = pairs |> map(pair => {
b = bit_lens(pair[1])
return [
emit_fn("{nm}_{pair[0]}", "r", "and32(shr32_unsigned(r, {b.lo}), {b.mask})"),
emit_fn("{nm}_set_{pair[0]}", "r, v", "or32(and32(r, {b.inv}), shl32(and32(v, {b.mask}), {b.lo}))")
]
}) |> flatten(1)
...
})
// For field "N" at bit "7":
// lo = 7, mask = 1, inv = 0xFFFFFFFF ^ (1 << 7) = 4294967167 (0xFFFFFF7F)
.ic
Pure Core .ic
The strings returned by @syntax bits(form) are spliced back into the sheet as ordinary core .ic functions. All compile-time bitfield arithmetic is already folded into integer literals; no macro machinery survives to runtime.
p_reg_N(r) = and32(shr32_unsigned(r, 7), 1) p_reg_set_N(r, v) = or32(and32(r, 4294967167), shl32(and32(v, 1), 7))
The .ic compiler parses p_reg_N(r) into a typed abstract syntax tree and lowers it to flat stack-machine opcodes shared by the JavaScript host and the standalone C virtual machine.
fn p_reg_N(r): LOAD_ARG 0 ; push r PUSH_INT 7 BIT_RSHIFT ; r >>> 7 PUSH_INT 1 BIT_AND ; & 1 RETURN
For hot execution in browsers and Node.js, the ahead-of-time backend lowers each core function into branchless 32-bit unsigned bitwise expressions that V8 compiles to single-cycle shifts and masks.
export function f_p_reg_N(r) { return (r >>> 7) & 1; }
export function f_p_reg_set_N(r, v) { return (r & 4294967167) | ((v & 1) << 7); }
For native builds, the C backend emits static inline uint32_t helpers. Unsigned 32-bit arithmetic guarantees logical right-shift semantics and lets Clang or GCC inline and fold them without guards.
static inline uint32_t ic_p_reg_N(uint32_t r) { return (r >> 7u) & 1u; }
static inline uint32_t ic_p_reg_set_N(uint32_t r, uint32_t v) {
return (r & 0xFFFFFF7Fu) | ((v & 1u) << 7u);
}
LLVM recognises the shift-and-mask idiom (r >> 7u) & 1u and collapses both operations into a single ARM64 bitfield extract instruction (ubfx) and a single bitfield insert (bfi) for the setter. On x86-64 it emits shr followed by and.
; ARM64 (Apple Silicon) _ic_p_reg_N: ubfx w0, w0, #7, #1 ; extract 1 bit at bit 7 in 1 instruction ret _ic_p_reg_set_N: bfi w0, w1, #7, #1 ; insert bit 0 of v into bit 7 of r in 1 instruction ret ; x86-64 (System V ABI) ic_p_reg_N: mov eax, edi shr eax, 7 and eax, 1 ret
Finally, the assembler encodes each mnemonic into fixed-width 32-bit little-endian ARM64 words (or variable-length x86-64 bytes). The ASCII register diagram in examples/nes/nes.ic has become eight bytes of silicon instructions.
ARM64 _ic_p_reg_N: 40 1C 07 53 C0 03 5F D6 ; ubfx w0,w0,#7,#1 ; ret ARM64 _ic_p_reg_set_N: 20 00 07 33 C0 03 5F D6 ; bfi w0,w1,#7,#1 ; ret x86-64 ic_p_reg_N: 89 F8 C1 E8 07 83 E0 01 C3 ; mov eax,edi ; shr eax,7 ; and eax,1 ; ret
@bits p_reg in examples/nes/nes.ic.
Source: Instacalc compiler & LLVM (ARM64 / x86-64)