Files
dsh 9b31a51fec hardware: M0 -- the packer, the RTL, and a simulator that agrees byte for byte
The two things software cannot check by reading its own source are the 3 bit
packing and the bracket strategy, so both got a tool and a test.

New in the library (r8forge/tape.hh, src/tape.cc): the opcode numbering (taken
from ROT-8-viz enum, so the packed image and the hardware decoder cannot drift),
text <-> opcodes, opcodes <-> 3 bit bytes, the .r8t image with its trailer and
crc32, and a machine model that runs a packed tape the way a board would.  The
model takes the bracket strategy as an option: backward scan with loop stack or
not, and jump-back-onto-the-[ (the contract) or past it (what the interpreters
do).  All four combinations print the same thing, and the step count differs by
exactly the number of taken ] instructions -- which is what the test asserts.

Found and fixed while writing it: the loop stack discipline depends on the jump
convention.  Jumping onto the [ means the [ re-pushes, so ] must pop on the jump;
jumping past it means the entry must stay until the loop exits.  Mixing them up
emptied the stack on the second iteration of the calculator main loop -- caught
by the equivalence test on examples/calc.r8asm, not by reading the code.

Tools: r8forge_tape_pack (text tape -> image + --hex for $readmemh + --verify,
727 instructions become 273 bytes for hello, 62%, and the trailer sits past the
halt so address 0 of a ROM is instruction 0), and r8forge_tape_run now reads an
image directly and takes --loop-stack / --retest.

hardware/rot8.v: the 8 bit / 64 cell machine -- 3 bit opcodes from a byte
addressed memory read as a 16 bit window, a 6 bit dp with free wrap, the loop
stack bracket jump, blocking input, halt on ip == length, and a step counter that
counts instructions rather than cycles.  hardware/tb_rot8.v loads a --hex image
and prints the OUT stream in tape_run format.

Verified with Icarus Verilog 14 (the RTL against tape_run --loop-stack --retest):
  hello        577 instructions  417 steps  10 outs
  term         16414            17643      11 (fed "lhi")
  calc         51378           166741      19 (fed "12 34 + .": prints the prompt,
                                                046 and the next prompt)
  flagship     43676           100142      93
Every OUT stream identical.  ctest -R rtl_sim runs that comparison from an 8 bit
build (11 tests in the default build now, where the RTL test self-skips because
the RTL is the 8 bit machine).

Two traps worth remembering: Icarus passes plusargs through as raw bytes, so an
absolute +HEX path containing non-ASCII (this checkout is under a Chinese
directory name) arrives mangled, $readmemh silently leaves the memory empty and
the machine obediently runs LEN steps of opcode 0 printing nothing -- run vvp
from the directory holding the hex with a relative name.  And in_ready must not
be qualified with !in_valid or the input handshake deadlocks.
2026-11-20 16:25:54 +08:00

142 lines
4.3 KiB
Verilog

// Testbench for rot8.v: run one packed image and print what the machine printed,
// in the same shape as `r8forge_tape_run` so the two can be diffed.
//
// iverilog -o rot8_tb hardware/rot8.v hardware/tb_rot8.v
// vvp rot8_tb +HEX=hello.hex +LEN=727
//
// The hex file comes from `r8forge_tape_pack hello.rot8 -o hello.r8t --hex
// hello.hex` (the body alone, one byte per line) and LEN from the comment on its
// first line.
//
// What it is for: the OUT stream and the step count have to match
// r8forge_tape_run hello.r8t --loop-stack --retest
// which is the combination the board implements. That one comparison validates
// the RTL, the packer and the bracket strategy at the same time.
//
// Not run yet: the development machine has no Verilog simulator (no iverilog, no
// verilator). See hardware/README.md.
`timescale 1ns/1ps
`default_nettype none
module tb_rot8;
parameter integer MEMW = 16; // program memory address bits
parameter integer MAX_OUT = 4096;
reg clk = 0;
reg rst_n = 0;
reg run = 1;
reg step = 0;
reg in_valid = 0;
reg [7:0] in_data = 0;
wire [MEMW-1:0] prog_addr0, prog_addr1;
wire [7:0] prog_data0, prog_data1;
wire [MEMW-1:0] prog_len;
wire out_valid;
wire [7:0] out_data;
wire in_ready;
wire [MEMW-1:0] ip;
wire [5:0] dp;
wire [31:0] steps;
wire halted;
reg [7:0] mem [0:(1<<MEMW)-1];
reg [MEMW-1:0] length;
integer outs [0:MAX_OUT-1];
integer n_out = 0;
integer cycles = 0;
integer stalls = 0;
integer i;
reg [1023:0] hex_path;
reg [1023:0] in_path;
integer in_fd = 0;
reg in_eof = 0;
integer next_char;
assign prog_data0 = mem[prog_addr0];
assign prog_data1 = mem[prog_addr1];
assign prog_len = length;
// Input: characters from +INFILE, one per accepted ','. When the file runs out
// the machine is fed zeros, which is exactly what the interpreters do when
// their scripted input is exhausted (EOF reads as 0). Without +INFILE,
// in_valid stays low, so a tape that reads stops on the cycle cap and says so
// instead of hanging the simulator.
task take_char;
begin
next_char = $fgetc(in_fd);
if (next_char < 0) begin
in_eof <= 1'b1;
in_data <= 8'd0;
end else begin
in_data <= next_char[7:0];
end
end
endtask
rot8 #(.WIDTH(8), .RING(64), .IPW(MEMW), .STACKW(4)) dut (
.clk(clk), .rst_n(rst_n), .run(run), .step(step),
.prog_addr0(prog_addr0), .prog_addr1(prog_addr1),
.prog_data0(prog_data0), .prog_data1(prog_data1),
.prog_len(prog_len),
.in_valid(in_valid), .in_data(in_data), .in_ready(in_ready),
.out_valid(out_valid), .out_data(out_data),
.ip(ip), .dp(dp), .steps(steps), .halted(halted));
// 100 MHz: two cycles per instruction, so the cycle count is about twice the
// step count. A real board's clock is unrelated to the semantics.
always #5 clk = ~clk;
initial begin
if (!$value$plusargs("HEX=%s", hex_path)) begin
$display("tb_rot8: pass +HEX=<file>");
$finish;
end
if (!$value$plusargs("LEN=%d", length)) begin
$display("tb_rot8: pass +LEN=<instruction count>");
$finish;
end
for (i = 0; i < (1<<MEMW); i = i + 1)
mem[i] = 8'h00;
$readmemh(hex_path, mem);
if ($value$plusargs("INFILE=%s", in_path))
in_fd = $fopen(in_path, "r");
#20 rst_n = 1;
if (in_fd != 0) begin
in_valid = 1'b1;
take_char;
end
// A tape that reads ',' with no input at all stays in in_ready; the cycle cap
// turns that into a report instead of a hang.
while (!halted && cycles < 100000000) begin
@(posedge clk);
cycles = cycles + 1;
if (in_ready && !in_valid)
stalls = stalls + 1;
if (in_ready && in_valid && in_fd != 0 && !in_eof)
take_char; // the machine took this byte: fetch the next one
if (out_valid && n_out < MAX_OUT) begin
outs[n_out] = out_data;
n_out = n_out + 1;
end
end
$write("out");
for (i = 0; i < n_out; i = i + 1)
$write(" %0d", outs[i]);
if (halted)
$display(" (%0d steps, %0d cycles, %0d stalled on input)", steps, cycles,
stalls);
else
$display(" (no halt after %0d cycles: ip %0d dp %0d, %0d input stalls)",
cycles, ip, dp, stalls);
$finish;
end
endmodule
`default_nettype wire