SQ in silver chrome letters, a lab's gear stacked against the S: a rack, two oscilloscopes, pizza boxes and a six-pack. Strange Query Lab

CARDIAC › heartburn

heartburn's mark: a rusty sawblade with CARDIAC's instruction clock cut through it

heartburn

CARDIAC, stupid fast

brew tap strangequery/tap && brew trust strangequery/tap && brew install heartburn

heartburn is the engine under rust-cardiac: a CARDIAC emulator, as a Rust library, that runs about a billion instructions a second. For people without Rust it also comes as three programs of its own, for CARDIAC programs compiled with cargo-cardiac or written by hand: burn runs them, ekg debugs and profiles them, and carc assembles them.

burn

burn is heartburn's emulator as a program. It runs CARDIAC decks, the .cqb files:

# run a deck
burn countdown.cqb

# give input cards after the deck (the -- is optional)
burn add.cqb -- 123 456

# or on standard input, where each card is read
# when an INP asks for it
echo 123 456 | burn add.cqb

# read the deck itself from standard input
carc - < add.cq | burn -

# measure how fast this machine runs CARDIAC
burn bench

Decks. A deck is plain text, typically in a .cqb file, with one card per line. Lines starting with # are comments.

burn has no automatic loader, so a deck has to load itself, the way Brian Stuart's page describes. carc creates that bootstrap code automatically.

Output. Every value the program outputs is printed as a number on its own line. How the program stopped, and after how many instructions, goes to standard error. If a program's output values are characters (65 for A, 10 for a new line), pipe the output through perl:

burn hello.cqb | perl -CO -ne 'print chr if $_ >= 0'

Overlays. burn supports overlays as documented at Strange Query. A program too big for memory comes as NAME.cqb, NAME.2.cqb, and so on. When a deck is done, it halts with the program counter on the number of the deck to load next (HRS n), or on 00 when the whole program is finished. burn then does what a person running the machine would do: it puts that deck in the reader and starts the loader at 00. The decks can be loaded in any order, as often as the program asks. Cardigan is a useful tool for observing and debugging overlays.

Why a compiled program panicked. A compiler can write a panic map beside a deck, as a .pdb sits beside an .exe: cargo cardiac build writes NAME.map with NAME.cqb. On CARDIAC a panic is just the value -999 and a halt. With the map beside the deck, burn also says why on standard error, as Rust does, and exits 101 as cargo run does:

$ burn days.cqb -- 13
-999
     halted after 103 instructions
burn: days.cqb: panicked in main: index out of bounds

Without a map, nothing changes, and burn runs at full speed: it only keeps track of where a run ended when there is a map to read.

--limit=N stop a program after N instructions (the default is a billion)
-h, --help display help and exit
--version output version information and exit

Options go before the deck. Everything after the deck is input, including anything that starts with a minus sign. The exit status is 0 if the program halted or ran out of input cards. It is 1 if the deck can't be read, or if the program never stops (a run stops after a billion instructions, or after --limit). It is 2 if there is a mistake on the command line. It is 101 if the panic map says the program panicked (134 for a violated unsafe precondition, as Rust aborts on one).

How fast

burn bench runs three countdown loops nested inside each other, 626.5 million instructions in all, on one core. Here is the same program on every CARDIAC emulator we could build and run on an Apple M5 Ultra (October 2026):

emulator language million instructions a second per instruction
HEARTBURN Rust 1,070 0.94 ns
InPermutation/CARDIAC cem.c C (-O2) 438 2.3 ns
fzaca/CardiacVisualizer Rust 110 9.1 ns
weibell/python-cardiac-emu Python 3.9 2.4 417 ns
rzinkstok/cardiac Python 3.9 1.25 800 ns

These figures are per core. A CARDIAC program runs one instruction after another, so a single run uses a single core, but separate runs can go side by side on as many cores as the machine has.

How it gets this fast, so far:

  • Each cell's instruction is decoded once and kept next to its value. It is decoded again only when the cell is written, which matters because CARDIAC programs rewrite their own code all the time to index arrays. The decoding comes from a 4 KB table that holds the decoding of every possible word.
  • The accumulator wraps around with a comparison rather than a division.
  • JMP writes cell 99 already decoded.
  • A 101st decoded cell sends the program counter back round to 00, so no step has to check for it.
  • Tracing, which burn uses to say where a run stopped, is switched on or off when the program is compiled, so it costs nothing when it is off.
  • The main loop never allocates memory.

What comes next is fewer processor cycles per step, and running the idioms CARDIAC code is made of as single operations. For example, an indexed load is four instructions of self-modifying code. There is no JIT compiler. HEARTBURN is an interpreter, made as fast as an interpreter can be.

ekg

ekg is the debugger and the profiler. You give it either a listing or a deck, followed by the program's input. ekg tells which one it has from what is inside the file. A listing is assembled the way carc assembles it, and its labels and comments are kept for display. A deck is loaded through its own loader, the way burn loads it, and then disassembled.

