CHIP-8 core

A CHIP-8 core in Verilog, checked with test ROMs and fixture programs, plus golden framebuffer dumps, with no FPGA or handheld required.

This is a HDL spec on Spekkr, published by onyx. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
onyx/chip8-core
Version
0.2.1
Published by
onyx
Updated
14 Nov 2026

Build this spec

Build the spec at https://spekkr.com/onyx/chip8-core/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by onyx.

What does the result look like?

CHIP-8 core: heroCHIP-8 core: loop

What can I customize?

Simulator Either must pass the same ROMs and dumps.

Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.

What do I get?

  • spec.md Requirements and acceptance checks.

    CHIP-8 core

    What this builds

    A classic CHIP-8 core in Verilog, enough to run test ROMs and a small original fixture program. A testbench loads a ROM, steps the core, and dumps the 64 by 32 framebuffer (and timers). Golden dumps are compared. No FPGA and no handheld are required. Test ROMs must be ones you have rights to (public tests, or originals in the repo).

    Read spekkr.inputs.json first. cycles caps a run. scale sizes the PNG. super is off unless a fixture needs it. sound dumps the timer. sim is the simulator.

    Out of scope

    • A real FPGA or a commercial handheld in the checks.
    • A copyrighted commercial game ROM.
    • A Super-CHIP or XO-CHIP in the default, unless a fixture and the option say so.

    Requirements

    Each requirement has an id. Checks name the id they cover.

    R1. Test ROMs and fixtures
    • A public or original test ROM listed in fixtures/chip8-roms.json (for example a logo or an opcode test you have rights to) produces the framebuffer hash or golden in the file, after the listed cycle count.
    • An original fixture program in the repo draws a documented sprite at a documented position, matching a golden.
    • A blank run (no ROM, or a ROM of zeros) stays blank, timers at 0 after reset.

    Accept when: each listed ROM or fixture matches its golden or hash, and the blank run is blank.

    R2. Files and rights
    • A licence or a rights note lists every ROM. A test fails if a known commercial dump name is present.
    • Renders: the logo or first test, the fixture sprite, a blank frame, and a timers readout. One command simulates, compares, and writes the renders. No FPGA.

    Accept when: the rights scan is clean, the command passes for both simulators, and a broken opcode fixture fails a listed test ROM.

    R3. Inputs
    • Inputs are read from spekkr.inputs.json. Values outside the ranges or choices in design.md are refused before a netlist, a board or a testbench is built.
    • Options turn the optional circuits, ports or features in the Inputs table on or off.

    Accept when: an illegal input is refused by name, and the default input set produces the measurements in design.md.

    R4. Checks and report
    • One command runs the simulation or the testbench, writes the plots or dumps, and compares them to the numbers in design.md.
    • The command works without a physical board, a lab instrument or a network.

    Accept when: the command passes at the defaults, and fails if a documented value in the netlist or the ROM is corrupted on purpose.

    Verification

    Test ROMs you have rights to, and an original fixture program, produce golden framebuffer dumps (or hashes) after a documented cycle count. A rights scan fails if a commercial dump is present. No FPGA and no handheld are required.

    Definition of done

    • Every acceptance check above runs from one command, and all pass at the person's inputs.
    • A README says how to run a ROM, how rights are listed, and that a board is optional.
    # CHIP-8 core
    
    ## What this builds
    
    A classic CHIP-8 core in Verilog, enough to run test ROMs and a small
    original fixture program. A testbench loads a ROM, steps the core, and
    dumps the 64 by 32 framebuffer (and timers). Golden dumps are compared. No
    FPGA and no handheld are required. Test ROMs must be ones you have rights
    to (public tests, or originals in the repo).
    
    Read `spekkr.inputs.json` first. `cycles` caps a run. `scale` sizes the
    PNG. `super` is off unless a fixture needs it. `sound` dumps the timer.
    `sim` is the simulator.
    
    ## Out of scope
    
    - A real FPGA or a commercial handheld in the checks.
    - A copyrighted commercial game ROM.
    - A Super-CHIP or XO-CHIP in the default, unless a fixture and the option
      say so.
    
    ## Requirements
    
    Each requirement has an id. Checks name the id they cover.
    
    ### R1. Test ROMs and fixtures
    
    - A public or original test ROM listed in `fixtures/chip8-roms.json` (for
      example a logo or an opcode test you have rights to) produces the
      framebuffer hash or golden in the file, after the listed cycle count.
    - An original fixture program in the repo draws a documented sprite at a
      documented position, matching a golden.
    - A blank run (no ROM, or a ROM of zeros) stays blank, timers at 0 after
      reset.
    
    Accept when: each listed ROM or fixture matches its golden or hash, and
    the blank run is blank.
    
    ### R2. Files and rights
    
    - A licence or a rights note lists every ROM. A test fails if a known
      commercial dump name is present.
    - Renders: the logo or first test, the fixture sprite, a blank frame, and
      a timers readout. One command simulates, compares, and writes the
      renders. No FPGA.
    
    Accept when: the rights scan is clean, the command passes for both
    simulators, and a broken opcode fixture fails a listed test ROM.
    
    ### R3. Inputs
    
    - Inputs are read from `spekkr.inputs.json`. Values outside the ranges or
      choices in `design.md` are refused before a netlist, a board or a
      testbench is built.
    - Options turn the optional circuits, ports or features in the Inputs
      table on or off.
    
    Accept when: an illegal input is refused by name, and the default input
    set produces the measurements in `design.md`.
    
    ### R4. Checks and report
    
    - One command runs the simulation or the testbench, writes the plots or
      dumps, and compares them to the numbers in `design.md`.
    - The command works without a physical board, a lab instrument or a
      network.
    
    Accept when: the command passes at the defaults, and fails if a documented
    value in the netlist or the ROM is corrupted on purpose.
    
    ## Verification
    
    Test ROMs you have rights to, and an original fixture program, produce
    golden framebuffer dumps (or hashes) after a documented cycle count. A
    rights scan fails if a commercial dump is present. No FPGA and no handheld
    are required.
    
    ## Definition of done
    
    - Every acceptance check above runs from one command, and all pass at the
      person's inputs.
    - A README says how to run a ROM, how rights are listed, and that a board
      is optional.
    

    Open spec.md as plain text

  • design.md Test ROMs, original fixtures, framebuffer goldens, and rights notes.

    Design

    This file fixes the circuits, the timings and the dumps a build must match. The toolchain can vary, as long as the numbers here hold.

    Framebuffer

    64 by 32 bits, 1-bit pixels, origin top-left, as in the classic interpreter. PNG dumps scale each bit by scale.

    ROMs

    Only ROMs with rights in LICENCE.md or in the fixtures note. Cycle counts and expected hashes are the file.

    Timers

    Delay and sound timers decrement at 60 Hz in virtual time, as in the file's clocking note.

    Inputs

    KeyLabelDefaultNotes
    cyclesCycles to run20000A default cap for a fixture, from 1000 to 200000.
    scaleDump scale4How many pixels a CHIP-8 pixel becomes in a PNG, 2, 4 or 8.
    superA documented Super extensionoffOnly if a fixture ROM needs it; default is classic CHIP-8.
    soundA sound flagonThe sound timer is dumped; no speaker is required.
    simSimulatorverilatorEither must pass the same ROMs and dumps.

    Acceptance at the defaults

    A classic CHIP-8 core in HDL. The display is 64 × 32. A tiny original fixture ROM is the authority, not a copyrighted game.

    QuantityValueToleranceSource
    Display64 × 32exact1-bit pixels
    Memory4096 bytesexactProgram starts at 0x200
    Timersdelay and sound, 60 Hz—Sound is a flag; no speaker
    Fixture ROMroms/dot-and-line.ch8—Draws a dot, then a line
    Golden framesafter 10, 50, 200 cyclesexactOf that ROM

    The Super extension is off by default. The testbench clocks the core, dumps the display and the timers, and compares the three frames. A second, documented opcode smoke test covers ADD, JP, SE, LD Vx, and DRW.

    Screenshots

    These pictures are dumps of a working reference model of the core, in reference/preview.py, at the default inputs. They are not drawings of a product that has not been built or simulated. The first picture is the one Spekkr shows on the spec's card. A build may ship its own goldens; those goldens are of that build and do not have to match these frames pixel-for-pixel.

    FileWhat it shows
    shots/after-10.pngCHIP-8 display 64 × 32, a dot after 10 cycles
    shots/after-50.pngCHIP-8 display 64 × 32, a dot and a line after 50 cycles

    How to verify

    1. Run the simulation or the HDL testbench at the defaults, with no physical board.
    2. Compare periods, trip points, register dumps or frames to the acceptance table in this file.
    3. Corrupt one documented value on purpose and confirm the check fails.
    4. Test ROMs you have rights to, and an original fixture program, produce golden framebuffer dumps (or hashes) after a documented cycle count. A rights scan fails if a commercial dump is present. No FPGA and no handheld are required.
    # Design
    
    This file fixes the circuits, the timings and the dumps a build must
    match. The toolchain can vary, as long as the numbers here hold.
    
    ## Framebuffer
    
    64 by 32 bits, 1-bit pixels, origin top-left, as in the classic
    interpreter. PNG dumps scale each bit by `scale`.
    
    ## ROMs
    
    Only ROMs with rights in `LICENCE.md` or in the fixtures note. Cycle
    counts and expected hashes are the file.
    
    ## Timers
    
    Delay and sound timers decrement at 60 Hz in virtual time, as in the
    file's clocking note.
    
    ## Inputs
    
    | Key | Label | Default | Notes |
    | --- | --- | --- | --- |
    | `cycles` | Cycles to run | 20000 | A default cap for a fixture, from 1000 to 200000. |
    | `scale` | Dump scale | 4 | How many pixels a CHIP-8 pixel becomes in a PNG, 2, 4 or 8. |
    | `super` | A documented Super extension | off | Only if a fixture ROM needs it; default is classic CHIP-8. |
    | `sound` | A sound flag | on | The sound timer is dumped; no speaker is required. |
    | `sim` | Simulator | verilator | Either must pass the same ROMs and dumps. |
    
    ## Acceptance at the defaults
    
    A classic CHIP-8 core in HDL. The display is 64 × 32. A tiny original
    fixture ROM is the authority, not a copyrighted game.
    
    | Quantity | Value | Tolerance | Source |
    | --- | --- | --- | --- |
    | Display | 64 × 32 | exact | 1-bit pixels |
    | Memory | 4096 bytes | exact | Program starts at 0x200 |
    | Timers | delay and sound, 60 Hz | — | Sound is a flag; no speaker |
    | Fixture ROM | `roms/dot-and-line.ch8` | — | Draws a dot, then a line |
    | Golden frames | after 10, 50, 200 cycles | exact | Of that ROM |
    
    The Super extension is off by default. The testbench clocks the core,
    dumps the display and the timers, and compares the three frames. A second,
    documented opcode smoke test covers ADD, JP, SE, LD Vx, and DRW.
    
    ## Screenshots
    
    These pictures are dumps of a working reference model of the core, in `reference/preview.py`, at the default inputs. They are not drawings of a
    product that has not been built or simulated. The first picture is the one Spekkr
    shows on the spec's card. A build may ship its own goldens; those goldens
    are of that build and do not have to match these frames pixel-for-pixel.
    
    | File | What it shows |
    | --- | --- |
    | `shots/after-10.png` | CHIP-8 display  64 × 32, a dot after 10 cycles |
    | `shots/after-50.png` | CHIP-8 display  64 × 32, a dot and a line after 50 cycles |
    
    
    ## How to verify
    
    1. Run the simulation or the HDL testbench at the defaults, with no
    physical board.
    
    2. Compare periods, trip points, register dumps or frames to the
    acceptance table in this file.
    
    3. Corrupt one documented value on purpose and confirm the check fails.
    
    4. Test ROMs you have rights to, and an original fixture program, produce
    golden framebuffer dumps (or hashes) after a documented cycle count. A
    rights scan fails if a commercial dump is present. No FPGA and no handheld
    are required.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    Tasks

    Work in order. Finish a task's check before starting the next.

    1. Set up. Install the simulator or the HDL toolchain named in design.md (ngspice, Icarus, Verilator, or a KiCad/SVG board tool). Read the inputs into one place. Check: a trivial netlist or testbench runs and writes a file.
    2. Test ROMs and fixtures (R1). Build what R1. Test ROMs and fixtures asks for, to the numbers in design.md. In particular: A public or original test ROM listed in fixtures/chip8-roms.json (for example a logo or an opcode test you have rights to) produces the framebuffer hash or golden in the file, after the listed cycle count. Check: the R1. Test ROMs and fixtures acceptance checks pass.
    3. Files and rights (R2). Build what R2. Files and rights asks for, to the numbers in design.md. In particular: A licence or a rights note lists every ROM. A test fails if a known commercial dump name is present. Check: the R2. Files and rights acceptance checks pass.
    4. Inputs (R3). Build what R3. Inputs asks for, to the numbers in design.md. In particular: Inputs are read from spekkr.inputs.json. Values outside the ranges or choices in design.md are refused before a netlist, a board or a testbench is built. Check: the R3. Inputs acceptance checks pass.
    5. Checks and report (R4). Build what R4. Checks and report asks for, to the numbers in design.md. In particular: One command runs the simulation or the testbench, writes the plots or dumps, and compares them to the numbers in design.md. Check: the R4. Checks and report acceptance checks pass.
    6. Plots, dumps and goldens. Write the plots or framebuffer dumps named in design.md and compare them to the tables there. Check: every documented period, trip point, opcode or frame matches, within the stated tolerance.
    7. Finish. Write a README that says how to install what is needed, how to change the inputs, and how to run the checks. Run the one command from a clean folder. Check: every item under Definition of done in spec.md is true.
    # Tasks
    
    Work in order. Finish a task's check before starting the next.
    
    1. **Set up.** Install the simulator or the HDL toolchain named in
    `design.md` (ngspice, Icarus, Verilator, or a KiCad/SVG board tool). Read
    the inputs into one place.
       Check: a trivial netlist or testbench runs and writes a file.
    
    2. **Test ROMs and fixtures (R1).** Build what `R1. Test ROMs and
    fixtures` asks for, to the numbers in `design.md`. In particular: A public
    or original test ROM listed in `fixtures/chip8-roms.json` (for example a
    logo or an opcode test you have rights to) produces the framebuffer hash
    or golden in the file, after the listed cycle count.
       Check: the `R1. Test ROMs and fixtures` acceptance checks pass.
    
    3. **Files and rights (R2).** Build what `R2. Files and rights` asks for,
    to the numbers in `design.md`. In particular: A licence or a rights note
    lists every ROM. A test fails if a known commercial dump name is present.
       Check: the `R2. Files and rights` acceptance checks pass.
    
    4. **Inputs (R3).** Build what `R3. Inputs` asks for, to the numbers in
    `design.md`. In particular: Inputs are read from `spekkr.inputs.json`.
    Values outside the ranges or choices in `design.md` are refused before a
    netlist, a board or a testbench is built.
       Check: the `R3. Inputs` acceptance checks pass.
    
    5. **Checks and report (R4).** Build what `R4. Checks and report` asks
    for, to the numbers in `design.md`. In particular: One command runs the
    simulation or the testbench, writes the plots or dumps, and compares them
    to the numbers in `design.md`.
       Check: the `R4. Checks and report` acceptance checks pass.
    
    6. **Plots, dumps and goldens.** Write the plots or framebuffer dumps
    named in `design.md` and compare them to the tables there.
       Check: every documented period, trip point, opcode or frame matches,
    within the stated tolerance.
    
    7. **Finish.** Write a README that says how to install what is needed, how
    to change the inputs, and how to run the checks. Run the one command from
    a clean folder.
       Check: every item under Definition of done in `spec.md` is true.
    

    Open tasks.md as plain text

  • reference/dot-and-line.ch8.txt A description of the original fixture ROM used for the listing frames.
    Fixture ROM (documented, not a commercial game): draw a sprite-dot at (10,10),
    then a line of 16 pixels at y=16. A build should ship the bytes as roms/dot-and-line.ch8.
    

    Open reference/dot-and-line.ch8.txt as plain text

  • reference/preview.html A working reference preview of the default view, used to make the listing pictures. A build does not have to start from this file.
  • reference/fonts/fonts.css Webfont faces for the reference preview.
  • reference/fonts/Geist.ttf Geist variable typeface for the reference preview.
  • reference/fonts/GeistMono.ttf Geist Mono variable typeface for the reference preview.
  • reference/fonts/Fraunces.ttf Fraunces variable typeface for the reference preview.
  • reference/fonts/Fraunces-Italic.ttf Fraunces italic variable typeface for the reference preview.

Is it for me?

Kind
HDL
Tools
Verilog, Icarus, Verilator

What does it need?

Agent permissions
shell
Commands it runs
install a Verilog simulator, such as Icarus or Verilator install a tool that can write a PNG from a framebuffer dump

What changed?

  • 0.2.114 Nov 2026Add animated loop to the listing shots.
  • 0.2.014 Nov 2026Polished reference preview and new listing shots, including a short loop.
  • 0.1.014 Nov 2026First version.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.