CARDIAC › heartburn
heartburn
CARDIAC, stupid fast
brew tap strangequery/tap && brew trust strangequery/tap && brew install heartburn
GitHub
Discord
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/.