ekg countdown.cq             # debug at the (ekg) prompt
ekg --batch mul.cq -x 'break 17' -x run -x 'p p' -- 6 7
ekg --profile mul.cq -- 6 7  # run to the end and report where the instructions went

Debugging. The commands are the same as gdb's wherever gdb has an equivalent. A PLACE is a cell (00 to 99), a label, or label+N.

run, r start the program again from the beginning, with its input, and continue
continue, c run until a breakpoint, a watch, a halt, or an INP with no card to read
step, s [N] run one instruction, or N of them
next, n [N] like step, but when a JMP calls a routine, run the whole routine and stop at the cell after the JMP. (A JMP counts as a call when the code it jumps to reads cell 99, the way back, before it reaches another JMP.)
break, b PLACE stop before the instruction in PLACE runs
watch PLACE stop after an instruction writes to PLACE
delete, d [PLACE] remove the breakpoint and the watch on PLACE, or all of them if no PLACE is given
info break, i b list the breakpoints and watches
info registers, i r show the program counter, the accumulator, how many instructions have run, and the cards in the reader
print, p PLACE show a cell's value, and what it means as an instruction (p acc and p pc also work)
x PLACE [N] show the values of N cells starting at PLACE (10 if N isn't given)
list, l [PLACE] show the listing around the program counter (or around PLACE), with the program counter marked > and breakpoints marked b
set PLACE VALUE write a value into a cell (set acc VALUE and set pc PLACE also work)
input CARDS... add cards to the reader, after the ones already in it
help, h list the commands
quit, q leave

Pressing Enter on an empty line repeats the last step, next or continue. Whenever ekg stops, it shows the next instruction the way the listing has it. If the program has rewritten that cell, the instruction is decoded again from the new value. Each value the program outputs is printed as soon as it is output, on a line starting with out:. If an INP finds no card left, ekg stops and waits for you to give it more with input.

Profiling. --profile runs the program to the end and prints a report on standard output, while the program's own output goes to standard error. The report shows how many instructions ran, the hottest cells, every cell of the listing with how often it ran, the cells the program wrote to (and which of those it also ran, meaning code it rewrites), and the listed instructions that never ran. If you give no input, the program reads its cards from standard input, as it would in burn. To see every instruction, ekg drives the machine one instruction at a time. It profiles about 270 million instructions per second, a quarter of burn's speed, and burn doesn't pay anything for it.

-x, --eval-command=COMMAND carry out COMMAND (you can give any number of them, and they run in order)
--batch carry out the -x commands, then exit without reading standard input
-q, --quiet, --silent skip the introduction
--profile profile instead of debugging
--limit=N stop a run after N instructions (the default is 1,000,000,000)
--start-at=NN start a listing at cell NN (by default, where carc would start it)
--help display help and exit
--version output version information and exit

The exit status is 0 on success. It is 1 if something failed: the listing has errors, a -x command failed in --batch mode, or a profile run was stopped by the limit. It is 2 if there is a mistake on the command line.

carc

carc is the assembler. It turns a listing into a deck.

carc countdown.cq                           # writes countdown.cqb next to it
carc --start-at=10 -o out.cqb countdown.cq  # options can go before or after the file
carc - < countdown.cq | burn -              # read the listing from standard input, write the deck to standard output

Listings. A listing has one cell per line. The columns are either Brian Stuart's six, ADDRESS CONTENTS LABEL OPCODE OPERAND COMMENT, or the manual's three, ADDRESS CONTENTS COMMENT. You can leave the contents out, and carc works them out from the opcode and the operand. The operand can be a number, a label, or label+N. DATA (or DAT) puts a plain number in a cell. Lines that aren't cells, such as titles, prose, and comments starting with ; or #, are skipped.

Where the program starts. The deck starts the program at the cell given by --start-at. Without it, carc looks in the listing: first for a Start at NN. line, then for a line labelled start, and otherwise it uses the first instruction.

Errors and warnings are reported the way a compiler reports them. While there are errors, no deck is written. If a cell's contents disagree with its opcode and operand, that is only a warning, and the contents are what get loaded.

-o, --output=FILE write the deck to FILE (- means standard output). By default it goes to NAME.cqb next to NAME.cq, or to standard output if the listing came from standard input.
--start-at=NN start the program at cell NN
-h, --help display help and exit
--version output version information and exit

The exit status is 0 if the deck was written. It is 1 if the listing has errors or a file can't be read or written, and 2 if there is a mistake on the command line.

Get it

For burn, carc and ekg on their own, without Rust, add Strange Query's Homebrew tap, trust it, and install heartburn:

brew tap strangequery/tap
brew trust strangequery/tap
brew install heartburn

There are also archives of the three programs for macOS, Linux and Windows on heartburn's releases page.

If you write Rust, you don't need them: cargo-cardiac has heartburn underneath, and cargo cardiac run, cargo cardiac debug and cargo cardiac asm are burn, ekg and carc. To use the emulator as a library in your own program, add the heartburn crate:

cargo add heartburn

To build the programs from the source code instead:

git clone https://github.com/StrangeQuery/heartburn
cd heartburn
cargo build --release --features tools

The programs end up in target/release/.