Instacalc · Technology Quarterly
Technology Quarterly · Programming Languages

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.

Architecture Overview

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
Standard-library primitives used by 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).
Note: sLOC excludes blank lines, comments and triple-quoted docstrings. Source: Instacalc repository
Exhibit 1 · Source Browser

Inspecting the five layers of source code

Select any file below to read the exact .ic source embedded from the repository.

examples/nes/nes.ic 379 sLOC / 526 LOC

      
Syntax highlighting reflects .ic directives (red), keywords (blue), strings (green) and literals (ochre). Source: Instacalc repository
Exhibit 2 · Compilation Pipeline

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.

TIER 1 · INPUT @bits p_reg | N | V | U | B | 7 6 5 4 TIER 2 · EXPANDER @syntax bits bit_lens("7") folds lo=7, mask=1 TIER 2 · CORE .IC Pure functions shr32_unsigned(r,7) Zero macro runtime TIER 3 · TARGETS VM / JS / C99 (r >> 7u) & 1u Branchless 32-bit TIER 4 · SILICON ARM64 / x86-64 ubfx w0,w0,#7,#1 40 1C 07 53 Compile-time boundary: Tiers 1–2 run once during sheet compilation; Tiers 3–4 execute at native speed.
Showing all 4 tiers · Input through Machine Code
01Level 1 Input: ASCII Register Diagram (@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
02Level 2 Macro Expander: @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)
03Level 0 Expanded Core .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))
04Stack Bytecode VM Bytecode IR

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
05AOT Compiled JavaScript JS Target

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); }
06Native C99 C Target

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);
}
07Assembly (ARM64 Apple Silicon & x86-64) ISA Assembly

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
08Raw Machine Code Bytes Machine Code

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
Lowering trace captured from @bits p_reg in examples/nes/nes.ic. Source: Instacalc compiler & LLVM (ARM64 / x86-64)