Files

355 lines
12 KiB
Lua

-- harness.lua -- the shared debugger-assisted COFF loader harness.
--
-- Boots the firmware with VT1200_SKIP_LEVEL1=1 (the documented divergence) to
-- the OS, then at frame LOADER_AT pokes the loader payload at bit 0x01880000,
-- the app's GSPLNK COFF at LOADER_BUF (default bit 0x01900000) and the loader
-- descriptor at 0x01882C00, and sets PC = 0x01880000. No network, no rdebug:
-- this is the debugger-assisted milestone. The loader copies the COFF sections
-- to their linked bit addresses and calls
-- create_process(entry, "LOADER", 0x6000, 1, 0); this harness only pokes the
-- input and reads the result, it never writes the app's code.
--
-- A test is configuration plus hooks:
--
-- local H = dofile(<dir> .. "/harness.lua")
-- H.config{ tablet = "SMOKE" }
-- H.sequence(3100, 20, { { ":lk401:K26", "A" } })
-- H.result_dump(function() print(...) end)
-- H.run()
--
-- Env (the tests/*.sh contract): LOADER_BIN, LOADER_COFF, LOADER_BUF,
-- LOADER_AT, LOADER_END, LOADER_OUT, LOADER_SNAP, LOADER_VERBOSE, and the
-- DIAG_LOOPS/EVENTS/LAST/FOCUS/REV/QUIT/TICK bit addresses (a missing one
-- prints -1).
--
-- The exit is the fixed LOADER_END frame, never an early completion: the tests
-- read the snapshot at that frame (loader_frame<LOADER_END>.png).
local H = {}
local function hex(v, w) return string.format("%0" .. (w or 8) .. "X", v) end
local machine = manager.machine
local cpu = machine.devices[':maincpu']
local dbg = machine.debugger
local prog = cpu.spaces['program']
H.machine, H.cpu, H.dbg, H.prog, H.hex = machine, cpu, dbg, prog, hex
local LOADER_BASE = 0x01880000
local DESC = 0x01882C00
local RESULT = 0x01882D00
local cfg = {
bin = os.getenv("LOADER_BIN") or "dwt/loader/build/loader.bin",
coff = os.getenv("LOADER_COFF") or "dwt/loader/build/marker.coff",
buf = tonumber(os.getenv("LOADER_BUF") or "0x01900000"),
at = tonumber(os.getenv("LOADER_AT") or "2500"),
endf = tonumber(os.getenv("LOADER_END") or "2700"),
out = os.getenv("LOADER_OUT") or "dwt/loader/evidence",
snap = os.getenv("LOADER_SNAP") == "1",
verbose = os.getenv("LOADER_VERBOSE") == "1",
}
local diag = {
loops = tonumber(os.getenv("DIAG_LOOPS") or "0") or 0,
events = tonumber(os.getenv("DIAG_EVENTS") or "0") or 0,
last = tonumber(os.getenv("DIAG_LAST") or "0") or 0,
focus = tonumber(os.getenv("DIAG_FOCUS") or "0") or 0,
rev = tonumber(os.getenv("DIAG_REV") or "0") or 0,
quit = tonumber(os.getenv("DIAG_QUIT") or "0") or 0,
tick = tonumber(os.getenv("DIAG_TICK") or "0") or 0,
}
local function slurp(p)
local f, err = io.open(p, "rb")
if not f then error("cannot open " .. p .. ": " .. tostring(err)) end
local s = f:read("*a")
f:close()
return s
end
local function u16(s, o) return s:byte(o + 1) + s:byte(o + 2) * 256 end
local function u32(s, o)
return s:byte(o + 1) + s:byte(o + 2) * 256
+ s:byte(o + 3) * 65536 + s:byte(o + 4) * 16777216
end
local function parse_coff(d)
local c = { data = d, sections = {} }
c.magic = u16(d, 0)
c.nscns = u16(d, 2)
c.opthdr = u16(d, 16)
if c.opthdr > 0 then
c.optmagic = u16(d, 20)
c.entry = u32(d, 20 + 16)
c.textstart = u32(d, 20 + 20)
c.datastart = u32(d, 20 + 24)
end
local base = 20 + c.opthdr
for i = 0, c.nscns - 1 do
local o = base + i * 40
c.sections[#c.sections + 1] = {
name = d:sub(o + 1, o + 8):gsub("%z", ""),
paddr = u32(d, o + 8),
size = u32(d, o + 16), -- bits
scnptr = u32(d, o + 20),
flags = u32(d, o + 36),
}
end
return c
end
local function poke_bytes(bitaddr, data)
local n = math.floor((#data + 1) / 2)
for i = 0, n - 1 do
local lo = data:byte(i * 2 + 1) or 0
local hi = data:byte(i * 2 + 2) or 0
prog:write_u16(bitaddr + i * 16, lo + hi * 256)
end
return n
end
local function verify_bytes(bitaddr, data)
local n = math.floor((#data + 1) / 2)
local bad = 0
for i = 0, n - 1 do
local lo = data:byte(i * 2 + 1) or 0
local hi = data:byte(i * 2 + 2) or 0
if prog:read_u16(bitaddr + i * 16) ~= lo + hi * 256 then
bad = bad + 1
end
end
return n, bad
end
local function w32(a, v) prog:write_u32(a, v) end
local function r32(a)
local ok, v = pcall(function() return prog:read_u32(a) end)
if ok then return v end
return 0xDEADBEEF
end
H.r32 = r32
local STATUS = {
"OK", "bad descriptor", "truncated COFF / section headers",
"bad COFF magic", "section size not whole words", "target outside RAM",
"target overlaps loader page or COFF buffer",
"relocation records present (unsupported)",
"target not in a free-list block", "no entry point",
}
local function status_name(v) return STATUS[v + 1] or ("error " .. tostring(v)) end
local loader, coff, app
local function prepare()
loader = slurp(cfg.bin)
coff = slurp(cfg.coff)
app = parse_coff(coff)
print(string.format("LOADER: payload %s (%d B) -> bit %s", cfg.bin, #loader, hex(LOADER_BASE)))
print(string.format("LOADER: COFF %s (%d B) -> bit %s", cfg.coff, #coff, hex(cfg.buf)))
print(string.format("LOADER: file magic=%04X nscns=%d opthdr=%d optmagic=%s entry=%s textstart=%s",
app.magic, app.nscns, app.opthdr,
app.optmagic and string.format("%04X", app.optmagic) or "none",
hex(app.entry or 0), hex(app.textstart or 0)))
for _, s in ipairs(app.sections) do
print(string.format("LOADER: sec %-8s paddr=%s size=%d bits (%d B) scnptr=%#x flags=%#x",
s.name, hex(s.paddr), s.size, math.floor(s.size / 8), s.scnptr, s.flags))
end
end
local function dump_result()
local st = r32(RESULT + 0x000)
print(string.format(
"LOADER: result status=%d (%s) entry=%s text=%s/%d bits data=%s/%d bits bss=%s/%d bits relocs=%d pcb=%s nscns=%d len=%d",
st, status_name(st), hex(r32(RESULT + 0x020)),
hex(r32(RESULT + 0x040)), r32(RESULT + 0x060),
hex(r32(RESULT + 0x080)), r32(RESULT + 0x0A0),
hex(r32(RESULT + 0x0C0)), r32(RESULT + 0x0E0),
r32(RESULT + 0x100), hex(r32(RESULT + 0x120)),
r32(RESULT + 0x140), r32(RESULT + 0x160)))
end
local function cell(addr) return addr ~= 0 and r32(addr) or -1 end
local function dump_diag()
local focus = diag.focus ~= 0 and string.format("%08X", r32(diag.focus)) or "-1"
print(string.format("DIAG: loops=%d events=%d last=%d focus=%s rev=%d quit=%d",
cell(diag.loops), cell(diag.events), cell(diag.last), focus,
cell(diag.rev), cell(diag.quit)))
print(string.format("DIAG: tick=%d quit=%d", cell(diag.tick), cell(diag.quit)))
end
local events = {}
local frame_hooks = {}
local result_hooks = {}
local done_hooks = {}
local tableted = false
local function field(tag, name)
local port = machine.ioport.ports[tag]
if not port then error("no input port " .. tag) end
local f = port.fields[name]
if not f then error("no field " .. name .. " on " .. tag) end
return f
end
-- Schedule one input event at `frame`, then print `message` (if any).
function H.key(frame, tag, name, value, message)
events[#events + 1] = { frame = frame, field = field(tag, name), value = value, message = message }
end
-- Schedule a log line at a frame.
function H.message(frame, text)
events[#events + 1] = { frame = frame, message = text }
end
-- Schedule a press/release pair for each {tag, field} entry, `step` frames
-- apart, half a step between the press and the release.
function H.sequence(first, step, keys)
local half = math.floor(step / 2)
for i, k in ipairs(keys) do
local f = first + (i - 1) * step
H.key(f, k[1], k[2], 1)
H.key(f + half, k[1], k[2], 0)
end
end
function H.config(opts)
for k, v in pairs(opts or {}) do cfg[k] = v end
if cfg.tablet and not tableted then
tableted = true
local label = type(cfg.tablet) == "string" and cfg.tablet or "LOADER"
H.key(2900, ":tablet:TABLET_X", "Tablet X", 700)
H.key(2900, ":tablet:TABLET_Y", "Tablet Y", 500, label .. ": tablet move")
H.key(3000, ":tablet:TABLET_BTN", "P1 Button 1", 1, label .. ": click down")
H.key(3020, ":tablet:TABLET_BTN", "P1 Button 1", 0, label .. ": click up")
end
end
function H.on_frame(fn) frame_hooks[#frame_hooks + 1] = fn end
function H.result_dump(fn) result_hooks[#result_hooks + 1] = fn end
function H.on_done(fn) done_hooks[#done_hooks + 1] = fn end
local frames = 0
local injected = false
local done = false
local function inject()
-- 1. loader itself
poke_bytes(LOADER_BASE, loader)
local n, bad = verify_bytes(LOADER_BASE, loader)
print(string.format("LOADER: loader poked %d words, readback %d bad at %s",
n, bad, hex(LOADER_BASE)))
-- 2. COFF image
poke_bytes(cfg.buf, coff)
n, bad = verify_bytes(cfg.buf, coff)
print(string.format("LOADER: COFF poked %d words, readback %d bad at %s",
n, bad, hex(cfg.buf)))
-- 3. pre-fill every .bss section with A5A5, so a loaded zero is meaningful
for _, s in ipairs(app.sections) do
if s.flags & 0x80 ~= 0 then
for i = 0, math.floor(s.size / 16) - 1 do
prog:write_u16(s.paddr + i * 16, 0xA5A5)
end
print(string.format("LOADER: pre-filled .bss %s..%s with A5A5",
hex(s.paddr), hex(s.paddr + s.size)))
end
end
-- 4. descriptor: magic "LD" "R1", buf, len, mode=0 (debug resume)
w32(DESC + 0x00, 0)
prog:write_u16(DESC + 0x00, 0x4C44)
prog:write_u16(DESC + 0x10, 0x5231)
w32(DESC + 0x20, cfg.buf)
w32(DESC + 0x40, #coff)
w32(DESC + 0x60, 0)
print(string.format("LOADER: descriptor @%s magic=%04X/%04X buf=%s len=%d mode=%d",
hex(DESC), prog:read_u16(DESC + 0x00), prog:read_u16(DESC + 0x10),
hex(r32(DESC + 0x20)), r32(DESC + 0x40), r32(DESC + 0x60)))
-- 5. enter the loader. A8=0 selects the fixed descriptor; mode 0 restores
-- the interrupted state and resumes at LD_ORIG_PC, so the caller yields
-- and the scheduler can run the child.
local orig_pc = cpu.state['PC'].value
w32(0x01882A20, orig_pc) -- LD_ORIG_PC
print(string.format("LOADER: will resume at %s after create_process", hex(orig_pc)))
cpu.state['A8'].value = 0
cpu.state['PC'].value = LOADER_BASE
injected = true
print(string.format("LOADER: frame %d: entered loader at %s (caller SP=%s)",
frames, hex(LOADER_BASE), hex(cpu.state['SP'].value)))
end
local function inspect()
dump_result()
-- Verify the placement from RAM: .text/.data must equal the file bytes.
for _, s in ipairs(app.sections) do
if s.scnptr ~= 0 and s.size > 0 then
local nb = math.floor(s.size / 8)
local bytes = coff:sub(s.scnptr + 1, s.scnptr + nb)
local _, bad = verify_bytes(s.paddr, bytes)
print(string.format("LOADER: placed %s at %s: %d bytes, %d differing",
s.name, hex(s.paddr), nb, bad))
end
end
for _, fn in ipairs(result_hooks) do fn() end
dump_diag()
print(string.format("LOADER: PC at inspection = %s", hex(cpu.state['PC'].value)))
end
local function snapshot()
if not cfg.snap then return end
local screen = nil
for _, s in pairs(machine.screens) do screen = s break end
if not screen then return end
local out = cfg.out .. "/loader_frame" .. frames .. ".png"
local ok, err = pcall(function() return screen:snapshot(out) end)
print(string.format("LOADER: snapshot %s ok=%s %s",
out, tostring(ok), tostring(err or "")))
end
local function fire_events()
for _, e in ipairs(events) do
if e.frame == frames then
if e.field then e.field:set_value(e.value) end
if e.message then print(e.message) end
end
end
end
function H.run()
if not dbg then
print("LOADER: debugger not enabled; pass -debug")
machine:exit()
return
end
dbg.visible_cpu = cpu
dbg.execution_state = 'run'
prepare()
emu.register_frame_done(function()
frames = frames + 1
fire_events()
for _, fn in ipairs(frame_hooks) do fn(frames) end
if frames == cfg.at and not injected then inject() end
if injected and not done and cfg.verbose and frames % 25 == 0 then dump_result() end
if frames >= cfg.endf then
if injected then
done = true
inspect()
for _, fn in ipairs(done_hooks) do fn() end
snapshot()
end
machine:exit()
end
end, "vt1200-loader")
end
return H