Two things: the TTL build is now the main target (Tang Nano looks too modern), and the packer learned the format that makes the TTL build simple. Format: r8forge_tape_pack --eprom writes one byte per instruction with the opcode in the low three bits. Then ip is the EPROM address and D2..D0 are the opcode -- no shift register, no 16 bit window, no decoder. It wastes five bits per instruction, and a 27C512 is exactly 64K, which is the historical instruction budget: the 8 bit calculator (51378) and the flagship (43676) both fit. Both formats live in the same .r8t trailer now (format byte 1 = packed, 2 = one byte per instruction), decode dispatches on it, and the test runs both and requires the same output and step count. Carrier: 74LS DIPs on a green board, 27C512 in a socket with its quartz window, 6116 SRAM, 74LS299 for the rotate, 6850 ACIA for serial, 74LS47 and four seven segment displays on the panel, 1 MHz can oscillator. About 31 to 40 chips, 400 to 700 CNY, a few weeks. The FPGA stays as a bench-only stepping stone. hardware/mechanics.md: where mechanics actually pays. The program must stay electronic (130 metres of paper tape for the calculator), and 512 relays for the data ring are out, but the pointer is worth it -- > and < are 71 to 73 percent of all steps, so a 64 position ratchet or uniselector makes the machine physically walk the ring. Also listed: an electromagnetic step counter (10 to 20 Hz, so only in single step mode, with a clutch for free running), a paper tape punch or plotter for output, a tape/card reader or plain keypad for input, and a hand crank as the clock. The rule that keeps this safe: mechanics only ever sit on sensor and actuator pins and never in the logic path, and the handshake just stops the sequencer while something moves -- since nothing in the ISA can observe time, slower is not different. A relay-only machine is priced honestly too: 60 to 120 relays, 10 to 50 Hz, hello in 10 to 40 seconds, the calculator in four hours, so that one is an exhibit. Also fixed: the synthesised macro fallback file name now carries a per-run token. When the system temp directory is not writable every r8asm falls back to the same working directory, so parallel ctest runs could write and import the same file -- which showed up as a random one-test failure in 0.39 seconds and nothing else.
140 lines
6.5 KiB
C++
140 lines
6.5 KiB
C++
#pragma once
|
|
|
|
#include <array>
|
|
#include <cstddef>
|
|
#include <cstdint>
|
|
#include <string>
|
|
#include <vector>
|
|
|
|
// The ROT-8 tape as *bits*, not as text.
|
|
//
|
|
// The assembler emits `.rot8`: one character per instruction, which is what the
|
|
// tools and the visualizer read. The hardware cannot afford that (an eight
|
|
// opcode instruction set needs three bits, so text wastes 62% of a ROM and needs
|
|
// an ASCII decoder in the datapath), so the image that goes into a ROM or a
|
|
// block RAM is packed.
|
|
//
|
|
// Opcode numbering follows the enum in the reference interpreter
|
|
// (ROT-8-viz/include/rot8/rot8.h: STP, BTP, ROR, FLB, BIZ, RNZ, OUT, INP).
|
|
// That table *is* the hardware's decoder, so the numbering is part of the
|
|
// interface: do not renumber it and do not change the packing.
|
|
//
|
|
// Packing: three bits per instruction, little end first, instructions laid out
|
|
// consecutively, so eight instructions fill exactly three bytes. Instruction i
|
|
// occupies bits 3*i .. 3*i+2 of the byte stream.
|
|
enum class opcode : uint8_t {
|
|
stp = 0, // '>'
|
|
btp = 1, // '<'
|
|
ror = 2, // '+'
|
|
flb = 3, // '-'
|
|
biz = 4, // '['
|
|
rnz = 5, // ']'
|
|
out = 6, // '.'
|
|
inp = 7, // ','
|
|
};
|
|
|
|
// Text (".rot8") -> opcodes. A character outside "><+-[].," is an error: the
|
|
// assembler never emits one, so seeing one means the tape is broken, and
|
|
// silently skipping it would hide that.
|
|
bool tape_decode(const std::string &text, std::vector<uint8_t> &code,
|
|
std::string &error);
|
|
// Opcodes -> text. `tape_decode` inverts this; a round trip has to be exact.
|
|
std::string tape_encode(const std::vector<uint8_t> &code);
|
|
|
|
// 3 bits per instruction, little end first.
|
|
std::vector<uint8_t> tape_pack(const std::vector<uint8_t> &code);
|
|
// The inverse. `length` comes from outside: the byte stream has padding bits at
|
|
// the top, so it cannot be recovered from the bytes alone.
|
|
bool tape_unpack(const std::vector<uint8_t> &bytes, size_t length,
|
|
std::vector<uint8_t> &code, std::string &error);
|
|
|
|
// ---- the .r8t image ----------------------------------------------------------
|
|
//
|
|
// The file a programmer burns or a block RAM initialises from: the packed body
|
|
// followed by a 16 byte trailer, so that address 0 of the medium is instruction
|
|
// 0 and the program can be executed in place (the trailer sits past the halt
|
|
// point and is never fetched).
|
|
//
|
|
// trailer +0 u32 instruction count, little endian
|
|
// +4 u8 cell width the tape was assembled for
|
|
// +5 u8 ring size in cells (0 = more than 255, use the default)
|
|
// +6 u8 format version (1)
|
|
// +7 u8 reserved (0)
|
|
// +8 "R8T1"
|
|
// +12 u32 crc32 of the body, little endian
|
|
struct tape_image {
|
|
std::vector<uint8_t> code;
|
|
size_t width = 0;
|
|
size_t ring = 0;
|
|
unsigned format = 1; // 1: 3 bits per instruction, 2: one byte per instruction
|
|
};
|
|
|
|
// format 1 packs three bits per instruction (dense: a block RAM or a bit sliced
|
|
// ROM); format 2 stores one byte per instruction with the opcode in the low three
|
|
// bits, which is what a plain EPROM wants: ip is the address and D2..D0 are the
|
|
// opcode, so the fetch needs no shift register and no decoder.
|
|
std::vector<uint8_t> tape_image_encode(const std::vector<uint8_t> &code,
|
|
size_t width, size_t ring,
|
|
unsigned format = 1);
|
|
// True when the bytes end with the trailer (the loader uses this to tell an
|
|
// image from a text tape without trusting the file name).
|
|
bool tape_is_image(const std::vector<uint8_t> &bytes);
|
|
bool tape_image_decode(const std::vector<uint8_t> &bytes, tape_image &img,
|
|
std::string &error);
|
|
|
|
// ---- the machine -------------------------------------------------------------
|
|
//
|
|
// A model of the *hardware*, not of the assembler: it executes a packed image
|
|
// (or the opcode vector, which is the same thing unpacked) and reports what a
|
|
// board would report -- the output stream, the final cells, and the step count.
|
|
//
|
|
// Why it exists: `r8forge_tape_run` reads text and `r8forge_derive` reads source;
|
|
// both are software interpreters. The board reads three bit opcodes out of a
|
|
// ROM and has to implement the bracket jump one way or another, so the two
|
|
// things that can go wrong in the hardware -- the packing and the bracket
|
|
// strategy -- need a model that is compared against the text level tools.
|
|
struct machine_options {
|
|
size_t ring = 0; // data cells, 0 = the build's default
|
|
size_t width = 0; // bits per cell, 0 = the build's default
|
|
size_t limit = 20'000'000; // step limit, the same as the other VMs
|
|
// The board has two ways to implement ']': scan backwards through the tape
|
|
// (what the interpreters do) or keep a stack of loop entry positions (what the
|
|
// hardware does, because scanning is O(body) *per iteration*). Both are
|
|
// compared here so the equivalence is a test and not a claim.
|
|
bool loop_stack = false;
|
|
// The contract (SPEC section 1, and ROT-8-viz) says ']' jumps back *onto* the
|
|
// '[' so it re-executes. The interpreters jump to the instruction after it,
|
|
// which prints the same thing but is one step shorter per loop. Default to
|
|
// the interpreters' reading so documented step counts stay comparable;
|
|
// `retest` is the contract reading, and the difference is exactly the number
|
|
// of taken ']' instructions, which the test asserts.
|
|
bool retest = false;
|
|
// Bookkeeping for the profiler. Off by default: counting every step is not
|
|
// free on a 20M step run.
|
|
bool profile = false;
|
|
// Optional starting cells (the debugger's `addr=value`). Copies over the
|
|
// zeroed ring, so a shorter vector only overwrites its own prefix.
|
|
const std::vector<uint32_t> *initial = nullptr;
|
|
// Called before each instruction when set (the debugger view).
|
|
void (*trace)(void *ctx, size_t ip, size_t dp, const uint32_t *cells,
|
|
size_t ring, uint8_t op) = nullptr;
|
|
void *trace_ctx = nullptr;
|
|
};
|
|
|
|
struct machine_result {
|
|
bool halted = false; // ran off the end of the tape
|
|
bool overrun = false; // hit the step limit
|
|
size_t steps = 0;
|
|
size_t back_jumps = 0; // taken ']' instructions (the step-count difference)
|
|
std::string error; // unbalanced bracket or bad opcode, empty when fine
|
|
std::vector<uint32_t> out;
|
|
std::vector<uint32_t> cells;
|
|
// Filled in only when machine_options::profile is set.
|
|
std::array<size_t, 8> op_counts{};
|
|
std::vector<size_t> cell_hits;
|
|
};
|
|
|
|
machine_result tape_run(const std::vector<uint8_t> &code,
|
|
const std::vector<uint32_t> &input,
|
|
const machine_options &opt = {});
|