ed/pikuma_ps1
1
0
Fork 0
mirror of https://github.com/Ed94/pikuma_ps1.git synced 2026-08-06 15:48:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: ed/pikuma_ps1:ed3eb45b1d61f4b35c5952533765617869cb6702
Branches Tags
ed/pikuma_ps1:master ed/pikuma_ps1:hot-reload-attempt ed/pikuma_ps1:raw-pad_io-experiment ed/pikuma_ps1:lua-static-analysis ed/pikuma_ps1:gdb-atoms ed/pikuma_ps1:gdb-atoms-unreviewed-cruft ed/pikuma_ps1:annotation-experiment
...
compare: ed/pikuma_ps1:c3cf05950e480f236a835df3224b73c61ed95ef5
Branches Tags
ed/pikuma_ps1:hot-reload-attempt ed/pikuma_ps1:master ed/pikuma_ps1:raw-pad_io-experiment ed/pikuma_ps1:lua-static-analysis ed/pikuma_ps1:gdb-atoms ed/pikuma_ps1:gdb-atoms-unreviewed-cruft ed/pikuma_ps1:annotation-experiment
3 Commits
ed3eb45b1d ... c3cf05950e
Author SHA1 Message Date
ed c3cf05950e good enough for now 2026-07-21 22:29:22 -04:00
ed f6b4d9895e Adjustments to offset convention (don't want 1s based addresssing to mess with the spec defined encoding) 2026-07-21 20:52:13 -04:00
ed e70361b548 curation: first pass 2026-07-21 19:20:30 -04:00
13 changed files with 1382 additions and 1831 deletions
Expand all files Collapse all files
scripts/build_psyq.ps1
+55 -100
View File
@@ -321,7 +321,7 @@ function ps1-meta { param(
[Parameter(Mandatory=$true)][string[]]$sources,
[Parameter(Mandatory=$true)][string]$metadata,
[string]$out_root = (join-path $path_build 'gen'),
[string[]]$passes = @('--all'),
[string[]]$passes = @('--pre-link'),
[string[]]$extra_args = @()
)
$script = join-path $path_scripts 'ps1_meta.lua'
@@ -379,123 +379,78 @@ function build-gte_hello {
$link_args += $f_debug
# $link_args += $f_optimize_size
$link_modules = @(
$module_asm_crt,
$module_asm_crt,
$module_c
)
link-modules $link_modules $elf $link_args
make-binary $elf $exe
# TODO(Ed): Do both -gdb-runtime and dwarf-injection passes in a single ps1-meta call.
# Post-link: emit ONLY build/gen/gdb_tape_atoms_runtime.gdb.
# The per-source *.atoms.sourcemap.txt was already generated by the pre-link --all call,
# so we skip --atoms-source-map here to avoid re-doing the work.
# The gdb-runtime emission requires --elf (for nm-based address lookup) so it MUST happen post-link.
# Post-link: gdb-runtime + dwarf-injection in a single Lua invocation (one luajit cold start).
ps1-meta -sources $atom_sources -metadata $path_atom_metadata `
-out_root (join-path $path_build 'gen') `
-passes @('--gdb-runtime') `
-extra_args @('--elf', $elf)
# F' + G' consolidated: --dwarf-injection now emits 7 .bin blobs
# (.debug_line, .debug_aranges, .debug_rnglists, .debug_info, .debug_abbrev, .debug_str, .debug_loc) all in one pass.
ps1-meta -sources $atom_sources -metadata $path_atom_metadata `
-out_root (join-path $path_build 'gen') `
-passes @('--dwarf-injection') `
-passes @('--post-link') `
-extra_args @('--elf', $elf)
#TODO(Ed): Move the below into ps-1 meta pass to reduce syscall latency?
# F' track: post-link DWARF injection. The new Lua pass writes build/gen/<basename>.dwarf_*.bin blobs;
# we splice them into a COPY of the ELF via objcopy --update-section (works fine from PowerShell).
# The un-injected $elf + $exe are unchanged (shipping binary).
$dwarfLineBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_line.bin'
$dwarfArangesBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_aranges.bin'
$dwarfRnglistsBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_rnglists.bin'
$injectElf = Join-Path $path_build 'hello_gte.dwarf-injected.elf'
if ((Test-Path $dwarfLineBin) -and (Test-Path $dwarfArangesBin) -and (Test-Path $dwarfRnglistsBin))
# F' + G' splice: collapse 9 objcopy subprocess invocations into 3.
# - 1 call: 3x --update-section for F' (line / aranges / rnglists)
# - 1 call: 3x --update-section for G' (info / abbrev / str)
# - 1 call: 2x --add-section for G' (loc / loclists — these don't exist in the source ELF)
# - 1 call: 1x --set-section-flags (.rodata / .data enable code flag)
# = 4 objcopy calls (was 9; saved 5 spawns).
$dwarfLineBin = join-path (join-path $path_build 'gen') 'hello_gte.dwarf_line.bin'
$dwarfArangesBin = join-path (join-path $path_build 'gen') 'hello_gte.dwarf_aranges.bin'
$dwarfRnglistsBin = join-path (join-path $path_build 'gen') 'hello_gte.dwarf_rnglists.bin'
$injectElf = join-path $path_build 'hello_gte.dwarf-injected.elf'
if ((Test-Path $dwarfLineBin) -and (Test-Path $dwarfArangesBin) -and (Test-Path $dwarfRnglistsBin))
{
Write-Host "[build] DWARF-injecting $elf -> $injectElf"
Copy-Item -LiteralPath $elf -Destination $injectElf
& $Objcopy --update-section ".debug_line=$dwarfLineBin" $injectElf
$last_exit_code_error = $LASTEXITCODE -ne 0
if ($last_exit_code_error) {
Write-Warning "[build] objcopy .debug_line update failed (exit $LASTEXITCODE); removing $injectElf"
Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
return;
}
& $Objcopy --update-section ".debug_aranges=$dwarfArangesBin" $injectElf
$last_exit_code_error = $LASTEXITCODE -ne 0
if ($LASTEXITCODE -ne 0) {
Write-Warning "[build] objcopy .debug_aranges update failed (exit $LASTEXITCODE); removing $injectElf"
Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
return;
}
& $Objcopy --update-section ".debug_rnglists=$dwarfRnglistsBin" $injectElf
if ($LASTEXITCODE -ne 0) {
Write-Warning "[build] objcopy .debug_rnglists update failed (exit $LASTEXITCODE); removing $injectElf"
Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
}
else
{
# Baked atoms execute from RAM but are emitted as C data arrays, so their ELF sections lack SHF_EXECINSTR.
# GDB discards line rows for non-code sections.
# Mark only the debug-copy sections executable; the shipping ELF and PS-EXE remain byte/flag unchanged.
& $Objcopy `
--set-section-flags ".rodata=alloc,load,readonly,code,contents" `
--set-section-flags ".data=alloc,load,data,code,contents" `
$injectElf
if ($LASTEXITCODE -ne 0) {
Write-Warning "[build] objcopy atom-section flag update failed (exit $LASTEXITCODE); removing $injectElf"
Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
} else {
Write-Host "[build] DWARF-injected ELF: $injectElf"
}
}
}
Copy-Item -LiteralPath $elf -Destination $injectElf -Force
# G' (atom locals) is now part of --dwarf-injection.
# The F' splice block above already covered .debug_line / .debug_aranges / .debug_rnglists;
# we extend the same Copy-Item + objcopy chain to splice the G' 4 sections
# (.debug_info, .debug_abbrev, .debug_str via --update-section; .debug_loc via --add-section since it doesn't exist in the source ELF).
$dwarfInfoBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_info.bin'
$dwarfAbbrevBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_abbrev.bin'
$dwarfStrBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_str.bin'
$dwarfLocBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_loc.bin'
$dwarfLoclistsBin = Join-Path (Join-Path $path_build 'gen') 'hello_gte.dwarf_loclists.bin'
if ((Test-Path $dwarfInfoBin) -and (Test-Path $dwarfAbbrevBin) -and (Test-Path $dwarfStrBin) -and (Test-Path $dwarfLocBin) -and (Test-Path $dwarfLoclistsBin))
{
Write-Host "[build] G' atom-locals: splicing .debug_info/.debug_abbrev/.debug_str/.debug_loc/.debug_loclists into $injectElf"
& $Objcopy --update-section ".debug_info=$dwarfInfoBin" $injectElf
$last_exit_code_error = ($LASTEXITCODE -ne 0)
if ($last_exit_code_error) {
Write-Warning "[build] objcopy .debug_info update failed (exit $LASTEXITCODE)"
# Single objcopy call: 3x --update-section for F' (line, aranges, rnglists).
$f_args = @(
"--update-section=.debug_line=$dwarfLineBin",
"--update-section=.debug_aranges=$dwarfArangesBin",
"--update-section=.debug_rnglists=$dwarfRnglistsBin"
)
& $Objcopy @f_args $injectElf 2>&1 | Out-Null
if ($LASTEXITCODE -ne 0) {
Write-Warning "[build] objcopy F' splice failed (exit $LASTEXITCODE); removing $injectElf"
Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
return;
}
& $Objcopy --update-section ".debug_abbrev=$dwarfAbbrevBin" $injectElf
# G' 5-section splice: 3 update-section (info / abbrev / str) + 2 add-section (loc / loclists).
$dwarfInfoBin = join-path (join-path $path_build 'gen') 'hello_gte.dwarf_info.bin'
$dwarfAbbrevBin = join-path (join-path $path_build 'gen') 'hello_gte.dwarf_abbrev.bin'
$dwarfStrBin = join-path (join-path $path_build 'gen') 'hello_gte.dwarf_str.bin'
$dwarfLocBin = join-path (join-path $path_build 'gen') 'hello_gte.dwarf_loc.bin'
$dwarfLoclistsBin = join-path (join-path $path_build 'gen') 'hello_gte.dwarf_loclists.bin'
$g_args = @(
"--update-section=.debug_info=$dwarfInfoBin",
"--update-section=.debug_abbrev=$dwarfAbbrevBin",
"--update-section=.debug_str=$dwarfStrBin",
"--add-section=.debug_loc=$dwarfLocBin",
"--add-section=.debug_loclists=$dwarfLoclistsBin"
)
& $Objcopy @g_args $injectElf 2>&1 | Out-Null
if ($LASTEXITCODE -ne 0) {
Write-Warning "[build] objcopy .debug_abbrev update failed (exit $LASTEXITCODE)"
Write-Warning "[build] objcopy G' splice failed (exit $LASTEXITCODE); removing $injectElf"
Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
return;
}
& $Objcopy --update-section ".debug_str=$dwarfStrBin" $injectElf
# Baked atoms execute from RAM but are emitted as C data arrays, so their ELF sections lack SHF_EXECINSTR.
# GDB discards line rows for non-code sections. Mark only the debug-copy sections executable.
# The shipping ELF and PS-EXE remain byte/flag unchanged.
& $Objcopy `
--set-section-flags ".rodata=alloc,load,readonly,code,contents" `
--set-section-flags ".data=alloc,load,data,code,contents" `
$injectElf 2>&1 | Out-Null
if ($LASTEXITCODE -ne 0) {
Write-Warning "[build] objcopy .debug_str update failed (exit $LASTEXITCODE)"
}
else
{
# .debug_loc doesn't exist in the source ELF; --add-section creates it.
& $Objcopy --add-section ".debug_loc=$dwarfLocBin" $injectElf
if ($LASTEXITCODE -ne 0) {
Write-Warning "[build] objcopy .debug_loc add-section failed (exit $LASTEXITCODE)"
}
else
{
# .debug_loclists doesn't exist in the source ELF; --add-section creates it.
& $Objcopy --add-section ".debug_loclists=$dwarfLoclistsBin" $injectElf
if ($LASTEXITCODE -ne 0) {
Write-Warning "[build] objcopy .debug_loclists add-section failed (exit $LASTEXITCODE)"
} else {
Write-Host "[build] G' atom-locals-injected: $injectElf"
}
}
Write-Warning "[build] atom-section flag update failed (exit $LASTEXITCODE); removing $injectElf"
Remove-Item -LiteralPath $injectElf -ErrorAction SilentlyContinue
} else {
Write-Host "[build] DWARF-injected ELF: $injectElf"
}
}
}
scripts/duffle.lua
+61 -49
View File
@@ -9,7 +9,6 @@
--- - **Word-count loader** (`load_word_counts` for `WORD_COUNT(...)` metadata files).
--- - **Line lookup** (`LineIndex` returns an O(log N) `line_of(pos)` closure for source-mapping).
--- - **Domain tables** (`TAPE_ATOM_MACROS`, `GTE_PIPELINE_LATENCY`, `GP0_CMD_SIZE`, `GP0_CMD_BY_SHAPE`, `GP0_MACRO_CONTRIB`, `INSTRUCTION_LATENCY`).
--- - **Process-bootstrap helper** (`setup_package_path`replaces the 8-line `arg[0]`-resolution boilerplate duplicated across 7 entry scripts)
---
--- **Conventions**: tabs (1/level), EmmyLua annotations, no regex.
@@ -137,10 +136,8 @@ local lpeg_scan_to_target_pat = function(target) return (P(1) - P(target))^0 en
-- ════════════════════════════════════════════════════════════════════════════
-- Section 1: character classification (byte-based for hot loops)
-- ════════════════════════════════════════════════════════════════════════════
-- Two APIs:
-- is_space(c), is_alpha(c), etc. — accept a single-char STRING (legacy)
-- is_space_byte(b), is_alpha_byte(b), etc. — accept a single-byte INTEGER
-- The byte-based versions are 5-10x faster in tight loops because they avoid the string allocation per s:sub(pos, pos) call.
-- Byte-based versions (accept a single-byte INTEGER).
-- Used in all hot loops because they avoid the string allocation per s:sub(pos, pos) call.
-- Whitespace characters per C locale.
function M.is_space_byte(b) return b == BYTE_SPACE or b == BYTE_TAB or b == BYTE_NEWLINE or b == BYTE_CR or b == BYTE_VT or b == BYTE_FF end
@@ -231,6 +228,9 @@ end
-- Section 3: I/O primitives
-- ════════════════════════════════════════════════════════════════════════════
-- File contents intentionally use io.open below. LuaFileSystem handles path
-- metadata, directory iteration, the current directory, and mkdir; it does not
-- expose file-content read/write streams.
function M.read_file(path)
local f = io.open(path, "r")
if not f then error("Cannot open " .. path) end
@@ -249,7 +249,7 @@ end
-- @param path string
-- @param content string
function M.write_file_lf(path, content)
local f = io.open(path, "wb")
local f = io.open(path, "wb")
if not f then error("Cannot write " .. path) end
f:write(content); f:close()
end
@@ -274,8 +274,7 @@ end
-- Normalizes forward slashes to backslashes on Windows.
-- Used for byte-identical emit: the // Source: comment line uses the absolute path.
--
-- The CWD is memoized on first call (one lfs.currentdir() per process — ~0ms).
-- Without the cache, calling this per-source in the components pass added ~1.5s to a 30-source build.
-- The CWD is memoized on first call.
-- @param path string
-- @return string
local _absolute_path_cache = {}
@@ -288,11 +287,10 @@ function M.to_absolute_path(path)
_absolute_path_cache[path] = result
return result
end
-- lfs.currentdir() is ~0ms vs io.popen("cd") at ~50ms per call on Windows.
local cwd = lfs.currentdir()
local cwd = lfs.currentdir()
if not cwd then _absolute_path_cache[path] = path; return path end
cwd = cwd:gsub("/", "\\")
local tail = (path:gsub("/", "\\"))
local tail = (path:gsub("/", "\\"))
local result = cwd .. "\\" .. tail
_absolute_path_cache[path] = result
return result
@@ -396,15 +394,11 @@ function M.scan_to_char(s, target, start)
local target_byte = target:byte()
local pos = start
while pos <= #s do
local c = s:byte(pos)
if c == target_byte then return pos end
-- scan: ... <target found> | <skipping to target>
if c == BYTE_OPEN_PAREN then local _, a = M.read_balanced(s, "(", ")", pos); pos = a
-- scan: ... ( <balanced> ) ...
elseif c == BYTE_OPEN_BRACE then local _, a = M.read_balanced(s, "{", "}", pos); pos = a
-- scan: ... { <balanced> } ...
elseif c == BYTE_OPEN_BRACK then local _, a = M.read_balanced(s, "[", "]", pos); pos = a
-- scan: ... [ <balanced> ] ...
local c = s:byte(pos)
if c == target_byte then return pos end -- scan: ... <target found> | <skipping to target>
if c == BYTE_OPEN_PAREN then local _, a = M.read_balanced(s, "(", ")", pos); pos = a -- scan: ... ( <balanced> ) ...
elseif c == BYTE_OPEN_BRACE then local _, a = M.read_balanced(s, "{", "}", pos); pos = a -- scan: ... { <balanced> } ...
elseif c == BYTE_OPEN_BRACK then local _, a = M.read_balanced(s, "[", "]", pos); pos = a -- scan: ... [ <balanced> ] ...
else
local nx = M.skip_str_or_cmt(s, pos)
pos = (nx > pos) and nx or (pos + 1)
@@ -520,12 +514,11 @@ function M.split_top_level_commas(body)
end
-- ════════════════════════════════════════════════════════════════════════════
-- Section 4b: tokenize_body + build_body_line_index (shared, memoized)
-- Section 4: tokenize_body + build_body_line_index (shared, memoized)
-- ════════════════════════════════════════════════════════════════════════════
local _tokenize_body_cache = {}
local _tokenize_body_simple_cache = {}
local _body_line_index_cache = {}
local _tokenize_body_cache = {}
local _body_line_index_cache = {}
--- Tokenize the body inner-text into a flat list of `{tok, rel}` pairs.
--- `tok` is the trimmed token string; `rel` is the byte offset within `body`.
@@ -535,12 +528,12 @@ local _body_line_index_cache = {}
function M.tokenize_body(body)
if _tokenize_body_cache[body] ~= nil then return _tokenize_body_cache[body] end
local out = {}
local len = #body
local rel = 1
local len = #body
local rel = 1
while rel <= len do
local ws_end = M.skip_ws_and_cmt(body, rel)
if ws_end > rel then rel = ws_end end
if rel > len then break end
if rel > len then break end
local scan = rel
while scan <= len do
@@ -575,21 +568,6 @@ function M.tokenize_body(body)
return out
end
--- Tokenize the body into a flat list of trimmed string tokens (preserves comments).
--- Uses `split_top_level_commas` (which appends trailing comments to the previous token)
--- so the components pass can emit `/* Words: ... */` comments in the .macs.h output.
--- Memoized on body string (R7 lift; mirror of M.tokenize_body's memoization).
--- @param body string
--- @return string[]
function M.tokenize_body_simple(body)
if _tokenize_body_simple_cache[body] ~= nil then return _tokenize_body_simple_cache[body] end
local tokens = M.split_top_level_commas(body)
local out = {}
for i = 1, #tokens do out[i] = M.trim(tokens[i]) end
_tokenize_body_simple_cache[body] = out
return out
end
--- Build a line-index: count `\n` chars from offset 1 up to the offset; that count + 1 is the line number (1-based).
--- Memoized on the body string.
--- @param body string
@@ -597,7 +575,7 @@ end
function M.build_body_line_index(body)
if _body_line_index_cache[body] ~= nil then return _body_line_index_cache[body] end
local index = {}
local len = #body
local len = #body
local newline_count = 0
for pos = 1, len do
if pos > 1 then
@@ -619,7 +597,7 @@ end
--- @param tok string
--- @return integer|nil
function M.find_marker_call_end(tok)
local ident, after = M.read_ident(tok, 1)
local ident, after = M.read_ident(tok, 1)
if not ident then return nil end
if ident ~= "atom_label" and ident ~= "atom_offset" then return nil end
local paren_pos = M.skip_ws_and_cmt(tok, after)
@@ -628,6 +606,41 @@ function M.find_marker_call_end(tok)
return close
end
--- True iff `tok` is an atom-label or atom-offset marker call.
--- Sibling helper to M.find_marker_call_end; uses the same string constants.
--- @param tok string
--- @return boolean
function M.is_marker_token(tok)
local leading = M.read_ident(tok, 1)
return leading == "atom_label" or leading == "atom_offset"
end
--- Count words contributed by the non-marker portion of `tok` (after the marker's closing `)`).
--- Returns 0 if `tok` isn't a marker call or has no trailing content.
---
--- `count_token_words_fn` is injected by the caller rather than imported here because the
--- dependency arrow already points the other way: `passes/offsets.lua` and
--- `passes/atoms_source_map.lua` both `require("word_count_eval")` and pass its
--- `count_token_words` as the 3rd argument to this function, while `word_count_eval`
--- itself loads `duffle` via `duffle_paths.lua` (see `passes/word_count_eval.lua` near
--- the top of the file) and calls `duffle.trim` / `duffle.read_ident` /
--- `duffle.skip_ws_and_cmt` from `M.count_token_words`. Importing `word_count_eval`
--- from this module would reverse that direction and form a recursive require cycle.
--- The callback keeps the marker-syntax helpers (`find_marker_call_end`,
--- `is_marker_token`, this function) shared in `duffle` without making the foundational
--- utility depend on a pass module.
--- @param tok string
--- @param word_counts table
--- @param count_token_words_fn fun(tok: string, wc: table): integer
--- @return integer
function M.count_marker_rest(tok, word_counts, count_token_words_fn)
local marker_end = M.find_marker_call_end(tok)
if not marker_end or marker_end >= #tok then return 0 end
local rest = M.trim(tok:sub(marker_end))
if rest == "" then return 0 end
return count_token_words_fn(rest, word_counts)
end
-- ════════════════════════════════════════════════════════════════════════════
-- Section 5: load_word_counts
-- ════════════════════════════════════════════════════════════════════════════
@@ -703,13 +716,12 @@ M.TAPE_ATOM_MACROS = {
-- The check (`scripts/passes/static_analysis.lua :: check_gte_pipeline_fill`) walks each atom body,
-- counts the consecutive nop words before every `gte_cmdw_*` invocation, and reports a finding if the count is below this minimum.
--
-- PRE-FILL vs POST-FILL: this table models PRE-cmdw nops (retiring preceding C2 writes),
-- NOT the post-cmdw input-latch window.
-- PRE-FILL vs POST-FILL: this table models PRE-cmdw nops (retiring preceding C2 writes).
-- The PSX-SPX pipeline timings doc (`docs/psx-spx/docs/gtepipelinetimings.md`) measures a DIFFERENT number:
-- the smallest N nops between `cop2` and `mtc2` to a specific input register at which the write no longer affects the output.
-- For nearly all instructions, inputs latch in the first 0-4 cycles — the GTE snapshots its input register file early and works
-- from internal pipeline storage afterward. The documented total cycle count is NOT the "do not touch inputs" window;
-- the actual read window is much shorter.
-- from internal pipeline storage afterward.
-- The documented total cycle count is NOT the "do not touch inputs" window; the actual read window is much shorter.
--
-- The `gte_rtpt()` / `gte_nclip()` wrapper macros in gte.h emit the pre-cmd nops internally (asm_words(nop, nop, ...)),
-- but THOSE WRAPPERS ARE NOT USED INSIDE ATOM BODIES in this codebase.
@@ -934,7 +946,7 @@ M.INSTRUCTION_LATENCY = {
["gte_nclip"] = 8, -- alias for nclip
["gte_avsz3"] = 5,
["gte_avsz4"] = 6,
-- Legacy single-cycle store helpers (gte_stotz, gte_stsxy3 are 1 cycle)
-- Single-cycle store helpers (gte_stotz, gte_stsxy3 are 1 cycle)
["gte_stotz"] = 1,
["gte_stsxy3"] = 1,
-- High-level GTE helpers (gte_load_v0/v1/v2 do multiple lwc2s)
scripts/elf_dwarf.lua
+156 -491
View File
@@ -1,10 +1,9 @@
--- elf_dwarf.lua — ELF32 + DWARF + atoms source-map utilities for the F'' track.
---
--- elf_dwarf.lua — ELF32 + DWARF + atoms source-map utilities.
--- All ELF32 + DWARF-specific code lives here.
---
--- **What this module contains:**
--- - **Format-constant tables** (the byte-offset / opcode / size encyclopedias for ELF32, DWARF4 aranges, DWARF5 rnglists, DWARF line-program, MIPS).
--- Every constant carries a spec:` comment naming the spec section that defines it (convention established by F'').
--- Every constant carries a spec:` comment naming the spec section that defines it.
--- - **I/O helpers**: little-endian byte read/write, ELF32 section walker, nm symbol reader, source-map parser, native directory glob.
---
--- **Conventions:** tabs (1/level), EmmyLua annotations, no regex,
@@ -14,8 +13,7 @@
-- Native dependencies
-- ════════════════════════════════════════════════════════════════════════════
-- lfs is wired into package.cpath by `duffle_paths.lua` (vendored under `toolchain/lfs/lfs.dll`).
-- Required here for native directory ops (replaces the ~56ms `dir /b` subprocess with ~2ms native).
-- lfs is wired into package.cpath by `duffle_paths.lua` (vendored under `toolchain/lfs/lfs.dll`).
local lfs = require("lfs")
local M = {}
@@ -26,17 +24,17 @@ local M = {}
-- (DWARF5 §7.5.5 "Tag Encodings" + Table 7.1; gcc emits these exact values for the DWARF3-extension and DWARF5 line units.)
M.DW_TAG = {
compile_unit = 0x11,
subprogram = 0x2E,
variable = 0x34,
structure_type = 0x13,
member = 0x0D,
base_type = 0x24,
typedef = 0x2A,
pointer_type = 0x0F,
const_type = 0x26,
volatile_type = 0x27,
inlined_subroutine = 0x1D,
compile_unit = 0x11,
subprogram = 0x2E,
variable = 0x34,
structure_type = 0x13,
member = 0x0D,
base_type = 0x24,
typedef = 0x2A,
pointer_type = 0x0F,
const_type = 0x26,
volatile_type = 0x27,
inlined_subroutine = 0x1D,
-- We index the canonical gcc-emitted tags. Anything else falls through.
}
@@ -102,49 +100,51 @@ local DW_FORM_implicit_const = 0x21
--- spec: MIPS o32 ABI §"Register Usage" — 32-bit general-purpose registers
M.MIPS_BYTES_PER_WORD = 0x04
-- ----------------------------------------------------------------------------
-- ELF32 (System V ABI gABI v1.2)
-- ----------------------------------------------------------------------------
-- All offsets are 1-INDEXED (matching Lua string.sub convention),
-- expressed in hex so they map directly to the wire-format byte positions in the binary file.
-- To compute the 0-indexed file offset, subtract 1.
--
-- Example: e_shoff_offset = 0x21 means the 4-byte e_shoff field starts at
-- string.sub byte 0x21 (= 33 in 1-indexed), i.e. file offset 0x20 (= 32).
--- **Wire-offset contract:** format offsets, fixed-width reader offsets, LEB/parser cursors,
--- and section-relative values are zero-based wire offsets. Only Lua string APIs receive
--- a `+ 1` conversion at their boundary (`byte`, `sub`, and `find`).
---
--- ELF/DWARF field offsets are expressed in hex so they map directly to the
--- zero-based byte positions in the binary file.
--- spec: System V ABI gABI v1.2 §"ELF Header" (Table 1) + §"Section Header Table"
M.ELF32 = {
magic_offset = 0x01, -- 4-byte magic "\127ELF" at file offset 0x00
magic_offset = 0x00, -- 4-byte magic "\127ELF" at file offset 0x00
magic = "\127ELF",
class_offset = 0x05, -- 1-byte; 1 = ELF32, 2 = ELF64
class_offset = 0x04, -- 1-byte; 1 = ELF32, 2 = ELF64
class_elf32 = 1,
endian_offset = 0x06, -- 1-byte; 1 = little-endian, 2 = big-endian
endian_offset = 0x05, -- 1-byte; 1 = little-endian, 2 = big-endian
endian_little = 1,
header_bytes = 0x34, -- spec: gABI v1.2 §"ELF Header" — ELF32 header is 52 bytes total
e_shoff_offset = 0x21, -- 4-byte LE; section-header table file offset
e_shentsize_offset = 0x2F, -- 2-byte LE; section-header entry size in bytes
e_shnum_offset = 0x31, -- 2-byte LE; number of section headers
e_shstrndx_offset = 0x33, -- 2-byte LE; index of section-name string table
e_shoff_offset = 0x20, -- 4-byte LE; section-header table file offset
e_shentsize_offset = 0x2E, -- 2-byte LE; section-header entry size in bytes
e_shnum_offset = 0x30, -- 2-byte LE; number of section headers
e_shstrndx_offset = 0x32, -- 2-byte LE; index of section-name string table
sh_size_bytes = 0x28, -- spec: gABI v1.2 §"Section Header Table" — each entry is 40 bytes
sh_name_offset = 0x01, -- 4-byte LE; offset into .shstrtab
sh_type_offset = 0x05, -- 4-byte LE; section type (SHT_*)
sh_offset_offset = 0x11, -- 4-byte LE; section's file offset
sh_size_offset = 0x15, -- 4-byte LE; section's size in bytes
sh_name_offset = 0x00, -- 4-byte LE; offset into .shstrtab
sh_type_offset = 0x04, -- 4-byte LE; section type (SHT_*)
sh_offset_offset = 0x10, -- 4-byte LE; section's file offset
sh_size_offset = 0x14, -- 4-byte LE; section's size in bytes
dw_dwarf32_terminator = 0xFFFFFFFF, -- spec: DWARF4 spec §7.4 — 32-bit DWARF initial-length terminator
}
-- ----------------------------------------------------------------------------
-- DWARF4 .debug_aranges (per DWARF5 spec §7.4 — Address Range Table)
-- ----------------------------------------------------------------------------
-- All offsets are 1-INDEXED (matching Lua string.sub convention), in hex.
-- All offsets are zero-based wire offsets.
--- spec: DWARF5 spec §7.4 (Address Range Table) — 32-bit DWARF form
M.DWARF4_ARANGES = {
unit_length_offset = 0x01, -- 4-byte LE; length of unit body (excludes these 4 bytes)
version_offset = 0x05, -- 2-byte LE; expected = 2
cu_offset_offset = 0x07, -- 4-byte LE; CU DIE offset in .debug_info
addr_size_offset = 0x0B, -- 1-byte; expected = 4 (32-bit MIPS)
seg_size_offset = 0x0C, -- 1-byte; expected = 0
unit_length_offset = 0x00, -- 4-byte LE; length of unit body (excludes these 4 bytes)
version_offset = 0x04, -- 2-byte LE; expected = 2
cu_offset_offset = 0x06, -- 4-byte LE; CU DIE offset in .debug_info
addr_size_offset = 0x0A, -- 1-byte; expected = 4 (32-bit MIPS)
seg_size_offset = 0x0B, -- 1-byte; expected = 0
entry_size = 0x08, -- 4-byte addr + 4-byte length (per §7.4)
terminator_size = 0x08, -- 8 zero bytes (per §7.4 end-of-list marker)
version_expected = 2,
@@ -155,16 +155,16 @@ M.DWARF4_ARANGES = {
-- ----------------------------------------------------------------------------
-- DWARF5 .debug_rnglists (per DWARF5 spec §2.17 + §7.21)
-- ----------------------------------------------------------------------------
-- All offsets are 1-INDEXED (matching Lua string.sub convention), in hex.
-- All offsets are zero-based wire offsets.
--- spec: DWARF5 spec §2.17 + §7.21 (Range List Table) — 32-bit DWARF form
M.DWARF5_RNGLISTS = {
unit_length_offset = 0x01, -- 4-byte LE
version_offset = 0x05, -- 2-byte LE; expected = 5
addr_size_offset = 0x07, -- 1-byte; expected = 4
seg_size_offset = 0x08, -- 1-byte; expected = 0
offset_count_offset = 0x09, -- 4-byte LE; expected = 0
first_entry_offset = 0x0D,
unit_length_offset = 0x00, -- 4-byte LE
version_offset = 0x04, -- 2-byte LE; expected = 5
addr_size_offset = 0x06, -- 1-byte; expected = 4
seg_size_offset = 0x07, -- 1-byte; expected = 0
offset_count_offset = 0x08, -- 4-byte LE; expected = 0
first_entry_offset = 0x0C,
end_of_list = 0x00, -- spec: DWARF5 §7.7 — DW_RLE_end_of_list byte value
start_length = 0x07, -- spec: DWARF5 §7.7 — DW_RLE_start_length byte value
version_expected = 5,
@@ -208,35 +208,37 @@ M.DWARF_LINE_OPS = {
-- I/O helpers: little-endian byte read/write
-- ════════════════════════════════════════════════════════════════════════════
--- Read a 4-byte little-endian unsigned integer from `buf` at 1-indexed offset `off`.
--- Equivalent to `string.unpack("<I4", buf, off)` but avoids the table-return shape + works under LuaJIT 2.1
--- Read a 4-byte little-endian unsigned integer from `buf` at zero-based wire offset `off`.
--- Equivalent to `string.unpack("<I4", buf, off + 1)` but avoids the table-return shape + works under LuaJIT 2.1
--- (which has partial `string.unpack` coverage).
---
--- **Convention:** offsets are 1-indexed (matching Lua `string.sub`).
--- **Convention:** `off` is a zero-based wire offset; `+ 1` is applied only at the `string.byte` boundary.
---
--- **Byte weights** are written as `0x100`, `0x10000`, `0x1000000` (i.e. 2^8, 2^16, 2^24) so the LE byte positions are visually explicit:
--- byte 0 contributes its value directly; byte 1 is shifted left by 8
--- (= 0x100); byte 2 by 16 (= 0x10000); byte 3 by 24 (= 0x1000000).
--- @param buf string
--- @param off integer -- 1-indexed
--- @param off integer -- zero-based wire offset
--- @return integer
function M.read_u32_le(buf, off)
return buf:byte(off)
+ buf:byte(off + 0x01) * 0x00000100
+ buf:byte(off + 0x02) * 0x00010000
+ buf:byte(off + 0x03) * 0x01000000
local byte_off = off + 1
return buf:byte(byte_off)
+ buf:byte(byte_off + 0x01) * 0x00000100
+ buf:byte(byte_off + 0x02) * 0x00010000
+ buf:byte(byte_off + 0x03) * 0x01000000
end
--- Read a 2-byte little-endian unsigned integer from `buf` at 1-indexed offset `off`.
--- (1-indexed convention; matches `M.read_u32_le`.)
--- Read a 2-byte little-endian unsigned integer from `buf` at zero-based wire offset `off`.
--- (`off` is zero-based; `+ 1` is applied only at the `string.byte` boundary.)
--- @param buf string
--- @param off integer -- 1-indexed
--- @param off integer -- zero-based wire offset
--- @return integer
function M.read_u16_le(buf, off)
return buf:byte(off) + buf:byte(off + 0x01) * 0x00000100
local byte_off = off + 1
return buf:byte(byte_off) + buf:byte(byte_off + 0x01) * 0x00000100
end
-- Pure-Lua 5.3 LEB128 readers (no `bit` library). `2^shift` arithmetic matches the existing F' parser.
-- Pure-Lua 5.3 LEB128 readers (no `bit` library). `2^shift` arithmetic matches the existing parser.
-- Offsets are 0-based; returns (value, next_pos).
-- Track A Task 10: promoted from `local function` to M.* exports so passes/dwarf_injection.lua
-- can import them as file-scope locals per the 2nd-caller lift precedent
@@ -359,23 +361,23 @@ end
-- The caller decides whether to interpret that as a section offset.
local function read_form_value(buf, str_buf, pos, form)
if form == M.DW_FORM.addr then
return M.read_u32_le(buf, pos + 1), pos + 4
return M.read_u32_le(buf, pos), pos + 4
elseif form == M.DW_FORM.string then
local s = read_c_string_at(buf, pos)
return s, pos + #s + 1
elseif form == M.DW_FORM.strp then
-- DW_FORM_strp: 4-byte offset into .debug_str.
local strp_off = M.read_u32_le(buf, pos + 1)
local strp_off = M.read_u32_le(buf, pos)
return read_c_string_at(str_buf, strp_off), pos + 4
elseif form == M.DW_FORM.udata then return M.read_uleb128_at(buf, pos)
elseif form == M.DW_FORM.data1 then return buf:byte(pos + 1), pos + 1
elseif form == M.DW_FORM.data2 then return M.read_u16_le(buf, pos + 1), pos + 2
elseif form == M.DW_FORM.data4 then return M.read_u32_le(buf, pos + 1), pos + 4
elseif form == M.DW_FORM.ref4 then return M.read_u32_le(buf, pos + 1), pos + 4
elseif form == M.DW_FORM.data2 then return M.read_u16_le(buf, pos), pos + 2
elseif form == M.DW_FORM.data4 then return M.read_u32_le(buf, pos), pos + 4
elseif form == M.DW_FORM.ref4 then return M.read_u32_le(buf, pos), pos + 4
elseif form == M.DW_FORM.sec_offset then
-- DW_FORM_sec_offset: 4-byte offset (size depends on DWARF version;
-- on DWARF5 32-bit it's always 4 bytes).
return M.read_u32_le(buf, pos + 1), pos + 4
return M.read_u32_le(buf, pos), pos + 4
elseif form == M.DW_FORM.flag_present then
return 1, pos
elseif form == M.DW_FORM.exprloc then
@@ -387,333 +389,12 @@ local function read_form_value(buf, str_buf, pos, form)
-- The constant is declared in the abbrev; no value bytes in the DIE.
return nil, pos
elseif form == M.DW_FORM.ref_sig8 then
return M.read_u32_le(buf, pos + 1), pos + 8
return M.read_u32_le(buf, pos), pos + 8
else
return nil, pos
end
end
-- Index the .debug_info + .debug_abbrev sections of an existing ELF and collect one entry per "interesting" type DIE in the FIRST compilation unit.
-- The index supports typed-views:
-- index = {
-- by_name = { ["V4_S2"] = {kind="structure_type", die_offset, byte_size, fields={...}},
-- ["U4"] = {kind="base_type", die_offset, byte_size, encoding="unsigned"},
-- ["MipsCode"] = {kind="typedef", die_offset, target_kind=..., target_die_offset=...} },
-- by_offset = { [die_offset] = {kind, name, ...} }, -- reverse lookup
-- }
--
-- @param info string -- .debug_info section bytes
-- @param abbrev string -- .debug_abbrev section bytes
-- @param str_buf string -- .debug_str section bytes (for DW_FORM_strp name resolution)
-- @param abbrev_offset integer -- 0-based offset of the main CU's abbrev table
-- @param cu_start integer|nil -- 0-based offset of the main CU (caller-known)
-- @return table|nil, string|nil -- (index, error)
function M.index_main_cu_types(info, abbrev, str_buf, abbrev_offset, cu_start)
if not info or #info < 12 or not abbrev or not abbrev_offset then return nil, "missing input" end
str_buf = str_buf or ""
-- Index the main table at abbrev_offset.
-- The F' pass writes a trailing 0 byte after the main table; the G' pass may append additional codes (100-108) + a 0 terminator.
-- The walker may encounter a code that wasn't in the main table but exists later in the same .debug_abbrev;
-- on the first miss, walk the rest of the section to add any new abbrevs we encounter.
local abbrev_decls, err = parse_abbrev_table(abbrev, abbrev_offset)
if not abbrev_decls then return nil, err end
local abbrev_by_code = {}
for _, d in ipairs(abbrev_decls) do abbrev_by_code[d.code] = d end
-- Resolve cu_start + cu_end_excl.
local cu_end_excl
if cu_start then
local ul = M.read_u32_le(info, cu_start + 1)
if ul == 0xFFFFFFFF then return nil, "DWARF64 not supported" end
cu_end_excl = cu_start + 4 + ul
else
local pos = 0
cu_start = nil
while pos < #info do
local ul = M.read_u32_le(info, pos + 1)
if ul == 0xFFFFFFFF then break end
local unit_end = pos + 4 + ul
if unit_end > #info then break end
local unit_abbrev = M.read_u32_le(info, pos + 9)
if unit_abbrev == abbrev_offset then
cu_start = pos
cu_end_excl = unit_end
break
end
pos = unit_end
end
if not cu_start then return nil, "no CU matches abbrev_offset" end
end
-- Walk the CU's DIE tree at 0-based offset cu_start + 12.
-- Emit a flat list of type-bearing DEIs; recursion handles nested children
-- (members inside structure_type, types inside subprograms, etc.).
-- A non-type DIE's subtree is SKIPPED by walking until the matching null.
local by_name = {}
local by_offset = {}
local pos_cursor = cu_start + 12
-- Root DIE is the compile_unit; skip past it.
if pos_cursor >= cu_end_excl then return nil, "no DIE bytes" end
local root_decl_code
root_decl_code, pos_cursor = M.read_uleb128_at(info, pos_cursor)
if not root_decl_code then return nil, "truncated root DIE code" end
local root_decl = abbrev_by_code[root_decl_code]
if not root_decl then return nil, "unknown root DIE abbrev" end
-- Skip root DIE attributes.
for _, attr in ipairs(root_decl.attrs) do
local _, ne = read_form_value(info, str_buf, pos_cursor, attr.form)
if not ne then return nil, "truncated root attr" end
pos_cursor = ne
end
-- If root has no children, return an empty index.
if not root_decl.has_children or root_decl.has_children == 0 then
return { by_name = by_name, by_offset = by_offset }
end
-- Helper: skip a subtree rooted at the current DIE (pos_cursor is positioned at the first child).
-- Walks down and right until the matching null terminator is consumed.
-- Returns the new pos_cursor.
-- For DIE trees that contain only the closed type + member shapes, the depth never exceeds 2 (type DIE -> member DIE -> null).
local function skip_subtree(pos)
local depth = 1
while pos < cu_end_excl and depth > 0 do
local code = info:byte(pos + 1)
pos = pos + 1
if code == 0 then
depth = depth - 1
else
local d = abbrev_by_code[code]
if d and d.has_children ~= 0 then
depth = depth + 1
end
end
end
return pos
end
-- Pre-declare n_visited so the closure helpers can read it.
local n_visited = 0
-- Helper: read one DIE's attributes.
-- Returns (name, byte_size, encoding, type_ref, new_pos_cursor) on success; (nil, error_string) on truncation.
local function read_die_attributes(decl, pos)
local die_name = nil
local die_byte_size = nil
local die_encoding = nil
local die_type_ref = nil
for ai, attr in ipairs(decl.attrs) do
local before = pos
local val, ne = read_form_value(info, str_buf, pos, attr.form)
if not ne then
return nil, "truncated DIE attr"
end
pos = ne
if attr.name == M.DW_AT.name then
die_name = val
elseif attr.name == M.DW_AT.byte_size and (decl.tag == M.DW_TAG.base_type or decl.tag == M.DW_TAG.structure_type) then
die_byte_size = val
elseif attr.name == M.DW_AT.encoding and decl.tag == M.DW_TAG.base_type then
die_encoding = val
elseif attr.name == M.DW_AT.type then
die_type_ref = val
end
end
return die_name, die_byte_size, die_encoding, die_type_ref, pos
end
-- Helper: read structure_type members. Returns (member_fields, new_pos).
local function read_member_fields(decl, pos)
local fields = {}
while pos < cu_end_excl do
local mcode = info:byte(pos + 1)
if mcode == 0 then
pos = pos + 1
break
end
local mdecl = abbrev_by_code[mcode]
if not mdecl then return nil, "unknown member abbrev" end
pos = pos + 1
local mname, mtype_ref, moffset
for _, a in ipairs(mdecl.attrs) do
local v, ne = read_form_value(info, str_buf, pos, a.form)
if not ne then return nil, "truncated member attr" end
pos = ne
if a.name == M.DW_AT.name then mname = v
elseif a.name == M.DW_AT.type then mtype_ref = v
elseif a.name == M.DW_AT.data_member_location then moffset = v end
end
fields[#fields + 1] = { name = mname, type_offset = mtype_ref, offset = moffset }
end
return fields, pos
end
-- Top-level walker: iterate siblings.
-- For each DIE, decide whether to record (if type), descend (if structure_type with members), or skip its subtree.
while pos_cursor < cu_end_excl do
local code = info:byte(pos_cursor + 1)
if code == 0 then pos_cursor = pos_cursor + 1; break end
local decl = abbrev_by_code[code]
if not decl then
-- Lazily scan the rest of the section for the missing code.
-- The G' pass appends new abbrevs (100-108) after the main table's terminator.
-- On the first miss, walk the rest of the section.
local scan_pos = 0
while scan_pos < #abbrev do
if abbrev:byte(scan_pos + 1) == 0 then
scan_pos = scan_pos + 1
goto continue
end
local new_table, e3 = parse_abbrev_table(abbrev, scan_pos)
if not new_table then
scan_pos = scan_pos + 1
goto continue
end
for _, d in ipairs(new_table) do
if not abbrev_by_code[d.code] then
abbrev_by_code[d.code] = d
end
end
-- Find the terminator (0 byte) of this table.
local term = M.find_abbrev_table_end(abbrev, scan_pos)
if not term then break end
scan_pos = term + 1
::continue::
end
decl = abbrev_by_code[code]
if not decl then
return nil, string.format("unknown abbrev %d at offset 0x%x", code, pos_cursor)
end
end
local die_offset = pos_cursor
pos_cursor = pos_cursor + 1
local read_result = { read_die_attributes(decl, pos_cursor) }
if #read_result == 2 then
return nil, read_result[2]
end
local die_name, die_byte_size, die_encoding, die_type_ref, pos_after_attrs
= read_result[1], read_result[2], read_result[3], read_result[4], read_result[5]
n_visited = n_visited + 1
local is_type = (
decl.tag == M.DW_TAG.base_type
or decl.tag == M.DW_TAG.structure_type
or decl.tag == M.DW_TAG.typedef
or decl.tag == M.DW_TAG.pointer_type
or decl.tag == M.DW_TAG.const_type)
local member_fields = nil
pos_cursor = pos_after_attrs
if decl.tag == M.DW_TAG.structure_type and decl.has_children ~= 0 then
local f, np = read_member_fields(decl, pos_cursor)
if not f then return nil, np end
member_fields = f
pos_cursor = np
elseif decl.has_children ~= 0 then
-- Skip the subtree (e.g., DW_TAG_subprogram, DW_TAG_variable, etc.).
pos_cursor = skip_subtree(pos_cursor)
end
if is_type and die_name then
local kind
if decl.tag == M.DW_TAG.base_type then kind = "base_type"
elseif decl.tag == M.DW_TAG.structure_type then kind = "structure_type"
elseif decl.tag == M.DW_TAG.typedef then kind = "typedef"
elseif decl.tag == M.DW_TAG.pointer_type then kind = "pointer_type"
elseif decl.tag == M.DW_TAG.const_type then kind = "const_type" end
local entry = {
kind = kind,
name = die_name,
die_offset = die_offset,
byte_size = die_byte_size,
encoding = die_encoding,
type_ref = die_type_ref,
fields = member_fields,
}
by_name[die_name] = entry
by_offset[die_offset] = entry
end
end
return { by_name = by_name, by_offset = by_offset }
end
-- Resolve a chain of pointer + const + typedef + structure_type down to a canonical struct or base type.
-- The returned entry has kind, name, byte_size, and (for structure_type) fields with {name, offset, type_name, pointer_depth}.
-- Returns nil if the chain cannot be resolved (e.g., missing DIE).
-- @param index table -- M.index_main_cu_types result
-- @param start_offset integer -- CU-relative DW_FORM_ref4 offset of the start
-- @param max_depth integer -- cycle protection
-- @return table|nil -- {kind, name, byte_size, fields?, pointer_depth}
function M.resolve_type_chain(index, start_offset, max_depth)
max_depth = max_depth or 16
if not index or not start_offset then return nil end
local chain = {}
local cur_offset = start_offset
local depth = 0
while cur_offset and depth < max_depth do
local entry = index.by_offset[cur_offset]
if not entry then return nil end
chain[#chain + 1] = entry
if entry.kind == "pointer_type" then cur_offset = entry.type_ref
elseif entry.kind == "const_type" then cur_offset = entry.type_ref
elseif entry.kind == "typedef" then cur_offset = entry.type_ref
else
break
end
depth = depth + 1
end
-- Compute pointer_depth = number of pointer/const wrappers.
local pointer_depth = 0
for _, e in ipairs(chain) do
if e.kind == "pointer_type" then pointer_depth = pointer_depth + 1 end
end
-- The last entry is the "naked" type.
local naked = chain[#chain]
if not naked then return nil end
-- If the last entry is a structure_type, resolve each field's type name
-- + pointer depth too (for `bind_args` shape expansion).
if naked.kind == "structure_type" and naked.fields then
local fields = {}
for _, f in ipairs(naked.fields) do
local field_entry = f.type_offset and index.by_offset[f.type_offset] or nil
local field_chain = {}
local d = 0
local co = f.type_offset
while co and d < 16 do
local e2 = index.by_offset[co]
if not e2 then break end
field_chain[#field_chain + 1] = e2
if e2.kind == "pointer_type" or e2.kind == "const_type" or e2.kind == "typedef" then
co = e2.type_ref
else
break
end
d = d + 1
end
local fpd = 0
for _, x in ipairs(field_chain) do if x.kind == "pointer_type" then fpd = fpd + 1 end end
fields[#fields + 1] = {
name = f.name,
offset = f.offset,
type_name = (field_chain[#field_chain] and field_chain[#field_chain].name) or "?",
pointer_depth = fpd,
}
end
return {
kind = "structure_type",
name = naked.name,
byte_size = naked.byte_size,
fields = fields,
pointer_depth = pointer_depth,
}
end
return {
kind = naked.kind,
name = naked.name,
byte_size = naked.byte_size,
encoding = naked.encoding,
pointer_depth = pointer_depth,
}
end
--- Return a 4-byte little-endian byte string for `value`.
--- Caller concatenates with `..` if composing multi-word blobs.
--- **Byte weights** written as `0x100` etc. (see `M.read_u32_le` for rationale).
@@ -741,7 +422,7 @@ end
--- Read the named sections from a post-link ELF32 by walking the ELF32 section-header table directly
--- (no subprocess; lfs only for the existence check). Returns `{[name] = bytes_or_empty_string, ...}`.
---
--- **Convention:** offsets from `M.ELF32` (1-indexed for string.sub).
--- **Convention:** ELF/DWARF offsets are zero-based wire offsets. Direct Lua string APIs add `+ 1` at the boundary.
--- Every requested name has an entry in the returned dict;
--- missing sections have an empty string (NOT nil) so callers can do `sections[".debug_x"] or ""` for the missing case.
---
@@ -783,17 +464,17 @@ function M.read_elf_sections(elf_path, section_names)
end
-- Sanity-check magic + class + endianness.
if header:sub(M.ELF32.magic_offset, M.ELF32.magic_offset + 0x03) ~= M.ELF32.magic then
if header:sub(M.ELF32.magic_offset + 1, M.ELF32.magic_offset + 0x04) ~= M.ELF32.magic then
io.stderr:write("[elf_dwarf.read_elf_sections] not an ELF file\n")
f:close()
return result
end
if header:byte(M.ELF32.class_offset) ~= M.ELF32.class_elf32 then
io.stderr:write(string.format("[elf_dwarf.read_elf_sections] not ELF32 (class=%d)\n", header:byte(M.ELF32.class_offset)))
if header:byte(M.ELF32.class_offset + 1) ~= M.ELF32.class_elf32 then
io.stderr:write(string.format("[elf_dwarf.read_elf_sections] not ELF32 (class=%d)\n", header:byte(M.ELF32.class_offset + 1)))
f:close()
return result
end
if header:byte(M.ELF32.endian_offset) ~= M.ELF32.endian_little then
if header:byte(M.ELF32.endian_offset + 1) ~= M.ELF32.endian_little then
io.stderr:write("[elf_dwarf.read_elf_sections] not little-endian; unsupported\n")
f:close()
return result
@@ -847,12 +528,9 @@ end
--- Read ELF symbol addresses by walking the `.symtab` + `.strtab` sections directly (no `nm` subprocess).
--- Returns a map `{name -> {addr, size_bytes}}` for every `code_<name>` symbol.
---
--- **Why direct parsing instead of `mipsel-none-elf-nm -S`?**
--- The `nm` subprocess costs ~50ms per spawn on Windows (cmd.exe + mipsel-none-elf-nm.exe). Parsing `.symtab` ourselves is ~0ms.
--- Same return shape, same `code_` prefix filter.
---
--- **Conventions:**
--- - ELF32 symtab entry = 16 bytes (`st_name:4 + st_value:4 + st_size:4 + st_info:1 + st_other:1 + st_shndx:2`). 1-indexed for Lua string.sub.
--- - ELF32 symtab entry = 16 bytes (`st_name:4 + st_value:4 + st_size:4 + st_info:1 + st_other:1 + st_shndx:2`); offsets within each entry are zero-based wire offsets.
--- - Direct Lua `string.byte`/`string.sub`/`string.find` boundaries receive `+ 1`.
--- - We filter on STB_GLOBAL (high nibble of st_info = 1) to match `nm`'s default (external symbols only). STB_WEAK excluded.
--- - We strip the `code_` prefix to match the previous `read_nm` output.
--- - `st_size > 0` filter excludes undefined/imported symbols.
@@ -871,31 +549,31 @@ function M.read_nm(elf_path)
end
-- Iterate the 16-byte ELF32 symtab entries.
-- Each entry (1-indexed): st_name at 1, st_value at 5, st_size at 9, st_info at 13, st_other at 14, st_shndx at 15.
-- Each entry (zero-based): st_name at 0, st_value at 4, st_size at 8, st_info at 12, st_other at 13, st_shndx at 14.
local SYM_ENTRY_BYTES = 0x10
local SYM_ST_NAME = 0x01
local SYM_ST_VALUE = 0x05
local SYM_ST_SIZE = 0x09
local SYM_ST_INFO = 0x0D
local SYM_ST_NAME = 0x00
local SYM_ST_VALUE = 0x04
local SYM_ST_SIZE = 0x08
local SYM_ST_INFO = 0x0C
local n_syms = #symtab / SYM_ENTRY_BYTES
for i = 0, n_syms - 1 do
local entry_off = i * SYM_ENTRY_BYTES + 1 -- 1-indexed
local st_info = symtab:byte(entry_off + SYM_ST_INFO - 1)
local entry_off = i * SYM_ENTRY_BYTES
local st_info = symtab:byte(entry_off + SYM_ST_INFO + 1)
-- High nibble = binding (STB_LOCAL=0, STB_GLOBAL=1, STB_WEAK=2).
-- Use math.floor(/16) instead of bit.rshift for LuaJIT 2.1 compat
-- (LuaJIT's `>>` is 5.3+, but math.floor(x/16) works on all versions).
local binding = math.floor(st_info / 16)
if binding == 0 or binding == 1 then -- STB_LOCAL or STB_GLOBAL
local st_size = M.read_u32_le(symtab, entry_off + SYM_ST_SIZE - 1)
local st_size = M.read_u32_le(symtab, entry_off + SYM_ST_SIZE)
if st_size > 0 then
local st_name_off = M.read_u32_le(symtab, entry_off + SYM_ST_NAME - 1)
local st_name_off = M.read_u32_le(symtab, entry_off + SYM_ST_NAME)
-- Extract the name from .strtab (null-terminated C string).
local name_end = strtab:find("\0", st_name_off + 1, true) or (st_name_off + 1)
local name = strtab:sub(st_name_off + 1, name_end - 1)
-- Filter: keep all symbol-table symbols (atoms emit their name as the bare `<name>` since the `code_` prefix was removed from the MipsAtom_ macro).
-- The atoms_source_map pass already filters out non-atom symbols via the source-map.txt cross-ref.
if name and #name > 0 then
local st_value = M.read_u32_le(symtab, entry_off + SYM_ST_VALUE - 1)
local st_value = M.read_u32_le(symtab, entry_off + SYM_ST_VALUE)
addrs[name] = { st_value, st_size }
end
end
@@ -963,9 +641,8 @@ function M.uleb128(n)
end
--- SLEB128 (Signed Little-Endian Base 128) encoder. Returns the byte string for the integer `n` (may be negative).
--- Algorithm differs from ULEB128 by the termination condition: stop when
--- the remaining bits can be inferred from the sign bit in the last byte's
--- 7-bit data payload.
--- Algorithm differs from ULEB128 by the termination condition:
--- stop when the remaining bits can be inferred from the sign bit in the last byte's 7-bit data payload.
--- - If `n == 0` (no more value bits) AND bit 6 of the data = 0 → positive terminator (sign bit says "zero-extend").
--- - If `n == -1` (sign-extended all-1s) AND bit 6 of the data = 1 → negative terminator (sign bit says "one-extend").
---
@@ -992,35 +669,26 @@ end
-- I/O helpers: atoms source-map + native directory glob
-- ════════════════════════════════════════════════════════════════════════════
--- Parse a FORMAT_VERSION <expected_version> `*.atoms.sourcemap.txt` file.
--- Returns `{name -> {total = N, words = {{pos, line}, ...}}}`.
--- Parse a FORMAT_VERSION <expected_version> atoms-meta file (sourcemap or provenance).
--- Shared by M.parse_source_map_file + M.parse_provenance_file.
--- The two callers differ only in how they parse WORD lines; that's `extract_word(line)`.
--- Returns the standard `{name -> {total, words}}` shape.
--- Returns `{}` on format-version mismatch (and logs to stderr).
---
--- **Wire format** (emitted by `passes/atoms_source_map.lua`):
--- ```
--- # FORMAT_VERSION <n>
--- ATOM <name> "<abs-source-path>" <total>
--- WORD <n> LINE <line> TEXT <text...>
--- ...
--- ENDATOM
--- ```
---
--- **Conventions:** the in-memory shape uses `{pos, line, text}`
--- (`atoms_source_map.lua:142`); the `.txt` file uses `WORD <n>` so the parser maps `n` → `pos` field name.
--- @param sm_path Path
--- @param expected_version integer -- expected FORMAT_VERSION line
--- @param path string
--- @param expected_version integer
--- @param extract_word fun(line: string): table|nil -- caller-supplied per-line parser
--- @return table<string, table>
function M.parse_source_map_file(sm_path, expected_version)
function M.parse_atom_records(path, expected_version, extract_word)
local out = {}
local cur_name, cur_words = nil, {}
for raw in io.lines(sm_path) do
for raw in io.lines(path) do
local line = raw
if line:match("^#") then
local ver = line:match("^# FORMAT_VERSION%s+(%d+)")
if ver and tonumber(ver) ~= expected_version then
io.stderr:write(string.format(
"[elf_dwarf.parse_source_map_file] source-map version mismatch (got %s, expected %d) in %s\n",
ver, expected_version, sm_path))
"[elf_dwarf.parse_atom_records] version mismatch (got %s, expected %d) in %s\n",
ver, expected_version, path))
return {}
end
-- skip other comments
@@ -1040,16 +708,42 @@ function M.parse_source_map_file(sm_path, expected_version)
end
cur_name, cur_words = nil, {}
elseif line:sub(1, 4) == "WORD" and cur_name then
-- WORD <n> LINE <line> TEXT <text...>
local _, n, _, src_line = line:find("WORD%s+(%d+)%s+LINE%s+(%d+)")
if n and src_line then
cur_words[#cur_words + 1] = { pos = tonumber(n), line = tonumber(src_line) }
local field = extract_word(line)
if field then
cur_words[#cur_words + 1] = field
end
end
end
return out
end
--- Parse a FORMAT_VERSION <expected_version> `*.atoms.sourcemap.txt` file.
--- Returns `{name -> {total = N, words = {{pos, line}, ...}}}`.
--- Returns `{}` on format-version mismatch (and logs to stderr).
---
--- **Wire format** (emitted by `passes/atoms_source_map.lua`):
--- ```
--- # FORMAT_VERSION <n>
--- ATOM <name> "<abs-source-path>" <total>
--- WORD <n> LINE <line> TEXT <text...>
--- ...
--- ENDATOM
--- ```
---
--- **Conventions:** the in-memory shape uses `{pos, line, text}`
--- (`atoms_source_map.lua:142`); the `.txt` file uses `WORD <n>` so the parser maps `n` → `pos` field name.
--- @param sm_path Path
--- @param expected_version integer -- expected FORMAT_VERSION line
--- @return table<string, table>
function M.parse_source_map_file(sm_path, expected_version)
return M.parse_atom_records(sm_path, expected_version, function(line)
local _, n, _, src_line = line:find("WORD%s+(%d+)%s+LINE%s+(%d+)")
if n and src_line then
return { pos = tonumber(n), line = tonumber(src_line) }
end
end)
end
--- Parse a FORMAT_VERSION <expected_version> `*.atoms.provenance.txt` file.
--- Returns `{name -> {total = N, words = {{pos, call_file, call_line, comp_name, comp_file, comp_line}, ...}}}`.
--- Returns `{}` on format-version mismatch (and logs to stderr).
@@ -1072,64 +766,35 @@ end
--- @param expected_version integer -- expected FORMAT_VERSION line
--- @return table<string, table>
function M.parse_provenance_file(prov_path, expected_version)
local out = {}
local cur_name, cur_words = nil, {}
for raw in io.lines(prov_path) do
local line = raw
if line:match("^#") then
local ver = line:match("^# FORMAT_VERSION%s+(%d+)")
if ver and tonumber(ver) ~= expected_version then
io.stderr:write(string.format(
"[elf_dwarf.parse_provenance_file] provenance version mismatch (got %s, expected %d) in %s\n",
ver, expected_version, prov_path))
return {}
end
-- skip other comments
elseif line:sub(1, 4) == "ATOM" then
-- ATOM <name> "<abs-source-path>" <total>
local _, _, name = line:find("ATOM%s+(%S+)%s+\"[^\"]*\"%s+(%d+)")
if name then
cur_name = name
cur_words = {}
out[name] = { total = 0, words = cur_words }
end
elseif line == "ENDATOM" then
if cur_name and out[cur_name] then
out[cur_name].total = #cur_words
end
cur_name, cur_words = nil, {}
elseif line:sub(1, 4) == "WORD" and cur_name then
-- Two accepted shapes:
-- WORD <n> CALL <call-file>:<call-line> RAW
-- WORD <n> CALL <call-file>:<call-line> MACRO <comp_name> "<comp-file>:<comp-line>"
local pos, call_file, call_line, comp_name, comp_file, comp_line =
line:match('WORD%s+(%d+)%s+CALL%s+(.-):(%d+)%s+MACRO%s+(%S+)%s+"([^"]*):(%d+)"')
if pos then
cur_words[#cur_words + 1] = {
pos = tonumber(pos),
call_file = call_file,
call_line = tonumber(call_line),
comp_name = comp_name,
comp_file = comp_file,
comp_line = tonumber(comp_line),
}
else
-- RAW row.
local raw_pos, raw_file, raw_line = line:match('WORD%s+(%d+)%s+CALL%s+(.-):(%d+)%s+RAW')
if raw_pos then
cur_words[#cur_words + 1] = {
pos = tonumber(raw_pos),
call_file = raw_file,
call_line = tonumber(raw_line),
comp_name = nil,
comp_file = nil,
comp_line = nil,
}
end
end
return M.parse_atom_records(prov_path, expected_version, function(line)
-- Two accepted shapes:
-- WORD <n> CALL <call-file>:<call-line> RAW
-- WORD <n> CALL <call-file>:<call-line> MACRO <comp_name> "<comp-file>:<comp-line>"
local pos, call_file, call_line, comp_name, comp_file, comp_line =
line:match('WORD%s+(%d+)%s+CALL%s+(.-):(%d+)%s+MACRO%s+(%S+)%s+"([^"]*):(%d+)"')
if pos then
return {
pos = tonumber(pos),
call_file = call_file,
call_line = tonumber(call_line),
comp_name = comp_name,
comp_file = comp_file,
comp_line = tonumber(comp_line),
}
end
end
return out
-- RAW row.
local raw_pos, raw_file, raw_line = line:match('WORD%s+(%d+)%s+CALL%s+(.-):(%d+)%s+RAW')
if raw_pos then
return {
pos = tonumber(raw_pos),
call_file = raw_file,
call_line = tonumber(raw_line),
comp_name = nil,
comp_file = nil,
comp_line = nil,
}
end
end)
end
return M
scripts/passes/annotation.lua
+4 -5
View File
@@ -148,7 +148,7 @@ end
--- @param pipe_ctx PipeCtx
--- @param findings Findings
local function check_binds_struct_exists(a, pipe_ctx, findings)
if not a.binds then return end
if not a.binds then return end
if pipe_ctx.binds_index[a.binds] then return end
findings.warnings[#findings.warnings + 1] = {
line = a.line,
@@ -164,7 +164,7 @@ end
--- @param wc table<string, integer> -- the shared word-count table (from ctx.shared.word_counts)
--- @param findings Findings
local function check_macro_word_drift(m, wc, findings)
local declared = wc[m.name]
local declared = wc[m.name]
if not declared then
findings.errors[#findings.errors + 1] = {
line = m.line,
@@ -392,8 +392,7 @@ end
--- Any source referencing an R_X that's NOT in the registry will trip the new check; a single pass-level info entry
--- (emitted only when at least one such rejection lands in this source) tells users where to look.
---
--- Track A Task 13 added the proper `enum_alias_membership` per_source rule;
--- this is the stop-gap until users migrate off raw C-ABI register names.
--- This check is a stop-gap until users migrate off raw C-ABI register names.
--- @param _src SourceFile
--- @param pipe_ctx PipeCtx
--- @param findings Findings
@@ -409,7 +408,7 @@ local function check_wave_context_migration(_src, pipe_ctx, findings)
line = 0,
msg = "wave-context removed; opt in via #define atom_reg in mips.h "
.. "(every R_<alias> that should be visible to the annotation pass "
.. "must be enum-declared with the bare atom_reg marker; see Track A Task 21)",
.. "must be enum-declared with the bare atom_reg marker)",
}
return
end
scripts/passes/atoms_source_map.lua
+78 -143
View File
@@ -36,9 +36,8 @@
---
--- Marker calls (`atom_label(...)`, `atom_offset(...)`) emit 0 `.word`s.
--- They share the same walking convention as `passes/offsets.lua :: scan_atom_body`:
--- markers do NOT advance the word-offset counter, but if a marker is bundled on the same token with a
--- trailing instruction (e.g. `atom_label(foo) load_half_u(...)`),
--- the trailing instruction's word count is added. This matches `offsets.lua :: count_marker_rest`.
--- Markers do NOT advance the word-offset counter, but if a marker is bundled on the same token with a trailing instruction
--- (e.g. `atom_label(foo) load_half_u(...)`), the trailing instruction's word count is added. This matches `offsets.lua :: count_marker_rest`.
---
--- **Conventions:** tabs (1/level), EmmyLua annotations, no regex,
--- Lua 5.3 compatible.
@@ -84,68 +83,6 @@ local OFFSET_MARKER = "atom_offset"
-- Helpers
-- ════════════════════════════════════════════════════════════════════════════
--- True iff the leading identifier of `tok` is a marker call (`atom_label` / `atom_offset`).
--- Mirrors `passes/offsets.lua :: is_marker_token` (which is file-local there).
--- @param tok string
--- @return boolean
local function is_marker_token(tok)
local leading = duffle.read_ident(tok, 1)
return leading == LABEL_MARKER or leading == OFFSET_MARKER
end
--- Count words contributed by the non-marker portion of `tok` (after the marker's closing `)`).
--- Mirrors offsets.lua:182 `count_marker_rest`.
--- Returns 0 if there's no trailing content after the marker call.
--- @param tok string
--- @param wc table
--- @return integer
local function count_marker_rest(tok, wc)
local marker_end = duffle.find_marker_call_end(tok)
if not marker_end or marker_end >= #tok then return 0 end
local rest = duffle.trim(tok:sub(marker_end))
if rest == "" then return 0 end
return count_token_words(rest, wc)
end
--- Compute per-word entries for an atom.
--- Shared between the canonical text form and the gdb-runtime form.
---
--- Returns a list of `{pos, line, text}` entries + the total word count.
--- Markers contribute 0 entries (the marker call emits 0 `.word`s).
--- @param atom table -- one entry of scan.atoms / scan.raw_atoms
--- @param src table -- SourceFile (has .scan with .line_of(), .path)
--- @param wc table -- shared.word_counts
--- @return table[], integer
local function compute_word_entries(atom, src, wc)
local entries = {}
local pos = 0
for _, t in ipairs(atom.body_tokens) do
local tok = t.tok
local rel = t.rel
local words
if is_marker_token(tok) then
words = count_marker_rest(tok, wc)
else
words = count_token_words(tok, wc)
end
if words > 0 then
-- Source line for THIS token = line containing byte offset `atom.body_off + rel`.
-- `src.scan.line_of(...)` is O(log N) via LineIndex.
local line = src.scan.line_of(atom.body_off + rel)
-- Flatten newlines + tabs in TEXT to spaces so each WORD entry fits on one physical line.
-- The gdb Python parser (or our pure-gdb parser) does line-based splits; multi-line TEXT would break it.
local text = duffle.trim(tok):gsub("[\t\r\n]+", " ")
for _ = 1, words do
entries[#entries + 1] = { pos = pos, line = line, text = text }
pos = pos + 1
end
end
end
return entries, pos
end
-- ════════════════════════════════════════════════════════════════════════════
-- Provenance emission
-- ════════════════════════════════════════════════════════════════════════════
@@ -155,7 +92,7 @@ local MAC_PREFIX = "mac_"
local MAC_PREFIX_LEN = 4
--- Strip the `mac_` prefix from a token's leading identifier.
--- Returns nil if the identifier doesn't start with `mac_`
--- Returns nil if the identifier doesn't start with `mac_`
--- (so non-component tokens like `load_half_u`, `nop2`, `gte_cmdw_*` fall through cleanly).
--- @param tok string
--- @return string|nil
@@ -168,25 +105,48 @@ local function strip_mac_prefix_from_token(tok)
return nil
end
--- Compute per-word provenance entries for an atom. Mirrors `compute_word_entries` but additionally classifies each emitted `.word` as either:
--- - `RAW` — emitted by a direct instruction token (no component provenance)
--- - `MACRO X` — emitted by a `mac_X(...)` component invocation, with the component's definition file:line resolved from `ctx.shared.components`.
---
--- Returns a list of `{pos, line, text, comp_name, comp_line, comp_path, body_line}` entries + the total word count.
--- `comp_name` is nil for RAW rows. `body_line` is the line of THIS specific word in the macro body (component source file, not the caller's source);
--- it differs from `comp_line` (= the macro signature line) for every body word whose macro-body token is on a different physical line.
--- `body_line` is `nil` for RAW rows and for component words whose component declaration could not be indexed (older pass combinations / external macros).
---
--- The per-word body-line lookup mirrors `passes/dwarf_injection.lua :: compute_invocation_body_lines`:
--- walk the component's pre-tokenized body in lockstep with `count_token_words` and attribute the source line via `src.scan.line_of(...)` to each emitted `.word`.
--- Atom labels (`atom_label(...)`) emit 0 `.word`s and are skipped to stay aligned with the macro-side word-counting contract.
--- @param atom table -- one entry of scan.atoms / scan.raw_atoms
--- @param src table -- SourceFile (has .scan with .line_of(), .path)
--- @param wc table -- shared.word_counts
--- @param comp table -- shared.components map: bare_name -> {name=, line=, path=, kind=}
--- @param comp_body_index table -- per-source component body index: bare_name -> {body_off, body_tokens, line_of}
--- Fetch the per-word body lines for a `mac_X(...)` invocation.
--- Walks the component's pre-tokenized body in lockstep with `count_token_words` and attributes each emitted `.word`
--- to a source line via `idx.line_of(...)`.
--- Atom labels (`atom_label(...)`) emit 0 `.word`s and are skipped.
--- @param bare string|nil -- the bare component name (e.g. `gte_load_tri_verts`)
--- @param comp_body_index table
--- @param wc table
--- @return table|nil -- list of source lines, 1-based by word position
local function fetch_body_lines(bare, comp_body_index, wc)
if not (bare and comp_body_index) then return nil end
local idx = comp_body_index[bare]
if not (idx and idx.body_tokens and idx.line_of) then return nil end
local lines = {}
for _, bt in ipairs(idx.body_tokens) do
local bt_tok = duffle.trim(bt.tok or "")
if bt_tok ~= "" then
local leading = duffle.read_ident(bt_tok, 1)
local bt_words
if leading == "atom_label" or leading == "atom_offset" then
bt_words = 0
else
bt_words = count_token_words(bt_tok, wc)
end
if bt_words > 0 then
local body_line = idx.line_of(idx.body_off + bt.rel)
for _ = 1, bt_words do lines[#lines + 1] = body_line end
end
end
end
return lines
end
--- Unified per-word entry walker. `mode` is "sourcemap" (3 fields) or "provenance" (8 fields including component + body-line lookup).
--- Returns (entries, total_words). Markers contribute 0 entries.
--- @param atom table
--- @param src table
--- @param wc table
--- @param mode string -- "sourcemap" | "provenance"
--- @param comp table|nil -- shared.components map (provenance only)
--- @param comp_body_index table|nil -- per-source body index (provenance only)
--- @return table[], integer
local function compute_provenance_entries(atom, src, wc, comp, comp_body_index)
local function compute_word_entries(atom, src, wc, mode, comp, comp_body_index)
local entries = {}
local pos = 0
for _, t in ipairs(atom.body_tokens) do
@@ -194,70 +154,46 @@ local function compute_provenance_entries(atom, src, wc, comp, comp_body_index)
local rel = t.rel
local words
if is_marker_token(tok) then
words = count_marker_rest(tok, wc)
if duffle.is_marker_token(tok) then
words = duffle.count_marker_rest(tok, wc, count_token_words)
else
words = count_token_words(tok, wc)
end
-- Resolve component provenance for this token (if any).
local comp_name = nil
local comp_line = nil
local comp_path = nil
local comp_kind = nil
local bare = strip_mac_prefix_from_token(tok)
if bare and comp and comp[bare] then
comp_name = bare
comp_line = comp[bare].line
comp_path = comp[bare].path
comp_kind = comp[bare].kind
end
-- Per-word body lines: lazily allocate from the indexed component body the first time we see a `mac_X(...)` call to a given component.
-- We allocate ONE full body_lines vector per (call) and consume it sequentially;
-- if a single atom calls the same component more than once, each call refetches its own vector.
-- (Today no atom calls the same `mac_X(...)` twice, but the refetch keeps the semantics correct even if that changes.)
local body_lines = nil
local function fetch_body_lines()
if not (bare and comp_body_index) then return nil end
local idx = comp_body_index[bare]
if not (idx and idx.body_tokens and idx.line_of) then return nil end
local lines = {}
for _, bt in ipairs(idx.body_tokens) do
local bt_tok = duffle.trim(bt.tok or "")
if bt_tok ~= "" then
local leading = duffle.read_ident(bt_tok, 1)
local bt_words
if leading == "atom_label" or leading == "atom_offset" then
bt_words = 0
else
bt_words = count_token_words(bt_tok, wc)
end
if bt_words > 0 then
local body_line = idx.line_of(idx.body_off + bt.rel)
for _ = 1, bt_words do lines[#lines + 1] = body_line end
end
end
-- Provenance-only: resolve component + body_lines (one fetch per token).
local comp_name, comp_line, comp_path, comp_kind
local body_lines
if mode == "provenance" then
local bare = strip_mac_prefix_from_token(tok)
if bare and comp and comp[bare] then
comp_name = bare
comp_line = comp[bare].line
comp_path = comp[bare].path
comp_kind = comp[bare].kind
end
return lines
if comp_name then body_lines = fetch_body_lines(bare, comp_body_index, wc) end
end
if words > 0 then
local line = src.scan.line_of(atom.body_off + rel)
local text = duffle.trim(tok):gsub("[\t\r\n]+", " ")
-- Fetch body_lines ONCE per token (one mac_X(...) call exhausts N body words).
if comp_name then body_lines = fetch_body_lines() end
for i = 1, words do
entries[#entries + 1] = {
pos = pos,
line = line,
text = text,
comp_name = comp_name,
comp_line = comp_line,
comp_path = comp_path,
comp_kind = comp_kind,
body_line = body_lines and body_lines[i],
}
local entry
if mode == "provenance" then
entry = {
pos = pos,
line = line,
text = text,
comp_name = comp_name,
comp_line = comp_line,
comp_path = comp_path,
comp_kind = comp_kind,
body_line = body_lines and body_lines[i],
}
else -- "sourcemap" (default)
entry = { pos = pos, line = line, text = text }
end
entries[#entries + 1] = entry
pos = pos + 1
end
end
@@ -282,7 +218,7 @@ end
local function emit_provenance_stanza(src, atom, wc, comp, comp_body_index)
local lines = {}
local rel_path = src.path:gsub("\\", "/")
local entries, total = compute_provenance_entries(atom, src, wc, comp, comp_body_index)
local entries, total = compute_word_entries(atom, src, wc, "provenance", comp, comp_body_index)
-- ATOM header line with placeholder total (patched after we know it).
lines[#lines + 1] = string.format('ATOM %s "%s" 0', atom.raw_name or atom.name, rel_path)
@@ -465,7 +401,6 @@ end
---
--- Each command is a static sequence of `printf` / `tbreak` / `if ... end` blocks.
--- The Lua pass emits N atoms' worth of lines — no runtime iteration.
--- With 7 atoms + ~200 word entries, the runtime file is ~2000 lines, all auto-generated, no human edit ever.
--- @param lines table -- output line buffer (mutated in place)
--- @param matched table -- list of atom records from `build_atom_table`
local function append_gdb_commands(lines, matched)
@@ -595,8 +530,7 @@ local function append_gdb_commands(lines, matched)
lines[#lines + 1] = ""
-- ── show_c2 ──
-- GTE data regs (COP2). pcsx-redux's gdb stub doesn't expose COP2 (only
-- 72 regs: 32 GPR + COP0 + FPR).
-- GTE data regs (COP2). pcsx-redux's gdb stub doesn't expose COP2 (only 72 regs: 32 GPR + COP0 + FPR).
-- curl http://localhost:8080/api/v1/lua/gte
-- We keep the command definition as a stub that points the user at the plugin.
lines[#lines + 1] = "define show_c2"
@@ -713,8 +647,9 @@ local M = {}
--- but invoked from many source files (every atom body that calls `mac_X(...)`).
--- The body_offset + body_tokens + line_of live with the declaration source, so a per-source index would miss invocations from other sources.
---
--- The cross-source index is keyed by the bare component name (`gte_load_tri_verts`, NOT `ac_gte_load_tri_verts`) — `strip_mac_prefix_from_token` strips the `mac_` prefix
--- from call-site identifiers and yields that exact bare name; matching it here keeps the lookup aligned with the `ctx.shared.components` map's keying convention.
--- The cross-source index is keyed by the bare component name (`gte_load_tri_verts`, NOT `ac_gte_load_tri_verts`)
--- `strip_mac_prefix_from_token` strips the `mac_` prefix from call-site identifiers and yields that exact bare name;
--- matching it here keeps the lookup aligned with the `ctx.shared.components` map's keying convention.
--- First declaration wins (subsequent redeclarations would collide; today's sources declare each component exactly once).
--- @param ctx PassCtx
--- @return table<string, table> -- {[comp_name] = {body_off, body_tokens, line_of}}
scripts/passes/components.lua
+90 -174
View File
@@ -96,16 +96,24 @@ local GEN_SUBDIR = "gen"
local M = {}
-- ════════════════════════════════════════════════════════════════════════════
-- Function-args extraction (precedes MipsAtomComp_Proc_ invocations)
-- Back-walk helpers (composed into the 2 entry points below: find_function_args_for + preceding_comment_block)
-- ════════════════════════════════════════════════════════════════════════════
-- Find the LAST occurrence of `name + "("` in `source[1..before_pos]`.
-- Returns the position of the open paren, or nil if not found.
-- @param source string
-- @param name string
-- @param before_pos integer
-- @return integer|nil
local function find_last_name_open_paren(source, name, before_pos)
--- Find the args of the function declaration that immediately precedes a `MipsAtomComp_Proc_` invocation of the given name.
--- Returns the args string (e.g., `"U4 off, U4 code, U1 r, U1 g, U1 b"`) or nil if no function declaration is found.
---
--- Convention: function form is
--- `FI_ MipsAtom ac_X(args) MipsAtomComp_Proc_(ac_X, { body })`
--- We find the LAST occurrence of `"ac_X("` before `before_pos` and extract the args from inside the parens.
--- We then verify the preceding context ends with `MipsAtom`
--- (the function-decl keyword with possible qualifiers between).
---
--- @param source string
--- @param name string
--- @param before_pos integer
--- @return string|nil
local function find_function_args_for(source, name, before_pos)
-- Find the LAST occurrence of `name + "("` in `source[1..before_pos]`.
local name_open = name .. "("
local last_idx = nil
local scan_pos = 1
@@ -117,24 +125,6 @@ local function find_last_name_open_paren(source, name, before_pos)
last_idx = found
scan_pos = found + #name_open
end
return last_idx
end
--- Find the args of the function declaration that immediately precedes a `MipsAtomComp_Proc_` invocation of the given name.
--- Returns the args string (e.g., `"U4 off, U4 code, U1 r, U1 g, U1 b"`) or nil if no function declaration is found.
---
--- Convention: function form is
--- `FI_ MipsAtom ac_X(args) MipsAtomComp_Proc_(ac_X, { body })`
--- We find the LAST occurrence of `"ac_X("` before `before_pos` and extract the args from inside the parens.
--- We then verify the preceding context ends with `MipsAtom`
--- (the function-decl keyword with possible qualifiers between).
---
--- @param source string
--- @param name string
--- @param before_pos integer
--- @return string|nil
local function find_function_args_for(source, name, before_pos)
local last_idx = find_last_name_open_paren(source, name, before_pos)
if not last_idx then return nil end
-- Verify the preceding context ends with "MipsAtom" (with possible qualifiers between).
@@ -153,100 +143,11 @@ local function find_function_args_for(source, name, before_pos)
return inner
end
-- ════════════════════════════════════════════════════════════════════════════
-- Preceding-comment-block extraction
-- ════════════════════════════════════════════════════════════════════════════
-- Skip whitespace (space/tab/newline/CR) backward from `pos`, returning the position of the first non-whitespace char.
-- @param source string
-- @param pos integer
-- @return integer
local function skip_ws_backward(source, pos)
local back = pos - 1
while back > 0 do
local ch = source:sub(back, back)
if ch == " " or ch == "\t" or ch == "\n" or ch == "\r" then
back = back - 1
else
break
end
end
return back
end
-- Find the opening `/*` for a block comment whose `*/` ends at `close_pos`.
-- Returns the position of `/`, or nil if not found.
-- @param source string
-- @param close_pos integer -- position of the closing `*` of `*/`
-- @return integer|nil
local function find_block_comment_open(source, close_pos)
local prefix = source:sub(1, close_pos - 1)
local open_at = nil
for scan = #prefix - 1, 1, -1 do
if prefix:sub(scan, scan + 1) == "/*" then
open_at = scan
break
end
end
return open_at
end
-- Walk back from `open_at` over leading spaces + tabs to include the indentation before the `/*` in the captured comment.
-- @param source string
-- @param open_at integer
-- @return integer
local function extend_left_over_indent(source, open_at)
local start = open_at
while start > 1 do
local ch = source:sub(start - 1, start - 1)
if ch == " " or ch == "\t" then
start = start - 1
else
break
end
end
return start
end
-- Walk back from `line_end` to the start of the source line (the most recent `\n` or position 1).
-- @param source string
-- @param line_end integer
-- @return integer
local function find_line_start(source, line_end)
local start = line_end
while start > 1 and source:sub(start - 1, start - 1) ~= "\n" do
start = start - 1
end
return start
end
-- (internal) Capture one `/* ... */` block comment whose closing `*/`
-- ends at `close_end_pos`. Returns (block_text, new_scan_pos) where `new_scan_pos`
-- is where to continue scanning for more comments, or nil if no block comment was found.
local function capture_block_comment(source, close_end_pos)
local open_at = find_block_comment_open(source, close_end_pos)
if not open_at then return nil end
local block_start = extend_left_over_indent(source, open_at)
return source:sub(block_start, close_end_pos), block_start
end
-- (internal) Capture one `// ...` line comment ending at `line_end_pos`.
-- Returns (comment_text, new_scan_pos) or nil if the line is not a `//` comment.
local function capture_line_comment(source, line_end_pos)
local line_start = find_line_start(source, line_end_pos)
local line = source:sub(line_start, line_end_pos)
if line:sub(1, 2) == "//" then
return line, line_start - 1
end
return nil
end
--- Find the contiguous comment block immediately preceding `pos` in `source`.
--- Returns the comment text (with the `/* */` or `//` markers preserved) or an empty string if no comment is adjacent.
---
--- Used to copy signature comments from the source declaration (`MipsAtomComp_` / `MipsAtomComp_Proc_` / function decl)
--- over to the generated `mac_X` macro, so LSP/IntelliSense displays the args doc.
---
--- @param source string
--- @param pos integer
--- @return string
@@ -254,22 +155,59 @@ local function preceding_comment_block(source, pos)
local scan_pos = pos
local pieces = {}
while true do
local non_ws = skip_ws_backward(source, scan_pos)
if non_ws == 0 then break end
-- Skip whitespace (space/tab/newline/CR) backward from `scan_pos`,
-- returning the position of the first non-whitespace char.
local non_ws = scan_pos - 1
while non_ws > 0 do
local ch = source:sub(non_ws, non_ws)
if ch == " " or ch == "\t" or ch == "\n" or ch == "\r" then
non_ws = non_ws - 1
else
break
end
end
if non_ws == 0 then break end
local is_block_close = non_ws >= 2 and source:sub(non_ws - 1, non_ws) == "*/"
local is_line_end = source:sub(non_ws, non_ws) == "\n" or source:sub(non_ws, non_ws) == "\r"
if is_block_close then
local block_text, new_scan_pos = capture_block_comment(source, non_ws)
if not block_text then break end
table.insert(pieces, 1, block_text)
scan_pos = new_scan_pos
-- Find the opening `/*` for a block comment whose `*/` ends at `non_ws`.
-- Walk back from `non_ws` over `/*` candidates.
local prefix = source:sub(1, non_ws - 1)
local open_at = nil
for scan = #prefix - 1, 1, -1 do
if prefix:sub(scan, scan + 1) == "/*" then
open_at = scan
break
end
end
if not open_at then break end
-- Walk back from `open_at` over leading spaces + tabs to include the indentation before the `/*`.
local block_start = open_at
while block_start > 1 do
local ch = source:sub(block_start - 1, block_start - 1)
if ch == " " or ch == "\t" then
block_start = block_start - 1
else
break
end
end
table.insert(pieces, 1, source:sub(block_start, non_ws))
scan_pos = block_start
elseif is_line_end then
local line_text, new_scan_pos = capture_line_comment(source, non_ws)
if not line_text then break end
table.insert(pieces, 1, line_text)
scan_pos = new_scan_pos
-- Walk back from `non_ws` to the start of the source line (the most recent `\n` or position 1).
local line_start = non_ws
while line_start > 1 and source:sub(line_start - 1, line_start - 1) ~= "\n" do
line_start = line_start - 1
end
local line = source:sub(line_start, non_ws)
if line:sub(1, 2) == "//" then
table.insert(pieces, 1, line)
scan_pos = line_start - 1
else
break
end
else
break
end
@@ -282,42 +220,6 @@ end
-- Argument-name extraction
-- ════════════════════════════════════════════════════════════════════════════
-- Walk `trimmed` backward from `pos` over trailing whitespace / asterisks / brackets,
-- returning the position of the first non-trailer character (i.e. the end of the identifier).
-- @param trimmed string
-- @param pos integer
-- @return integer
local function trim_trailer_back(trimmed, pos)
local back = pos
while back > 0 do
local ch = trimmed:sub(back, back)
if ch == " " or ch == "\t" or ch == "*" or ch == "]" or ch == "[" then
back = back - 1
else
break
end
end
return back
end
-- Walk `trimmed` backward from `pos` over identifier chars (alnum + `_`),
-- returning the position just before the identifier starts.
-- @param trimmed string
-- @param pos integer
-- @return integer
local function trim_ident_back(trimmed, pos)
local back = pos
while back > 0 do
local ch = trimmed:sub(back, back)
if duffle.is_alnum(ch) or ch == "_" then
back = back - 1
else
break
end
end
return back
end
--- Extract just the parameter NAMES from a function-args string (stripping type annotations). E.g.,
--- `"U4 off, U4 code, U1 r, U1 g, U1 b"` -> `{"off", "code", "r", "g", "b"}`
--- `"U4 *ptr"` -> `{"ptr"}`
@@ -331,9 +233,29 @@ local function extract_arg_names(args_str)
for _, tok in ipairs(tokens) do
local trimmed = duffle.trim(tok)
if trimmed ~= "" then
local ident_end = trim_trailer_back(trimmed, #trimmed)
local ident_start = trim_ident_back(trimmed, ident_end) + 1
local name = trimmed:sub(ident_start, ident_end)
-- Find the identifier at the end: walk back over trailers (whitespace + `*` + `[]`),
-- then walk back over the identifier chars (alnum + `_`).
-- Plex: inlined the 2 single-caller helpers (no 2-caller rule met).
local ident_end = #trimmed
while ident_end > 0 do
local ch = trimmed:sub(ident_end, ident_end)
if ch == " " or ch == "\t" or ch == "*" or ch == "]" or ch == "[" then
ident_end = ident_end - 1
else
break
end
end
local ident_start = ident_end
while ident_start > 0 do
local ch = trimmed:sub(ident_start, ident_start)
if duffle.is_alnum(ch) or ch == "_" then
ident_start = ident_start - 1
else
break
end
end
ident_start = ident_start + 1
local name = trimmed:sub(ident_start, ident_end)
if name ~= "" then names[#names + 1] = name end
end
end
@@ -513,13 +435,6 @@ local function split_comment_lines(s)
return out
end
--- Split an atom body by top-level commas; drop empty tokens.
--- @param body string
--- @return string[]
local function tokens_from_body(body)
return duffle.tokenize_body_simple(body)
end
--- Determine the macro signature: function-args list (function form) or variadic-ignored (bare form).
--- @param args_str string|nil
--- @return string
@@ -569,7 +484,8 @@ local function build_component_lines(c, counts)
end
end
local tokens = tokens_from_body(c.body)
local tokens = duffle.split_top_level_commas(c.body)
for i = 1, #tokens do tokens[i] = duffle.trim(tokens[i]) end
local sig = signature_from_args(c.args)
-- Direct lookup against the per-source precomputed `counts` table (built once by count_all_components).
local n = counts[c.name]
@@ -605,7 +521,7 @@ local function header_boilerplate(src)
"// Component atoms (MipsAtomComp_(ac_*)) -> macro variants (mac_*)",
"",
-- Self-contained: define WORD_COUNT if not already defined.
-- We use the same definition here so the auto-generated entries below expand
-- We use the same definition here so the auto-generated entries below expand
-- to compile-time constants whether the metadata file is included first or not.
"#ifndef WORD_COUNT",
"#define WORD_COUNT(name, count) enum { words_##name = (count) };",
@@ -616,7 +532,7 @@ end
-- Compute the output path for one source's `.macs.h` file.
-- The pre-rework convention uses the *directory* basename
-- (not the source file basename) — e.g. `code/duffle/lottes_tape.h` produces `code/duffle/gen/duffle.macs.h`.
-- (not the source file basename) e.g. `code/duffle/lottes_tape.h` produces `code/duffle/gen/duffle.macs.h`.
-- This matches what the C codebase #includes.
-- @param src SourceFile
-- @return string -- the output directory
scripts/passes/dwarf_injection.lua
+272 -317
View File
@@ -1,12 +1,12 @@
--- passes/dwarf_injection.lua — Per-atom DWARF injection for tape-atom step-debug (F' + G').
--- passes/dwarf_injection.lua — Per-atom DWARF injection for tape-atom step-debug.
---
--- Reads the post-link ELF directly (lfs + io.open; walks the ELF32 section header table to find
--- `.debug_info` + `.debug_abbrev` + `.debug_str` + `.debug_line` + `.debug_aranges` + `.debug_rnglists`),
--- APPENDS synthetic DWARF line-program sequences for every `code_<name>` atom, EXTENDS the `.debug_aranges`
--- and main-CU range tables with the atom ranges, and APPENDS a new compilation unit to `.debug_info` with
--- per-atom `DW_TAG_subprogram` + per-wave-context-reg `DW_TAG_variable` entries (so `R_PrimCursor` etc.
--- appear as atom-scoped locals in VSCode's Variables pane). Writes the new section data to
--- `<out_root>/<basename>.dwarf_*.bin` (7 blobs total) plus deterministic `<out_root>/<basename>.gdbinit` skip commands.
--- per-atom `DW_TAG_subprogram` + per-wave-context-reg `DW_TAG_variable` entries
--- (so `R_PrimCursor` etc. appear as atom-scoped locals in VSCode's Variables pane).
--- Writes the new section data to `<out_root>/<basename>.dwarf_*.bin` plus deterministic `<out_root>/<basename>.gdbinit` skip commands.
---
--- The `build_psyq.ps1` post-link hook then splices those `.bin` files into a copy of the ELF via:
--- mipsel-none-elf-objcopy --update-section .debug_info=<bin> <elf>
@@ -20,11 +20,11 @@
--- Splice step runs from PowerShell — no Lua subprocess; no cmd /c parsing issues.
--- objcopy's --update-section works fine in PowerShell even though Lua's `os.execute`/`io.popen` would mangle the `=` on Windows.)
---
--- Result: VSCode's source gutter follows per-stepi inside atom bodies (F'), AND the Variables pane shows the wave-context regs as atom-scoped locals (G').
--- Result: VSCode's source gutter follows per-stepi inside atom bodies, AND the Variables pane shows the wave-context regs as atom-scoped locals.
--- Native VSCode UX (gutter arrow + highlighted line + Run to Cursor + conditional BPs by source line + per-atom locals).
--- No VSCode plugin, no Python, no pyelftools — pure Lua + objcopy.
---
--- **Conventions:** tabs (1/level), EmmyLua annotations, no regex, Lua 5.3 compatible.
--- **Conventions:** tabs (1/level), EmmyLua annotations, Lua 5.3 compatible.
-- ════════════════════════════════════════════════════════════════════════════
-- Bootstrap
@@ -43,12 +43,17 @@ local elf_dwarf = require("elf_dwarf")
-- word-counting helper shared with passes/atoms_source_map.lua.
-- Used here to walk a component's body_tokens in lockstep with their word-count allocation
-- when we propagate per-word body lines into each invocation's `body_lines` array.
local word_count_eval = require("word_count_eval")
local word_count_eval = require("word_count_eval")
local count_token_words = word_count_eval.count_token_words
local lfs = require("lfs")
-- File-scope LEB128 aliases; the helpers are available at module-load time so no forward-reference table is needed.
-- File-scope aliases to elf_dwarf helpers; the canonical implementations live in scripts/elf_dwarf.lua.
-- (2-caller lift: these were duplicated file-locals; the canonical is in elf_dwarf.lua, used by parse_abbrev_table + read_form_value.)
local read_uleb128_at = elf_dwarf.read_uleb128_at
local read_sleb128_at = elf_dwarf.read_sleb128_at
local find_abbrev_table_end = elf_dwarf.find_abbrev_table_end
-- Note: uleb128 + sleb128 are encoders; read_uleb128_at + read_sleb128_at are decoders. Different functions.
local uleb128 = elf_dwarf.uleb128
local sleb128 = elf_dwarf.sleb128
@@ -58,7 +63,7 @@ local sleb128 = elf_dwarf.sleb128
-- DWARF line-program opcodes + range-list entry encodings (per DWARF5 spec).
-- All values lifted from `elf_dwarf.DWARF_LINE_OPS` + `elf_dwarf.DWARF5_RNGLISTS`.
-- Local aliases preserve the F' code's readability
-- Local aliases preserve the code's readability
-- (e.g. `DW_LNS_copy` reads better than `elf_dwarf.DWARF_LINE_OPS.DW_LNS_copy` in an emitter body).
local DWARF_LINE_OPS = elf_dwarf.DWARF_LINE_OPS
local DWARF5_RNGLISTS = elf_dwarf.DWARF5_RNGLISTS
@@ -109,8 +114,17 @@ local DW_LLE_end_of_list = 0x00
local DW_LLE_start_length = 0x08
local DW_OP_reg0 = 0x50 -- base reg op; regN = 0x50 + N
local DW_OP_breg0 = 0x70 -- base breg op; bregN = 0x70 + N (SLEB offset)
local DW_OP_piece = 0x93
local MIPS_LOAD_DELAY_BYTES = 0x08 -- 1 load word + 1 BD-slot word
-- DIE children-list terminator: each DIE that has children ends with a single 0 byte (DWARF5 §7.5.3).
-- This is NOT the same as DW_LLE_end_of_list despite sharing the value 0x00 — different spec sections.
local DIE_CHILDREN_TERMINATOR = 0x00
-- Field/piece byte sizes for the typed-view piece chains.
-- All Binds_* struct fields are U4 (sizeof(uint32_t) on MIPS32 = 4 bytes).
local U4_BYTE_SIZE = 4
-- DWARF3/4/5 opcodes / attributes / forms (for the .debug_info synth).
-- DW_TAG values are stable across DWARF3-5 per the standard's Table 7.1;
-- gcc emits DW_TAG_structure_type=0x13 + DW_TAG_base_type=0x24 even in DWARF5-versioned CUs, so we match those exact byte values.
@@ -171,7 +185,7 @@ local function resolve_provenance_file_index(path)
local normalized = path:gsub("\\", "/")
-- Take the last path component (the basename).
local basename = normalized:match("([^/]+)$") or normalized
local idx = PROVENANCE_BASENAME_TO_FILE_INDEX[basename]
local idx = PROVENANCE_BASENAME_TO_FILE_INDEX[basename]
if idx == nil then
error(string.format(
"[dwarf_injection] resolve_provenance_file_index: unknown provenance basename '%s' (from '%s'). "
@@ -198,7 +212,7 @@ local DW_OP_piece = 0x93 -- followed by ULEB128 byte count (per DWA
local DW_ATE_unsigned = 0x07 -- DWARF5 §7.8.1: DW_ATE_unsigned (used for U4 base type)
local DW_LANG_C99 = 0x0C -- = 12 (C99); use as a safe "C-like" placeholder
-- (DW_LANG_Mips_Assembler = 0x8001 was used in the F', but we want this CU to look like a C TU so VSCode's Variables pane treats it as code.)
-- (DW_LANG_Mips_Assembler = 0x8001 was used in the, but we want this CU to look like a C TU so VSCode's Variables pane treats it as code.)
-- R_<name> → MIPS GPR lookups go through the merged register_alias_registry
-- (collected by collect_per_source_registries from ctx.sources[*].scan.register_alias_registry).
@@ -211,7 +225,6 @@ local DW_LANG_C99 = 0x0C -- = 12 (C99); use as a safe "C-like" plac
--
-- Per rbind atom we emit 2 loclist entries (tape → GPR split) using the last field's transition as the boundary.
-- This is a conservative approximation that always reads the correct GPR value once the first load has retired (load_pc + 8).
-- A future task can refine to per-field transitions.
--
-- `tape_alias` (default: "R_TapePtr") names the wave-runtime pointer register whose value is the tape address.
-- The GPR integer comes from the merged registry; if the alias is absent, this function fails loud
@@ -239,12 +252,16 @@ local function build_debug_loclists_section(atom_table, registries)
for _, f in ipairs(fields) do
local offset = f.offset or 0
local offset_sleb = elf_dwarf.sleb128(offset)
table.insert(tape_pieces, string.char(DW_OP_breg0 + tape_reg) .. offset_sleb .. string.char(DW_OP_piece) .. uleb128(4))
-- (DW_OP_bregN, SLEB128(offset), DW_OP_piece, ULEB128(U4_BYTE_SIZE))
-- 4 = U4_BYTE_SIZE: each piece is sizeof(uint32_t) on MIPS32.
table.insert(tape_pieces, string.char(DW_OP_breg0 + tape_reg) .. offset_sleb .. string.char(DW_OP_piece) .. uleb128(U4_BYTE_SIZE))
end
local tape_expr = table.concat(tape_pieces)
local gpr_pieces = {}
for _, pair in ipairs(regs) do
table.insert(gpr_pieces, string.char(DW_OP_reg0 + pair.reg) .. string.char(DW_OP_piece) .. uleb128(4))
-- (DW_OP_regN, DW_OP_piece, ULEB128(4)) — one piece per GPR-resident field.
-- The 4 = U4_BYTE_SIZE: each piece is sizeof(uint32_t) on MIPS32.
table.insert(gpr_pieces, string.char(DW_OP_reg0 + pair.reg) .. string.char(DW_OP_piece) .. uleb128(U4_BYTE_SIZE))
end
local gpr_expr = table.concat(gpr_pieces)
parts[#parts + 1] = string.char(DW_LLE_start_length)
@@ -258,13 +275,17 @@ local function build_debug_loclists_section(atom_table, registries)
parts[#parts + 1] = string.char(DW_LLE_end_of_list)
end
end
-- Loclist unit header (DWARF5 §7.7.2):
-- unit_length(4) + version(2) + address_size(1) + segment_size(1) + offset_entry_count(4) = 12 bytes header.
-- version = 5 (DWARF5); address_size = 4 (MIPS32); segment_size = 0; offset_entry_count = 0 (we use DW_LLE_start_length, not offsets).
local LOCLIST_HEADER_SIZE = 12
local body = table.concat(parts)
local unit_length = 2 + 1 + 1 + 4 + #body
local unit_length = LOCLIST_HEADER_SIZE - 4 + #body -- -4 because unit_length excludes itself
local header = elf_dwarf.write_u32_le(unit_length)
.. elf_dwarf.write_u16_le(5)
.. string.char(4)
.. string.char(0)
.. elf_dwarf.write_u32_le(0)
.. elf_dwarf.write_u16_le(5) -- DWARF5
.. string.char(U4_BYTE_SIZE) -- address_size
.. string.char(0) -- segment_size
.. elf_dwarf.write_u32_le(0) -- offset_entry_count
return header .. body
end
@@ -273,7 +294,7 @@ end
-- @return table -- {[atom_name] = offset_in_section}
local function compute_loclists_offsets(atom_table)
local offsets = {}
local cursor = 4 + 2 + 1 + 1 + 4
local cursor = 4 + 2 + 1 + 1 + 4
for _, atom in ipairs(atom_table) do
if atom.rbind then
offsets[atom.name] = cursor
@@ -290,7 +311,7 @@ local function compute_loclists_offsets(atom_table)
end
-- Default name for the synthetic CU (so VSCode lists it as a known source).
local DEFAULT_CU_NAME = "tape_atom_locals"
local DEFAULT_CU_NAME = "tape_atom_locals"
local DEFAULT_CU_COMP_DIR = "."
-- Path templates for the .bin outputs are now in SECTION_WRITERS (see below).
@@ -316,16 +337,8 @@ local function normalize_debug_path(path)
return duffle.to_absolute_path(path):gsub("\\", "/")
end
--- Build a case-insensitive Windows path + exact component-name key.
--- @param path string
--- @param component_name string
--- @return string
local function component_skip_key(path, component_name)
return normalize_debug_path(path):lower() .. "\0" .. component_name
end
--- Consume the per-source scanner associations without naming any atom or component in production.
--- Whole atoms remain symbol-keyed; components are file-qualified internally so a source marker associates
--- Whole atoms remain symbol-keyed; components are file-qualified internally so a source marker associates
--- with its exact component definition even though GDB 12 requires function-only skip entries for the resulting synthetic inline frame.
--- @param ctx DwarfInjectionCtx
--- @return table -- {atoms = {[symbol] = association}, components = {[file|name] = association}}
@@ -343,7 +356,9 @@ local function collect_skip_over(ctx)
end
for component_name, association in pairs(scan_skip.components or {}) do
local source_path = normalize_debug_path(src.path)
skip_over.components[component_skip_key(source_path, component_name)] = {
-- component_skip_key (the lower() .. "\0" .. component_name part) inlined at this single call site
-- (no other callers remain after pass 17).
skip_over.components[source_path:lower() .. "\0" .. component_name] = {
name = component_name,
source_path = source_path,
association = association,
@@ -361,8 +376,7 @@ end
--- Aliases without `atom_reg` adjacent are absent; the absence is treated as "not debug-visible" (see build_inserted_children for the precedence chain).
---
--- When two sources register the same key, the last-writer wins (later sources override earlier).
--- Today only one source declares wave-context enums, so collisions are absent;
--- future multi-source declarations would need a name-resolution rule (left as a follow-up).
--- Today only one source declares wave-context enums, so collisions are absent.
--- @param ctx DwarfInjectionCtx
--- @return table -- {
--- register_alias_registry = {[R_Name] = AliasEntry},
@@ -660,7 +674,7 @@ end
--- (the MipsAtomComp_/MipsAtomComp_Proc_ declaration).
--- Atom labels (`atom_label(...)`) emit 0 `.word`s and are ignored (matching `passes/atoms_source_map.lua :: is_marker_token` + `count_marker_rest`).
--- @param ctx DwarfInjectionCtx
--- @param skip_over table -- collect_skip_over(ctx) result
--- @param skip_over table -- {atoms = {[symbol] = association}, components = {[file|name] = association}}
--- @return table[] -- list of {name, addr, size_bytes, words, entries, invocations, skip_over?}
local function build_atom_table(ctx, skip_over)
local basename = ctx.basename or DEFAULT_BASENAME
@@ -688,7 +702,7 @@ local function build_atom_table(ctx, skip_over)
-- Also read *.atoms.provenance.txt to extract per-component invocations.
-- Files are merged by atom name; entries carry the original {pos, call_file, call_line, comp_name, comp_file, comp_line} shape.
local prov_files = duffle.list_dir(ctx.out_root, "%.atoms.provenance%.txt$")
local prov_files = duffle.list_dir(ctx.out_root, "%.atoms.provenance%.txt$")
local prov_merged = {}
for _, prov_path in ipairs(prov_files) do
local prov = elf_dwarf.parse_provenance_file(prov_path, 1)
@@ -793,7 +807,9 @@ local function build_atom_table(ctx, skip_over)
comp_line = w.comp_line,
start_pos = w.pos,
end_pos = w.pos,
skip_over = skip_over.components[component_skip_key(w.comp_file, w.comp_name)] ~= nil,
-- component_skip_key: case-insensitive Windows path + "\0" separator + exact component-name.
-- (Inlined from `component_skip_key`; the lookup is in skip_over.components keyed by the result.)
skip_over = skip_over.components[normalize_debug_path(w.comp_file):lower() .. "\0" .. w.comp_name] ~= nil,
}
-- Capture the per-word body lines for THIS invocation, indexed by 1-based word position within the invocation.
-- body_lines[1] is the line of the first body word (= the line of the first macro-body token, NOT the comp def line).
@@ -850,7 +866,6 @@ end
-- parse_rbind_atoms consumes `scan.binds[i].fields` directly, which is populated by the scan-source pass with the typed-field record ({name, type_name, pointer_depth, offset, byte_size}).
--- Find every `load_word(R_<reg>, R_TapePtr, O_(Binds_X, FieldName))` call in the atom body and return ordered (reg_index, field_name) pairs.
---
--- Source pattern (single-line, comma-separated at top level):
--- load_word(R_PrimCursor, R_TapePtr, O_(Binds_CubeTri,PrimCursor)),
--- load_word(R_FaceCursor, R_TapePtr, O_(Binds_CubeTri,FaceCursor)),
@@ -859,49 +874,36 @@ end
--- The GPR for each `R_<reg>` is looked up in the merged register_alias_registry; aliases absent from the registry
--- (no `atom_reg` opt-in) are silently skipped — the resulting rbind record will be incomplete and the atom will fail to bind a usable piece chain.
--- This is intentional: silently falling back to a hardcoded GPR would mask the missing opt-in.
--- @param body string -- the atom body text (between { ... })
--- @param binds_name string -- expected Binds_X name (skip pairs with mismatching binds)
--- @param registries table -- merged registries from collect_per_source_registries
--- @return table[] -- list of {reg = <MIPS index>, field = <field name>}
local function parse_body_load_pairs(body, binds_name, registries)
local pairs = {}
local pos = 1
local body_len = #body
---
--- Pre-tokenized: `body_tokens` is the scan-source pass's pre-split list of top-level
--- statements (each entry is a single `load_word(...)` call or other statement).
--- Plex: prepass move — use the pre-computed data instead of re-walking the body text.
--- @param body_tokens table[] -- the atom's pre-tokenized body statements (from atom.body_tokens)
--- @param binds_name string -- expected Binds_X name (skip pairs with mismatching binds)
--- @param registries table -- merged registries from collect_per_source_registries
--- @return table[] -- list of {reg = <MIPS index>, field = <field name>}
local function parse_body_load_pairs(body_tokens, binds_name, registries)
local pairs = {}
local reg_index_by_name = (registries and registries.register_alias_registry) or {}
while pos <= body_len do
-- Find the next "load_word" identifier.
pos = duffle.skip_ws_and_cmt(body, pos)
if pos > body_len then break end
local ident, ident_end = duffle.read_ident(body, pos)
if not ident or ident ~= "load_word" then
-- Either no ident here OR a non-load_word ident (e.g. add_ui_self).
-- Either way, advance by at least 1 byte to avoid infinite loops.
-- ident_end is `pos` when no ident matches (read_ident returns nil, pos).
pos = (ident_end and ident_end > pos) and ident_end or (pos + 1)
else
-- Read the argument list.
local p_open = duffle.skip_ws_and_cmt(body, ident_end)
if body:sub(p_open, p_open) ~= "(" then
pos = p_open + 1
else
local inner, p_after = duffle.read_parens(body, p_open)
-- Split top-level commas.
local args = duffle.split_top_level_commas(inner)
-- Expected shape: (R_<reg>, R_TapePtr, O_(Binds_<X>, FieldName))
if #args >= 3 then
local reg_name = duffle.trim(args[1])
local third_arg = duffle.trim(args[3])
-- Match O_(Binds_<X>, FieldName)
local b, f = third_arg:match("^O_%((Binds_[%w_]+)%s*,%s*(.-)%s*%)$")
local alias_entry = reg_index_by_name[reg_name]
if b and b == binds_name and alias_entry and alias_entry.code then
pairs[#pairs + 1] = {
reg = alias_entry.code,
field = duffle.trim(f),
}
end
for _, t in ipairs(body_tokens or {}) do
local tok = duffle.trim(t.tok or "")
-- Match "load_word(...)" — the entire call is one body_tokens entry.
local inner = tok:match("^load_word%s*%((.*)%)$")
if inner then
local args = duffle.split_top_level_commas(inner)
-- Expected shape: (R_<reg>, R_TapePtr, O_(Binds_<X>, FieldName))
if #args >= 3 then
local reg_name = duffle.trim(args[1])
local third_arg = duffle.trim(args[3])
-- Match O_(Binds_<X>, FieldName)
local b, f = third_arg:match("^O_%((Binds_[%w_]+)%s*,%s*(.-)%s*%)$")
local alias_entry = reg_index_by_name[reg_name]
if b and b == binds_name and alias_entry and alias_entry.code then
pairs[#pairs + 1] = {
reg = alias_entry.code,
field = duffle.trim(f),
}
end
pos = p_after
end
end
end
@@ -955,13 +957,13 @@ local function parse_rbind_atoms(ctx, atom_table, registries)
end
end
-- Walk every atom_info; if `binds` is set, find the atom body + parse load_word pairs.
local body_by_atom = {}
-- Walk every atom_info; if `binds` is set, find the atom body_tokens + parse load_word pairs.
local body_tokens_by_atom = {}
for _, src in ipairs(ctx.sources or {}) do
local scan = src.scan
if scan then
for _, atom in ipairs(scan.atoms or {}) do
body_by_atom[atom.name] = atom.body
body_tokens_by_atom[atom.name] = atom.body_tokens
end
end
end
@@ -978,10 +980,10 @@ local function parse_rbind_atoms(ctx, atom_table, registries)
for atom_name, ai in pairs(ai_by_atom) do
if ai.binds then
local struct = rbind_structs[ai.binds]
local body = body_by_atom[atom_name]
if struct and body then
local pairs = parse_body_load_pairs(body, ai.binds, registries)
local struct = rbind_structs[ai.binds]
local body_toks = body_tokens_by_atom[atom_name]
if struct and body_toks then
local pairs = parse_body_load_pairs(body_toks, ai.binds, registries)
if #pairs > 0 then
rbind_atoms[atom_name] = {
binds = ai.binds,
@@ -1033,24 +1035,24 @@ local function build_dwarf_line_section(existing, atom_table)
-- Walk DWARF32 line units and retain the final unit's bounds.
-- The main C CU points at this final unit (DW_AT_stmt_list = 0x5b in today's ELF).
local unit_pos, last_pos, last_length, last_end = 1, nil, nil, nil
while unit_pos <= #existing do
if unit_pos + 3 > #existing then return existing end
local unit_length = elf_dwarf.read_u32_le(existing, unit_pos)
local unit_pos, last_pos, last_length, last_end = 0, nil, nil, nil
while unit_pos < #existing do
if unit_pos + 4 > #existing then return existing end
local unit_length = elf_dwarf.read_u32_le(existing, unit_pos)
if unit_length == elf_dwarf.ELF32.dw_dwarf32_terminator then return existing end
local unit_end = unit_pos + 3 + unit_length
if unit_end > #existing then return existing end
last_pos, last_length, last_end = unit_pos, unit_length, unit_end
unit_pos = unit_end + 1
local unit_end_excl = unit_pos + 4 + unit_length
if unit_end_excl > #existing then return existing end
last_pos, last_length, last_end = unit_pos, unit_length, unit_end_excl
unit_pos = unit_end_excl
end
if unit_pos ~= #existing + 1 or not last_pos then return existing end
if unit_pos ~= #existing or not last_pos then return existing end
local new_length = last_length + #appended
local new_length_bytes = elf_dwarf.write_u32_le(new_length)
return existing:sub(1, last_pos - 1)
return existing:sub(1, last_pos)
.. new_length_bytes
.. existing:sub(last_pos + 4, last_end)
.. existing:sub(last_pos + 5, last_end)
.. appended
end
@@ -1089,10 +1091,10 @@ local function build_dwarf_aranges_section(existing, atom_table)
-- Walk all units and emit each one (preserving existing structure).
-- For the LAST unit, replace the terminator with my entries + new term.
local result = {}
local i = 1 -- 1-indexed
local i = 0 -- zero-based wire offset
local is_last_unit = false
while i <= #existing do
while i < #existing do
-- Read this unit's length.
local ul = elf_dwarf.read_u32_le(existing, i)
if ul == elf_dwarf.ELF32.dw_dwarf32_terminator then
@@ -1101,8 +1103,8 @@ local function build_dwarf_aranges_section(existing, atom_table)
end
local unit_start = i
local unit_end = i + 3 + ul -- last byte of unit content
is_last_unit = (unit_end == #existing)
local unit_end_excl = i + 4 + ul
is_last_unit = (unit_end_excl == #existing)
if is_last_unit then
-- The old terminator is replaced by entries + a new terminator, so net section growth (and unit_length growth) is entries only.
@@ -1111,7 +1113,7 @@ local function build_dwarf_aranges_section(existing, atom_table)
local new_ul_bytes = elf_dwarf.write_u32_le(new_ul)
-- Emit everything EXCEPT the last 8 bytes (terminator).
result[#result + 1] = new_ul_bytes
.. existing:sub(i + 4, unit_end - elf_dwarf.DWARF4_ARANGES.terminator_size)
.. existing:sub(i + 5, unit_end_excl - elf_dwarf.DWARF4_ARANGES.terminator_size)
-- Append my atom entries.
for _, atom in ipairs(atom_table) do
local a = atom.addr
@@ -1122,10 +1124,10 @@ local function build_dwarf_aranges_section(existing, atom_table)
result[#result + 1] = string.rep("\0", elf_dwarf.DWARF4_ARANGES.terminator_size)
else
-- Emit this unit unchanged.
result[#result + 1] = existing:sub(unit_start, unit_end)
result[#result + 1] = existing:sub(unit_start + 1, unit_end_excl)
end
i = unit_end + 1
i = unit_end_excl
end
if not is_last_unit then
@@ -1148,12 +1150,12 @@ end
--- @param atom_table table
--- @return string
local function build_dwarf_rnglists_section(existing, atom_table)
if #existing < elf_dwarf.DWARF5_RNGLISTS.first_entry_offset or #atom_table == 0 then return existing end
if #existing <= elf_dwarf.DWARF5_RNGLISTS.first_entry_offset or #atom_table == 0 then return existing end
local unit_length = elf_dwarf.read_u32_le(existing, elf_dwarf.DWARF5_RNGLISTS.unit_length_offset)
local version = elf_dwarf.read_u16_le(existing, elf_dwarf.DWARF5_RNGLISTS.version_offset)
local address_size = existing:byte(elf_dwarf.DWARF5_RNGLISTS.addr_size_offset)
local segment_size = existing:byte(elf_dwarf.DWARF5_RNGLISTS.seg_size_offset)
local address_size = existing:byte(elf_dwarf.DWARF5_RNGLISTS.addr_size_offset + 1)
local segment_size = existing:byte(elf_dwarf.DWARF5_RNGLISTS.seg_size_offset + 1)
local offset_entry_count = elf_dwarf.read_u32_le(existing, elf_dwarf.DWARF5_RNGLISTS.offset_count_offset)
if unit_length + 4 ~= #existing
@@ -1182,19 +1184,12 @@ local function build_dwarf_rnglists_section(existing, atom_table)
end
-- ════════════════════════════════════════════════════════════════════════════
-- G' helpers: per-atom .debug_info synthesis (DW_TAG_subprogram + DW_TAG_variable)
-- Helpers: per-atom .debug_info synthesis (DW_TAG_subprogram + DW_TAG_variable)
-- ════════════════════════════════════════════════════════════════════════════
--- Build the location bytes (DW_FORM_exprloc) for a register-resident value.
--- DW_OP_reg0..reg31 occupy opcodes 0x50..0x6f. DW_OP_reg15 is 0x5f;
--- 0x90 is DW_OP_regx, not the base of the compact register opcode range.
--- @param reg_n integer -- 0..31 (MIPS register number)
--- @return string -- the exprloc byte sequence (length-prefixed)
local function reg_exprloc(reg_n)
local op = string.char(DW_OP_reg0 + reg_n)
return uleb128(#op) .. op
end
--- Build the piece-chain location bytes (DW_FORM_exprloc) for an rbind atom's bind_args.
---
--- The location expression is a sequence of (DW_OP_regN, DW_OP_piece, ULEB128(size)) tuples, one per field.
@@ -1256,107 +1251,11 @@ end
-- 4. Patch the main CU's debug_abbrev_offset to the duplicate.
-- 5. Insert our DIEs as children of the main CU (just before its root terminator).
--
-- All offsets in this section are 0-based (matching the user's "section offset 0x24" convention).
-- When reading via elf_dwarf.read_u32_le (1-indexed), call with `pos + 1`.
-- All binary coordinates in this section are zero-based wire offsets. Direct Lua string APIs add `+ 1` at the boundary.
--
-- Pure-Lua 5.3 LEB decoders (no `bit` library; `2^shift` arithmetic matches elf_dwarf.lua's
-- "math.floor(/16) instead of bit.rshift for LuaJIT 2.1 compat" comment at line 352).
--- Read a ULEB128 value starting at 0-based byte offset `pos` in `buf`.
--- Returns (value, next_pos) where `next_pos` is the 0-based offset of the byte AFTER the last byte consumed.
--- Returns (nil, pos) on truncation.
--- @param buf string
--- @param pos integer -- 0-based
--- @return integer|nil, integer
local function read_uleb128_at(buf, pos)
local value = 0
local shift = 0
local buf_len = #buf
while pos < buf_len do
local byte = buf:byte(pos + 1)
value = value + (byte % 0x80) * (2 ^ shift) -- extract low 7 bits, shift left
shift = shift + 7
pos = pos + 1
if byte < 0x80 then return value, pos end -- continuation bit clear → final byte
end
return nil, pos
end
--- Read a SLEB128 value starting at 0-based byte offset `pos` in `buf`.
--- Returns (value, next_pos). Returns (nil, pos) on truncation.
--- @param buf string
--- @param pos integer -- 0-based
--- @return integer|nil, integer
local function read_sleb128_at(buf, pos)
local value = 0
local shift = 0
local buf_len = #buf
while pos < buf_len do
local byte = buf:byte(pos + 1)
value = value + (byte % 0x80) * (2 ^ shift)
shift = shift + 7
pos = pos + 1
if byte < 0x80 then
-- Sign-extend if the sign bit (bit 6) of the last byte is set.
if byte >= 0x40 then
value = value - (2 ^ shift)
end
return value, pos
end
end
return nil, pos
end
--- Walk a .debug_abbrev table starting at 0-based offset `table_start` and return the 0-based offset of the table-terminator byte
--- (a single 0 byte marking the end of declarations in this table per DWARF5 §7.5.3).
---
--- The walker consumes each declaration's abbrev code (ULEB) + tag (ULEB) + has_children byte + (attr, form)
--- attr-spec pairs (each pair = ULEB + ULEB, with an extra SLEB constant for DW_FORM_implicit_const per DWARF5 §7.5.6).
--- The declaration's attr-spec list ends at the (0, 0) pair.
---
--- Returns nil on truncated or malformed input.
--- @param existing string -- the .debug_abbrev section bytes
--- @param table_start integer -- 0-based offset of the table's first byte
--- @return integer|nil -- 0-based offset of the table-terminator byte
local function find_abbrev_table_end(existing, table_start)
local pos = table_start
local buf_len = #existing
-- Empty table = terminator byte at table_start.
if pos >= buf_len or existing:byte(pos + 1) == 0 then return pos end
while pos < buf_len do
-- Each declaration: ULEB code, ULEB tag, 1 byte has_children.
local _code, code_end = read_uleb128_at(existing, pos)
if not _code then return nil end
pos = code_end
local _tag, tag_end = read_uleb128_at(existing, pos)
if not _tag then return nil end
pos = tag_end
-- has_children: 1 byte (DW_CHILDREN_yes=1 / DW_CHILDREN_no=0).
if pos >= buf_len then return nil end
pos = pos + 1
-- attr/form loop until (0, 0) terminator pair.
while pos < buf_len do
local attr, attr_end = read_uleb128_at(existing, pos)
if not attr then return nil end
pos = attr_end
local form, form_end = read_uleb128_at(existing, pos)
if not form then return nil end
pos = form_end
if attr == 0 and form == 0 then break end
-- DW_FORM_implicit_const: declaration carries a SLEB constant.
if form == DW_FORM_implicit_const then
local _const, const_end = read_sleb128_at(existing, pos)
if not _const then return nil end
pos = const_end
end
end
-- Next declaration starts here; if next byte is 0, the table is done.
if pos >= buf_len then return nil end
if existing:byte(pos + 1) == 0 then return pos end
end
return nil
end
-- DWARF5 compile-unit header constants.
local DW_VERSION_5 = 5
local DW_UT_compile = 0x01
@@ -1389,7 +1288,7 @@ local function find_main_cu_layout(existing)
local main_cu_start = nil
local main_cu_end_excl = nil
while pos + 4 <= buf_len do
local unit_length = elf_dwarf.read_u32_le(existing, pos + 1)
local unit_length = elf_dwarf.read_u32_le(existing, pos)
if unit_length == DWARF32_TERMINATOR then return nil end
local unit_end_excl = pos + 4 + unit_length
if unit_end_excl > buf_len then return nil end
@@ -1408,10 +1307,10 @@ local function find_main_cu_layout(existing)
-- [7] address_size
-- [8..11] debug_abbrev_offset
local hdr = main_cu_start + 4
local version = elf_dwarf.read_u16_le(existing, hdr + 1)
local unit_type = existing:byte(hdr + 3)
local address_size = existing:byte(hdr + 4)
local abbrev_off = elf_dwarf.read_u32_le(existing, hdr + 5)
local version = elf_dwarf.read_u16_le(existing, hdr)
local unit_type = existing:byte(hdr + 2 + 1)
local address_size = existing:byte(hdr + 3 + 1)
local abbrev_off = elf_dwarf.read_u32_le(existing, hdr + 4)
if version ~= DW_VERSION_5 or unit_type ~= DW_UT_compile or address_size ~= 4 then
return nil
end
@@ -1549,16 +1448,9 @@ local function build_new_abbrev()
.. abbrev_struct_type .. abbrev_member .. abbrev_bind_var .. abbrev_base_type
.. abbrev_abstract_subprogram .. abbrev_inlined_subroutine
.. abbrev_bind_var_loclists
.. string.char(0x00)
.. string.char(DW_LLE_end_of_list) -- section terminator (the loclist-unit end marker per DWARF5 §7.7.3)
end
--- Build the new strings to append to .debug_str. Each string is null-terminated.
-- The CU name + comp_dir + one entry per RR_<name> debug-visible alias all go into one new blob.
-- Register names are sourced from the merged registry filtered to MIPS GPR 0..31
-- (the same filter that build_inserted_children applies for the RR_<name> locals, so .debug_str entries stay in sync with .debug_info).
-- @param atom_table table[] -- list of {name, addr, size_bytes, ...}
-- @param registries table -- merged registries from collect_per_source_registries
-- @return string, table -- (new_strings_blob, map_of_name_to_offset_in_new_blob)
--- Strip a leading "R_" prefix from an enum alias name.
--- The .debug_str/.debug_info consumers display the local without the C-enum prefix (RR_PrimCursor, not RR_R_PrimCursor)
@@ -1572,6 +1464,13 @@ local function strip_r_prefix(r_name)
return r_name
end
--- Build the new strings to append to .debug_str. Each string is null-terminated.
-- The CU name + comp_dir + one entry per RR_<name> debug-visible alias all go into one new blob.
-- Register names are sourced from the merged registry filtered to MIPS GPR 0..31
-- (the same filter that build_inserted_children applies for the RR_<name> locals, so .debug_str entries stay in sync with .debug_info).
-- @param atom_table table[] -- list of {name, addr, size_bytes, ...}
-- @param registries table -- merged registries from collect_per_source_registries
-- @return string, table -- (new_strings_blob, map_of_name_to_offset_in_new_blob)
local function build_new_strings(atom_table, registries)
registries = registries or {}
-- The CU name + comp_dir are the first two strings (offsets 0 and N1).
@@ -1601,13 +1500,20 @@ local function build_new_strings(atom_table, registries)
-- Register names (one per unique debug-visible R_Name alias from the merged registry,
-- filtered to MIPS GPR 0..31 — the same filter that build_inserted_children applies
-- for the RR_<name> locals, so .debug_str entries stay in sync with .debug_info).
-- Plex: Lua's pairs() is non-deterministic; sort the alias names first so the emitted
-- .debug_str bytes are byte-identical across runs.
local sorted_alias_names = {}
for r_name, alias in pairs(registries.register_alias_registry or {}) do
if alias.code and alias.code >= 0 and alias.code <= 31 then
local rr_name = "RR_" .. strip_r_prefix(r_name)
if not map[rr_name] then
map[rr_name] = #table.concat(strings)
strings[#strings + 1] = rr_name .. "\0"
end
sorted_alias_names[#sorted_alias_names + 1] = r_name
end
end
table.sort(sorted_alias_names)
for _, r_name in ipairs(sorted_alias_names) do
local rr_name = "RR_" .. strip_r_prefix(r_name)
if not map[rr_name] then
map[rr_name] = #table.concat(strings)
strings[#strings + 1] = rr_name .. "\0"
end
end
@@ -1672,12 +1578,19 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
-- by_alias: the merged register_alias_registry filtered to aliases whose `code` is a valid MIPS GPR 0..31.
-- Aliases absent from the merged registry are not debug-visible and are skipped entirely (no fallback GPR).
-- by_alias_order: sorted list of by_alias keys, for deterministic iteration order.
-- (Lua's pairs() order is implementation-defined and may vary between runs;
-- without sorting, the per-atom variable emission order would be non-deterministic
-- and the .debug_info bytes would differ across builds.)
local by_alias = {}
for r_name, alias in pairs(registries.register_alias_registry or {}) do
if alias.code and alias.code >= 0 and alias.code <= 31 then
by_alias[r_name] = alias
end
end
local by_alias_order = {}
for r_name in pairs(by_alias) do by_alias_order[#by_alias_order + 1] = r_name end
table.sort(by_alias_order)
-- Build a name->atom lookup for fast rbind_atom resolution during the per-atom phase/ctx propagation.
-- Cheap (O(atom_table)) and built once.
@@ -1694,18 +1607,31 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
-- The first emitted byte lives at section offset (main_cu_end_excl - 1).
local insertion_start = main_cu_end_excl - 1
local bytes = {}
local next_offset = insertion_start -- 0-based section offset of the NEXT byte to emit
-- Closure state: bytes + next_offset + the typed-view/structure/abstract offset caches.
-- All step-emitters mutate this state in place. Plex: Fleury expose structure over interface.
local S = {
bytes = {},
next_offset = insertion_start, -- 0-based section offset of the NEXT byte to emit
type_chain_offsets = {}, -- {[type_name.."|"..depth] = section_offset for the outermost pointer_type}
struct_section_offsets = {}, -- {[binds_name] = section_offset for the structure_type}
abstract_offsets = {}, -- {[comp_name] = section_offset for the abstract subprogram}
member_base_type_offsets = {}, -- {[tn.."|"..byte_size.."|"..encoding] = section_offset}
base_type_section_offset = nil, -- set by emit_unsigned_int_base_type
}
-- Plex helpers.
local function emit(s)
bytes[#bytes + 1] = s
next_offset = next_offset + #s
S.bytes[#S.bytes + 1] = s
S.next_offset = S.next_offset + #s
end
local function ref4_of(section_offset)
return section_offset - main_cu_offset
end
-- 1) Emit the base_type DIE first (member ref4s reference it).
-- (Use a local alias for S.next_offset; the rest of the function body still
-- uses the bare name `next_offset` from the previous unrefactored version).
local next_offset = S.next_offset
local base_type_section_offset = next_offset
emit(uleb128(ABBREV_BASE_TYPE))
emit("unsigned int\0") -- DW_FORM_string (DW_AT_name)
@@ -1829,13 +1755,12 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
local depth = used_typed_views[tn]
local type_info = STRUCT_MEMBER_TABLE[tn]
if not type_info then
-- Unknown typed view — fall back to a generic base_type to keep the wire valid
-- Unknown typed view — fall back to a generic 4-byte unsigned base_type to keep the wire valid
-- (gdb will render as the typename but `print *ptr` will only see the first 4 bytes).
-- This is the pre-Track-A behavior; preserved here for forward compatibility with future typed views not in our table.
local innermost_offset = next_offset
emit(uleb128(ABBREV_BASE_TYPE))
emit(tn .. "\0")
emit(string.char(4)) -- byte_size = 4 (legacy stand-in)
emit(string.char(U4_BYTE_SIZE)) -- byte_size = 4 (fallback for unknown types)
emit(string.char(DW_ATE_unsigned)) -- encoding = unsigned
local outermost_offset = next_offset
emit(uleb128(9)) -- DW_TAG_pointer_type
@@ -1845,8 +1770,8 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
-- Emit a proper structure_type DIE for this typed view.
local struct_offset = next_offset
emit(uleb128(ABBREV_STRUCT_TYPE))
emit(tn .. "\0") -- DW_AT_name (struct_type has children, no name in abbrev 103 [DW_FORM_string only])
emit(uleb128(type_info.byte_size)) -- DW_AT_byte_size (DW_FORM_udata)
emit(tn .. "\0") -- DW_AT_name (struct_type has children, no name in abbrev 103 [DW_FORM_string only])
emit(uleb128(type_info.byte_size)) -- DW_AT_byte_size (DW_FORM_udata)
-- For each member, emit ABBREV_MEMBER (name + data_member_location + type ref4).
for _, m in ipairs(type_info.members) do
emit(uleb128(ABBREV_MEMBER))
@@ -1868,7 +1793,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
local member_base_off = ensure_member_base_type(member_type_name, m.byte_size, member_type_encoding)
emit(elf_dwarf.write_u32_le(ref4_of(member_base_off))) -- DW_AT_type ref4 → base_type
end
emit(string.char(0x00)) -- end of structure_type's children
emit(string.char(DIE_CHILDREN_TERMINATOR)) -- end of structure_type's children (DWARF5 §7.5.3)
-- Emit a single DW_TAG_pointer_type (abbrev 9) pointing at the structure_type.
-- For depth > 1, we'd chain pointer_type → pointer_type → ... → structure_type; not exercised.
if depth == 1 then
@@ -1947,7 +1872,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
emit(elf_dwarf.write_u32_le(ref4_of(field_type_offset))) -- DW_FORM_ref4 → type
end
emit(string.char(0x00)) -- end of structure_type's children
emit(string.char(DIE_CHILDREN_TERMINATOR)) -- end of structure_type's children (DWARF5 §7.5.3)
end
-- 3) Emit one abstract DW_TAG_subprogram per unique mac_X component.
@@ -2058,51 +1983,72 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
end
end
for r_name, alias in pairs(by_alias) do
local rr_name = "RR_" .. strip_r_prefix(r_name)
local alias_code = alias.code
emit(uleb128(ABBREV_VARIABLE))
emit(rr_name .. "\0") -- DW_FORM_string (DW_AT_name)
emit(reg_exprloc(alias_code)) -- DW_FORM_exprloc (DW_OP_regN from registry code)
-- Resolve the type for this register via the 6-step precedence chain.
local type_offset = type_chain_offsets["void|1"] -- step (f) fallback: void* (renders as hex)
-- step (a): per-atom callsite atom_type(R_X, <T>)
local override = atom_view and atom_view.reg_type_overrides and atom_view.reg_type_overrides[r_name]
if override and override.pointer_depth and override.pointer_depth > 0 then
local chain_offset = type_chain_offsets[override.type_name .. "|" .. override.pointer_depth]
if chain_offset then type_offset = chain_offset end
else
-- step (b): atom_ctx(<rbind_atom>) propagation
-- 5-step precedence chain. Plex: data table; the dispatch loop runs the first step that yields a non-nil offset.
-- Each step returns the type's section offset or nil if it missed.
-- Adding a step = 1 row in the table + 1 function. The 5-level nested if/else is gone.
-- Per-atom precomputed state is captured in upvalues: atom_view, reg_to_field_ctx, atom_view_ctx_fields,
-- reg_to_field_phase, atom_view_phase_fields, field_type_by_name, reg_to_field, alias, type_chain_offsets.
local PRECEDENCE_STEPS = {
-- (a) per-atom callsite atom_type(R_X, <T>): most specific; user explicit override for THIS atom only.
function(r_name, alias_code)
local override = atom_view and atom_view.reg_type_overrides and atom_view.reg_type_overrides[r_name]
if override and override.pointer_depth and override.pointer_depth > 0 then
return type_chain_offsets[override.type_name .. "|" .. override.pointer_depth]
end
end,
-- (b) atom_ctx(<rbind_atom>) propagation.
function(r_name, alias_code)
local ctx_field_name = reg_to_field_ctx and reg_to_field_ctx[alias_code]
local ctx_f = ctx_field_name and atom_view_ctx_fields and atom_view_ctx_fields[ctx_field_name]
if ctx_f and ctx_f.pointer_depth and ctx_f.pointer_depth > 0 then
local chain_offset = type_chain_offsets[ctx_f.type_name .. "|" .. ctx_f.pointer_depth]
if chain_offset then type_offset = chain_offset end
else
-- step (c): self-bind (this atom is the rbind atom)
local field_name = reg_to_field[alias_code]
local f = field_name and field_type_by_name[field_name]
if f and f.pointer_depth and f.pointer_depth > 0 then
local chain_offset = type_chain_offsets[f.type_name .. "|" .. f.pointer_depth]
if chain_offset then type_offset = chain_offset end
else
-- step (d): atom_phase(<label>)-grouped propagation
local phase_field_name = reg_to_field_phase and reg_to_field_phase[alias_code]
local phase_f = phase_field_name and atom_view_phase_fields and atom_view_phase_fields[phase_field_name]
if phase_f and phase_f.pointer_depth and phase_f.pointer_depth > 0 then
local chain_offset = type_chain_offsets[phase_f.type_name .. "|" .. phase_f.pointer_depth]
if chain_offset then type_offset = chain_offset end
else
-- step (e): enum-site atom_type(<T>) default on the registry entry
if alias.default_type and alias.default_depth and alias.default_depth > 0 then
local chain_offset = type_chain_offsets[alias.default_type .. "|" .. alias.default_depth]
if chain_offset then type_offset = chain_offset end
end
-- step (f): void* fallback (set as type_offset initial value above).
end
end
return type_chain_offsets[ctx_f.type_name .. "|" .. ctx_f.pointer_depth]
end
end,
-- (c) self-binding (this atom IS the rbind atom for its Binds_*).
function(r_name, alias_code)
local field_name = reg_to_field[alias_code]
local f = field_name and field_type_by_name[field_name]
if f and f.pointer_depth and f.pointer_depth > 0 then
return type_chain_offsets[f.type_name .. "|" .. f.pointer_depth]
end
end,
-- (d) atom_phase(<label>)-grouped propagation.
function(r_name, alias_code)
local phase_field_name = reg_to_field_phase and reg_to_field_phase[alias_code]
local phase_f = phase_field_name and atom_view_phase_fields and atom_view_phase_fields[phase_field_name]
if phase_f and phase_f.pointer_depth and phase_f.pointer_depth > 0 then
return type_chain_offsets[phase_f.type_name .. "|" .. phase_f.pointer_depth]
end
end,
-- (e) enum-site atom_type(<T>) default on the registry entry.
function(r_name, alias_code)
if alias and alias.default_type and alias.default_depth and alias.default_depth > 0 then
return type_chain_offsets[alias.default_type .. "|" .. alias.default_depth]
end
end,
}
-- Plex: iterate `by_alias` in sorted order (Lua's pairs() is non-deterministic;
-- sorting ensures byte-identical DWARF output across builds).
for _, r_name in ipairs(by_alias_order) do
local alias = by_alias[r_name]
local rr_name = "RR_" .. strip_r_prefix(r_name)
local alias_code = alias.code
emit(uleb128(ABBREV_VARIABLE))
emit(rr_name .. "\0") -- DW_FORM_string (DW_AT_name)
-- DW_FORM_exprloc: ULEB byte count + DW_OP_regN byte.
-- DW_OP_reg0..reg31 occupy opcodes 0x50..0x6f; DW_OP_reg15 is 0x5f.
-- Inlined from `reg_exprloc` (single caller; the function was 3 LOC).
-- DW_FORM_exprloc: ULEB byte count + DW_OP_regN byte.
-- Inlined from `reg_exprloc` (was at lines 1185-1188, dwarf_injection.lua; the function was 3 LOC and 1 caller).
-- The `1` is the length prefix — DW_OP_regN occupies exactly 1 byte (the base opcode is 0x50; regN = 0x50 + N).
-- `alias_code` is the MIPS GPR index (0..31) from the merged register_alias_registry.
emit(uleb128(1) .. string.char(DW_OP_reg0 + alias_code)) -- DW_FORM_exprloc (DW_OP_regN from registry code)
-- Precedence chain (a..e); step (f) is the void* fallback (initial value).
local type_offset = type_chain_offsets["void|1"]
for _, step in ipairs(PRECEDENCE_STEPS) do
local candidate = step(r_name, alias_code)
if candidate then type_offset = candidate; break end
end
emit(elf_dwarf.write_u32_le(ref4_of(type_offset))) -- DW_FORM_ref4 → type
emit(string.char(0x01)) -- DW_AT_external=1 (visible at CU scope)
@@ -2139,12 +2085,11 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
end
end
emit(string.char(0x00)) -- end of subprogram's children
emit(string.char(DIE_CHILDREN_TERMINATOR)) -- end of subprogram's children (DWARF5 §7.5.3)
end
-- DO NOT emit a final 0 here — that's the main CU's root terminator, which
-- build_debug_info_section preserves verbatim.
return table.concat(bytes)
-- DO NOT emit a final 0 here — that's the main CU's root terminator, which build_debug_info_section preserves verbatim.
return table.concat(S.bytes)
end
--- Build the new .debug_abbrev: existing + duplicate of the main CU's table + the new declarations 100..106 (with their terminating 0).
@@ -2221,7 +2166,7 @@ local function build_debug_info_section(existing, main_cu_start, main_cu_end_exc
local inserted_len = #inserted
-- 2) Patch main CU's unit_length += inserted_len.
local old_unit_length = elf_dwarf.read_u32_le(existing, main_cu_start + 1)
local old_unit_length = elf_dwarf.read_u32_le(existing, main_cu_start)
local new_unit_length = old_unit_length + inserted_len
local new_unit_length_bytes = elf_dwarf.write_u32_le(new_unit_length)
@@ -2252,10 +2197,8 @@ end
--- Atoms don't have stack frames. The .debug_loc section describes per-instruction location adjustments for call-frame-based variables;
--- We use DW_OP_regN which is register-based and doesn't need .debug_loc entries).
--- The section itself must not be empty OR gdb may complain; the DW_LLE_end_of_list marker (per DWARF5 §7.7) is a single byte 0x00.
--- @return string
local function build_debug_loc_section()
return string.char(0x00)
end
--- Single-caller (M.run's SECTION_BUILDERS table below); replaced by a literal at the call site.
-- local function build_debug_loc_section() return string.char(0x00) end
local SECTION_BUILDERS = {
debug_line = build_dwarf_line_section,
@@ -2264,7 +2207,7 @@ local SECTION_BUILDERS = {
debug_abbrev = build_debug_abbrev_section,
debug_info = build_debug_info_section,
debug_str = build_debug_str_section,
debug_loc = function() return build_debug_loc_section() end,
debug_loc = function() return string.char(DW_LLE_end_of_list) end,
-- debug_loclists is fed directly in M.run (it needs the merged registries for the R_TapePtr GPR lookup;
-- the SECTION_BUILDERS table cannot carry that context, so the dispatch is inlined in the per-run writers loop).
}
@@ -2282,6 +2225,34 @@ local SECTION_WRITERS = {
debug_loclists = function(out_root, basename) return out_root .. "\\" .. basename .. ".dwarf_loclists.bin" end,
}
-- Write a list of {name, data, was} section records to disk via SECTION_WRITERS.
-- Used twice in M.run (safe-path + production-path).
-- The only difference between the two call sites is the `is_production` flag, which gates the per-section progress line.
-- @param results table[] -- list of {name=, data=, was=} records to write
-- @param ctx PassCtx
-- @param basename string -- output file basename (e.g. "hello_gte")
-- @param is_production bool -- true → emit progress line; false → silent
-- @param atom_table table -- used by the progress line (only when is_production)
-- @return table -- list of {name_bin = path} entries to append to M.run's outputs
local function write_sections(results, ctx, basename, is_production, atom_table)
local outputs = {}
for _, r in ipairs(results) do
local path = SECTION_WRITERS[r.name](ctx.out_root, basename)
local f = io.open(path, "wb")
if not f then
io.stderr:write(string.format("[dwarf_injection] failed to open %s for write\n", path))
else
f:write(r.data); f:close()
if is_production then
io.stderr:write(string.format("[dwarf_injection] new .%s = %d bytes (was %d, +%d atoms)\n"
, r.name, #r.data, r.was, #atom_table))
end
outputs[#outputs + 1] = { [r.name .. "_bin"] = path }
end
end
return outputs
end
local function write_gdbinit(out_root, basename, skip_over, atom_table)
local path = out_root .. "\\" .. basename .. ".gdbinit"
duffle.write_file_lf(path, build_gdbinit(skip_over, atom_table))
@@ -2340,6 +2311,8 @@ function M.run(ctx)
-- Consume source-as-written skip associations from every scanned source,
-- then build the atom/provenance table with those generic selections.
-- Whole atoms remain symbol-keyed; components are file-qualified internally so a source marker associates
-- with its exact component definition even though GDB 12 requires function-only skip entries for the resulting synthetic inline frame.
local skip_over = collect_skip_over(ctx)
local registries = collect_per_source_registries(ctx)
local atom_table = build_atom_table(ctx, skip_over)
@@ -2364,7 +2337,7 @@ function M.run(ctx)
-- 4. Build .debug_loc (just a terminator).
--
-- .debug_str now also receives the new RR_<R_Name> entries
-- (the prior "left untouched in this slice" claim is obsolete; the merged registry drives the strings table to keep .debug_str and .debug_info in sync).
-- (the merged registry drives the strings table to keep .debug_str and .debug_info in sync).
local basename = ctx.basename or duffle.basename_no_ext(elf_path) or DEFAULT_BASENAME
if ctx.out_root and ctx.out_root ~= "" then
duffle.ensure_dir(ctx.out_root)
@@ -2384,19 +2357,11 @@ function M.run(ctx)
{ name = "debug_line", data = build_dwarf_line_section (existing_sections[".debug_line"] or "", atom_table), was = #(existing_sections[".debug_line"] or "") },
{ name = "debug_aranges", data = build_dwarf_aranges_section (existing_sections[".debug_aranges"] or "", atom_table), was = #(existing_sections[".debug_aranges"] or "") },
{ name = "debug_rnglists", data = build_dwarf_rnglists_section(existing_sections[".debug_rnglists"] or "", atom_table), was = #(existing_sections[".debug_rnglists"] or "") },
{ name = "debug_loc", data = build_debug_loc_section(), was = #(existing_sections[".debug_loc"] or "") },
{ name = "debug_loc", data = string.char(DW_LLE_end_of_list), was = #(existing_sections[".debug_loc"] or "") },
}
local section_outputs = write_sections(results_safe, ctx, basename, false, atom_table)
local outputs_safe = { gdbinit_output }
for _, r in ipairs(results_safe) do
local path = SECTION_WRITERS[r.name](ctx.out_root, basename)
local f = io.open(path, "wb")
if not f then
io.stderr:write(string.format("[dwarf_injection] failed to open %s for write\n", path))
else
f:write(r.data); f:close()
outputs_safe[#outputs_safe + 1] = { [r.name .. "_bin"] = path }
end
end
for _, o in ipairs(section_outputs) do outputs_safe[#outputs_safe + 1] = o end
return { outputs = outputs_safe, errors = {}, warnings = {} }
end
@@ -2426,23 +2391,13 @@ function M.run(ctx)
{ name = "debug_line", data = build_dwarf_line_section (existing_sections[".debug_line"] or "", atom_table), was = #(existing_sections[".debug_line"] or "") },
{ name = "debug_aranges", data = build_dwarf_aranges_section (existing_sections[".debug_aranges"] or "", atom_table), was = #(existing_sections[".debug_aranges"] or "") },
{ name = "debug_rnglists", data = build_dwarf_rnglists_section(existing_sections[".debug_rnglists"] or "", atom_table), was = #(existing_sections[".debug_rnglists"] or "") },
{ name = "debug_loc", data = build_debug_loc_section(), was = #(existing_sections[".debug_loc"] or "") },
{ name = "debug_loc", data = string.char(DW_LLE_end_of_list), was = #(existing_sections[".debug_loc"] or "") },
{ name = "debug_loclists", data = build_debug_loclists_section(atom_table, registries), was = 0 },
}
local section_outputs = write_sections(results, ctx, basename, true, atom_table)
local outputs = { gdbinit_output }
for _, r in ipairs(results) do
local path = SECTION_WRITERS[r.name](ctx.out_root, basename)
local f = io.open(path, "wb")
if not f then
io.stderr:write(string.format("[dwarf_injection] failed to open %s for write\n", path))
else
f:write(r.data); f:close()
io.stderr:write(string.format("[dwarf_injection] new .%s = %d bytes (was %d, +%d atoms)\n"
, r.name, #r.data, r.was, #atom_table))
outputs[#outputs + 1] = { [r.name .. "_bin"] = path }
end
end
for _, o in ipairs(section_outputs) do outputs[#outputs + 1] = o end
return {
outputs = outputs,
errors = {},
scripts/passes/offsets.lua
+2 -28
View File
@@ -172,32 +172,6 @@ local function scan_for_atom_markers(token, at_pos, labels, branches)
end
end
-- (internal) Count words emitted by the rest of `tok` after a marker call
-- (the marker call itself emits 0 words, but the source pattern may bundle the marker with the next instruction on the same line,
-- separated by no top-level comma).
-- Returns the word count contributed by that rest.
-- @param tok string
-- @param word_counts table
-- @return integer
local function count_marker_rest(tok, word_counts)
-- duffle.find_marker_call_end returns the position PAST the closing `)` of the marker call
-- (or nil if `tok` isn't a marker call). Canonical impl in duffle.lua is faster than the
-- file-local copy that used to live here (byte-indexed, no `tok:sub` per char).
local marker_end = duffle.find_marker_call_end(tok)
if not marker_end or marker_end >= #tok then return 0 end
local rest = duffle.trim(tok:sub(marker_end))
if rest == "" then return 0 end
return count_token_words(rest, word_counts)
end
-- (internal) Is this token a marker call (`atom_label` or `atom_offset`)?
-- @param tok string
-- @return boolean
local function is_marker_token(tok)
local leading_ident = duffle.read_ident(tok, 1)
return leading_ident == LABEL_MARKER or leading_ident == OFFSET_MARKER
end
--- Scan an atom body for labels + branches, count total words.
--- Returns (labels, branches, total_words).
--- @param body string
@@ -214,10 +188,10 @@ local function scan_atom_body(body_tokens, word_counts)
local branches = {}
for _, t in ipairs(body_tokens) do
local tok = t.tok
if is_marker_token(tok) then
if duffle.is_marker_token(tok) then
-- Marker call: record at the current pos, do NOT advance pos.
scan_for_atom_markers(tok, pos, labels, branches)
pos = pos + count_marker_rest(tok, word_counts)
pos = pos + duffle.count_marker_rest(tok, word_counts, count_token_words)
else
local words = count_token_words(tok, word_counts)
scan_for_atom_markers(tok, pos, labels, branches)
scripts/passes/report.lua
-1
View File
@@ -16,7 +16,6 @@
-- ════════════════════════════════════════════════════════════════════════════
-- Resolve `arg[0]` to an absolute-ish script directory so that `require("duffle")` resolves against `scripts/` regardless of CWD.
-- Note: this boilerplate is duplicated in 6 other entry scripts; extraction target (`duffle.setup_package_path()`).
-- Bootstrap: see `ps1_meta.lua` for the rationale.
-- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
-- Uses `debug.getinfo` to find this file's own directory, so it works
scripts/passes/scan_source.lua
+243 -352
View File
@@ -19,9 +19,8 @@
-- Bootstrap: same as entry scripts. See `ps1_meta.lua` for the rationale.
-- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
-- Uses `debug.getinfo` to find this file's own directory, so it works
-- both standalone and when require'd from the orchestrator.
-- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when require'd).
-- Uses `debug.getinfo` to find this file's own directory, so it works both standalone and when require'd from the orchestrator.
-- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when required).
-- duffle_paths.lua sets package.path then returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua")
@@ -172,6 +171,26 @@ local function push_skip_over_marker(out, marker)
markers[#markers + 1] = marker
end
-- Try to read `(...)` parens after `ident_end`.
-- Returns (inner, after_paren, open_paren) on success, or (nil, fallback_pos) if no parens.
-- `fallback_pos` defaults to `open_paren + 1` (the common "advance by 1" no-parens case).
local function read_parens_after(source, ident_end, fallback)
local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
if source:sub(open_paren, open_paren) ~= "(" then return nil, fallback or open_paren + 1 end
local inner, after_paren = duffle.read_parens(source, open_paren)
return inner, after_paren, open_paren
end
-- Find the opening `{` of a body block and read its contents.
-- Returns (body, after_brace, body_off) on success, or (nil, fallback_pos) on no brace.
-- `fallback_pos` defaults to `after_paren + 1` (the common "advance by 1" case).
local function find_body_braces(source, after_paren, fallback)
local brace = duffle.scan_to_char(source, "{", after_paren)
if not brace then return nil, fallback or (after_paren + 1) end
local body, after_brace = duffle.read_braces(source, brace)
return body, after_brace, brace + 1
end
-- Attach the pending marker to the next declaration.
-- The declaration form disambiguates whole atoms from components;
-- unsupported declarations retain placement evidence for annotation.lua and populate neither lookup table.
@@ -202,30 +221,25 @@ local function associate_skip_over_marker(out, target_name, target_raw_name, tar
end
end
-- Read a top-level comma-delimited argument list. Mirrors split_top_level_commas in shape;
-- kept inline so scan_source can remain dependency-free.
local function read_top_level_args(text, pos)
local args = {}
pos = duffle.skip_ws_and_cmt(text, pos)
while pos <= #text do
local buf, level = {}, 0
while pos <= #text do
local c = text:sub(pos, pos)
if c == "(" or c == "[" or c == "{" then level = level + 1
elseif c == ")" or c == "]" or c == "}" then
if level == 0 then break end
level = level - 1
elseif c == "," and level == 0 then break end
buf[#buf + 1] = c
pos = pos + 1
end
local arg = duffle.trim(table.concat(buf))
if arg ~= "" then args[#args + 1] = arg end
if pos > #text then break end
if text:sub(pos, pos) == "," then pos = pos + 1; pos = duffle.skip_ws_and_cmt(text, pos) end
if not text:sub(pos, pos) or text:sub(pos, pos) == ")" then break end
end
return args
-- Register a parsed atom entry in `out.atoms` and link its skip-over marker.
-- Captures the shared 8-field shape used by MipsAtom_, MipsAtomComp_, MipsAtomComp_Proc_.
local function register_atom(out, kind, declaration_line, name, body, body_off, raw_name, pos, after_paren)
out.atoms[#out.atoms + 1] = {
line = declaration_line, name = name, body = body, body_off = body_off,
kind = kind, raw_name = raw_name,
ident_pos = pos, after_paren = after_paren,
}
associate_skip_over_marker(out, name, raw_name, kind, declaration_line, pos)
end
-- Register a parsed raw-atom entry in `out.raw_atoms` and link its skip-over marker.
-- Captures the 5-field shape used by MipsCode (the raw-atom form; offsets pass only).
local function register_raw_atom(out, declaration_line, name, body, body_off, raw_name, pos, marker_kind)
out.raw_atoms[#out.raw_atoms + 1] = {
line = declaration_line, name = name, body = body, body_off = body_off,
kind = "raw_atom", raw_name = raw_name,
}
associate_skip_over_marker(out, name, raw_name, marker_kind, declaration_line, pos)
end
-- Parse a `Type*` chain (zero or more `*` separated by optional whitespace) followed by the type ident.
@@ -256,15 +270,14 @@ local BUILTIN_BYTE_SIZES = {
["S1"] = 1,
["S2"] = 2,
["S4"] = 4,
-- GCC __UINT*_TYPE__ family (used by the duffle TSet_ convention). TODO(Ed): Do we really need these, they shouldn't be directly used...
-- GCC __UINT*/__INT*_TYPE__ family (used by the duffle TSet_ convention in dsl.h).
-- MIPS32 has no 64-bit types; __UINT64_TYPE__/__INT64_TYPE__ are excluded.
["__UINT8_TYPE__"] = 1,
["__UINT16_TYPE__"] = 2,
["__UINT32_TYPE__"] = 4,
["__UINT64_TYPE__"] = 8,
["__INT8_TYPE__"] = 1,
["__INT16_TYPE__"] = 2,
["__INT32_TYPE__"] = 4,
["__INT64_TYPE__"] = 8,
}
-- Pointer fields collapse to 4 bytes on MIPS32 (PS1).
@@ -273,128 +286,87 @@ local POINTER_BYTE_SIZE = 4
-- Maximum chain depth when resolving typedef / TSet_ chains (cycle guard).
local TYPE_CHAIN_MAX_DEPTH = 8
-- Parse the `<type> <field>;` declarations from a Struct_ body.
-- Returns the raw fields array with `{name, type_name, pointer_depth}` only (NO offset / byte_size).
-- The propagation pass `resolve_struct_field_sizes` walks each struct's fields AFTER type resolution and populates offset + byte_size in place.
-- Returns (fields). The aggregate byte_count is computed in the propagation pass (it depends on whether every field's type resolved).
local function parse_struct_body_fields(body)
-- Walk a `Struct_` / `Enum_` body, calling `build_field(first, first_end, after_first)` for each entry.
-- The builder returns either:
-- - (record, new_pos) -- append record to fields; advance body_pos to new_pos
-- - (nil, new_pos) -- skip this entry; advance body_pos to new_pos
-- After each entry, the walker skips a single trailing `,` or `;`.
-- The 2 body-field parsers in this file (struct + enum) share this body-walk loop.
-- @param body string
--- @param build_field fun(first: string, first_end: integer, after_first: integer): (table|nil, integer)
--- @return table[]
local function walk_body_fields(body, build_field)
local fields = {}
local body_pos = 1
local body_len = #body
while body_pos <= body_len do
body_pos = duffle.skip_ws_and_cmt(body, body_pos)
if body_pos > body_len then break end
local type_ident, type_end = duffle.read_ident(body, body_pos)
if not type_ident then
local first, first_end = duffle.read_ident(body, body_pos)
if not first then
body_pos = body_pos + 1
else
-- Parse the trailing `*` chain to derive pointer_depth.
local depth = 0
local cursor = duffle.skip_ws_and_cmt(body, type_end)
while cursor <= body_len and body:sub(cursor, cursor) == "*" do
depth = depth + 1
cursor = cursor + 1
cursor = duffle.skip_ws_and_cmt(body, cursor)
end
-- Read the field ident immediately after the type chain.
local field_ident, field_end = duffle.read_ident(body, cursor)
if not field_ident then
body_pos = type_end + 1
else
fields[#fields + 1] = {
name = field_ident,
type_name = type_ident,
pointer_depth = depth,
-- offset + byte_size filled by resolve_struct_field_sizes
offset = nil,
byte_size = nil,
}
body_pos = field_end
local after_first = duffle.skip_ws_and_cmt(body, first_end)
local result, new_pos = build_field(first, first_end, after_first)
if result then fields[#fields + 1] = result end
body_pos = new_pos or first_end
-- Skip a single trailing `,` or `;`.
if body_pos <= body_len and (body:sub(body_pos, body_pos) == "," or body:sub(body_pos, body_pos) == ";") then
body_pos = body_pos + 1
end
end
end
return fields
end
-- Parse the `<type> <field>;` declarations from a Struct_ body.
-- Returns the raw fields array with `{name, type_name, pointer_depth}` only (NO offset / byte_size).
-- The propagation pass `resolve_struct_field_sizes` walks each struct's fields AFTER type resolution and populates offset + byte_size in place.
-- Returns (fields). The aggregate byte_count is computed in the propagation pass (it depends on whether every field's type resolved).
local function parse_struct_body_fields(body)
return walk_body_fields(body, function(type_name, type_end, after_type)
-- Parse the trailing `*` chain to derive pointer_depth.
local depth, cursor = 0, after_type
while cursor <= #body and body:sub(cursor, cursor) == "*" do
depth = depth + 1
cursor = cursor + 1
cursor = duffle.skip_ws_and_cmt(body, cursor)
end
-- Read the field ident immediately after the type chain.
local field_ident, field_end = duffle.read_ident(body, cursor)
if not field_ident then return nil, type_end + 1 end
return {
name = field_ident,
type_name = type_name,
pointer_depth = depth,
-- offset + byte_size filled by resolve_struct_field_sizes
offset = nil,
byte_size = nil,
}, field_end
end)
end
-- Parse the `Enum_(<underlying>, <name>) { <body> }` body for entries.
-- Captures one field per named enumerator with the shape { name, value } value is the integer literal parsed from the source.
-- Returns the fields array (may be empty for `enum { }` shapes).
-- Self-contained integer parser (no upvalue on parse_enum_int_literal which lives further down in the file).
-- Captures one field per named enumerator with the shape { name, value }.
-- The value is the integer literal parsed from the source via the canonical `parse_enum_int_literal`.
local function parse_enum_body_fields(body)
local fields = {}
local body_pos = 1
local body_len = #body
while body_pos <= body_len do
body_pos = duffle.skip_ws_and_cmt(body, body_pos)
if body_pos > body_len then break end
local entry_name, name_end = duffle.read_ident(body, body_pos)
if not entry_name then
body_pos = body_pos + 1
else
local after_name = duffle.skip_ws_and_cmt(body, name_end)
local value
if body:sub(after_name, after_name) == "=" then
local val_pos = duffle.skip_ws_and_cmt(body, after_name + 1)
-- Self-contained integer literal parse (decimal, negative, hex).
-- Mirrors parse_enum_int_literal for the subset of shapes that appear in `typedef Enum_(...)` bodies.
local sign = 1
local p = val_pos
if p <= body_len and body:sub(p, p) == "-" then
sign = -1
p = p + 1
end
local start_digit = p
-- Hex form `0xNN` / `0XNN`.
local hex_value
if p + 1 <= body_len and body:sub(p, p) == "0"
and (body:sub(p + 1, p + 1) == "x"
or body:sub(p + 1, p + 1) == "X") then
p = p + 2
hex_value = 0
local any_hex = false
while p <= body_len do
local c = body:byte(p)
local d
if c >= 0x30 and c <= 0x39 then d = c - 0x30
elseif c >= 0x61 and c <= 0x66 then d = c - 0x61 + 10
elseif c >= 0x41 and c <= 0x46 then d = c - 0x41 + 10
else break end
hex_value = hex_value * 16 + d
p = p + 1
any_hex = true
end
if any_hex then value = sign * hex_value end
elseif start_digit <= body_len and body:sub(start_digit, start_digit):match("[%d]") then
-- Decimal form.
local dec_value = 0
local any_digit = false
while p <= body_len do
local c = body:byte(p)
if c < 0x30 or c > 0x39 then break end
dec_value = dec_value * 10 + (c - 0x30)
p = p + 1
any_digit = true
end
if any_digit then value = sign * dec_value end
end
if value ~= nil then
body_pos = p
else
body_pos = after_name + 1
end
return walk_body_fields(body, function(entry_name, name_end, after_name)
local value
local new_pos
if body:sub(after_name, after_name) == "=" then
local val_pos = duffle.skip_ws_and_cmt(body, after_name + 1)
local v, end_pos = parse_enum_int_literal(body, val_pos)
if v ~= nil then
value = v
new_pos = end_pos
else
body_pos = name_end
new_pos = after_name + 1
end
fields[#fields + 1] = { name = entry_name, value = value }
else
new_pos = name_end
end
-- Skip past any trailing comma.
body_pos = duffle.skip_ws_and_cmt(body, body_pos)
if body_pos <= body_len and body:sub(body_pos, body_pos) == "," then
body_pos = body_pos + 1
end
end
return fields
return { name = entry_name, value = value }, new_pos
end)
end
-- Resolve a typedef chain's `byte_size` via repeated underlying_type walks.
@@ -445,7 +417,7 @@ local function propagate_type_sizes(out)
local reg = out.type_name_registry
if not reg then return end
-- Phase 1: seed builtin primitives (U1/U2/U4/S1/S2/S4 + __UINT*_TYPE__ family).
-- Seed builtin primitives (U1/U2/U4/S1/S2/S4 + __UINT*_TYPE__ family).
for name, size in pairs(BUILTIN_BYTE_SIZES) do
if reg[name] and reg[name].byte_size == nil then
reg[name].byte_size = size
@@ -559,9 +531,6 @@ end
-- parens like `V4_S2*()`), the function still returns the leading reg_name but sets `malformed_flag = true` and `override_entry = nil`
-- so the caller can silently drop the override while keeping the register in the reads/writes list
-- (per the parser-safety contract — "malformed atom_type MUST NOT create any override").
--
-- The legacy `atom_rtype(...)` spelling is accepted as a transparent alias so test fixtures
-- authored against the pre-Track-A grammar continue to parse. Canonical: `atom_type`.
local function parse_atom_info_reg_entry(entry)
local pos = 1
pos = duffle.skip_ws_and_cmt(entry, pos)
@@ -573,9 +542,8 @@ local function parse_atom_info_reg_entry(entry)
if pos > #entry then return reg_name, nil, false end
-- Adjacent ident must be a bare `atom_type` (word-bounded both sides).
-- `atom_rtype` is the legacy alias; matches silently.
local next_ident, next_end = duffle.read_ident(entry, pos)
if not next_ident or (next_ident ~= "atom_type" and next_ident ~= "atom_rtype") then
if not next_ident or next_ident ~= "atom_type" then
return reg_name, nil, false
end
-- Left word-boundary: `_atom_type` should NOT match `atom_type`.
@@ -620,15 +588,91 @@ end
-- Returns (binds, reads, writes, view_binds, reg_overrides, ctx_atom_name, phase_label).
-- `view_binds` is the Binds_X ident from `atom_view(Binds_X)`.
-- `reg_overrides` is a {reg_name = {reg, type_name, pointer_depth, source_line}}
-- table populated from BOTH `atom_reg_types(R_X, <type>)` (legacy) and `atom_type(...)` sub-entries inside `atom_reads(...)` / `atom_writes(...)`.
-- table populated from `atom_reg_types(R_X, <type>)` and `atom_type(...)` sub-entries inside `atom_reads(...)` / `atom_writes(...)`.
-- `ctx_atom_name` is the rbind atom ident from `atom_ctx(<atom_name>)` (singular; last-write-wins).
-- `phase_label` is the user-authored C-ident label from `atom_phase(<label>)` (singular; last-write-wins).
-- `info_line` is the 1-based line of the enclosing `atom_info(...)` call;
-- It is recorded as `source_line` on every override entry so downstream passes can locate the declaration.
local function scan_atom_info_subcalls(info_inner, info_line)
local binds, reads, writes = nil, nil, nil
local view_binds, reg_overrides = nil, nil
local binds, reads, writes = nil, nil, nil
local view_binds, reg_overrides = nil, nil
local ctx_atom_name, phase_label = nil, nil
-- Per-subcall handler table. Each handler takes (sub_inner, info_line) and mutates the outer locals above.
-- atom_reads/atom_writes share a handler (same shape; just different output target).
local function rw_handler(sub_inner, info_line, kind)
-- The reads/writes arrays contain ONLY register idents;
-- the `atom_type(...)` sub-entry (when present and well-formed) is recorded as a per-atom reg_type_override.
local entries = duffle.split_top_level_commas(sub_inner)
local regs = {}
for _, entry in ipairs(entries) do
local reg_name, override, malformed = parse_atom_info_reg_entry(entry)
if reg_name then
regs[#regs + 1] = reg_name
if override then
reg_overrides = reg_overrides or {}
reg_overrides[reg_name] = {
reg = reg_name,
type_name = override.type_name,
pointer_depth = override.pointer_depth,
source_line = info_line,
}
end
-- malformed = silent: plain register still recorded; no override.
end
end
if kind == "atom_reads" then reads = regs else writes = regs end
end
local function ident_handler(sub_inner, info_line, out_name)
-- Validates the arg is a single C identifier (no commas / parens / whitespace).
-- Silently reject malformed args; the DWARF chain treats the field as un-set.
local name = duffle.read_ident(sub_inner, 1)
if name then
local after_id = duffle.skip_ws_and_cmt(sub_inner, 1 + #name)
if after_id > #sub_inner then
if out_name == "ctx_atom_name" then ctx_atom_name = name
elseif out_name == "phase_label" then phase_label = name end
end
end
end
local function reg_types_handler(sub_inner, info_line)
local args = duffle.split_top_level_commas(sub_inner)
if not args[1] then return end
reg_overrides = reg_overrides or {}
local reg_name = duffle.trim(args[1])
local type_name, depth = nil, 0
if args[2] then
local parsed_name, parsed_depth = parse_type_chain(args[2], 1)
if parsed_name then
type_name, depth = parsed_name, parsed_depth
else
type_name, depth = duffle.trim(args[2]), 0
end
end
reg_overrides[reg_name] = {
reg = reg_name,
type_name = type_name,
pointer_depth = depth,
source_line = info_line,
}
end
local SUBCALL_HANDLERS = {
-- scan: atom_bind(<Binds_X>)
atom_bind = function(sub_inner) binds = duffle.trim(sub_inner) end,
-- scan: atom_reads(<R_X [atom_type(<T>)], ...>)
atom_reads = function(sub_inner, info_line) rw_handler(sub_inner, info_line, "atom_reads") end,
-- scan: atom_writes(<R_X [atom_type(<T>)], ...>)
atom_writes = function(sub_inner, info_line) rw_handler(sub_inner, info_line, "atom_writes") end,
-- scan: atom_view(<Binds_X>)
atom_view = function(sub_inner) view_binds = duffle.trim(sub_inner) end,
-- scan: atom_reg_types(<R_X>, <T>)
atom_reg_types = reg_types_handler,
-- scan: atom_ctx(<atom_name>)
atom_ctx = function(sub_inner, info_line) ident_handler(sub_inner, info_line, "ctx_atom_name") end,
-- scan: atom_phase(<label>)
atom_phase = function(sub_inner, info_line) ident_handler(sub_inner, info_line, "phase_label") end,
}
local sub_pos = 1
while sub_pos <= #info_inner do
sub_pos = duffle.skip_ws_and_cmt(info_inner, sub_pos)
@@ -636,118 +680,16 @@ local function scan_atom_info_subcalls(info_inner, info_line)
local sub_ident, sub_end = duffle.read_ident(info_inner, sub_pos)
if not sub_ident then
sub_pos = sub_pos + 1
elseif sub_ident == "atom_bind" then
local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
if info_inner:sub(sub_open, sub_open) == "(" then
local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
-- scan: atom_bind(<Binds_X>)
binds = duffle.trim(sub_inner)
sub_pos = sub_after2
else
sub_pos = sub_open + 1
end
elseif sub_ident == "atom_reads" or sub_ident == "atom_writes" then
local kind = sub_ident
local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
if info_inner:sub(sub_open, sub_open) == "(" then
local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
-- scan: atom_reads(<R_X [atom_type(<T>)], ...>) OR atom_writes(<R_X [atom_type(<T>)], ...>)
-- The reads/writes arrays contain ONLY register idents;
-- the `atom_type(...)` sub-entry (when present and well-formed) is recorded as a per-atom reg_type_override.
local entries = read_top_level_args(sub_inner, 1)
local regs = {}
for _, entry in ipairs(entries) do
local reg_name, override, malformed = parse_atom_info_reg_entry(entry)
if reg_name then
regs[#regs + 1] = reg_name
if override then
reg_overrides = reg_overrides or {}
reg_overrides[reg_name] = {
reg = reg_name,
type_name = override.type_name,
pointer_depth = override.pointer_depth,
source_line = info_line,
}
end
-- malformed = silent: plain register still recorded; no override.
end
end
if kind == "atom_reads" then reads = regs else writes = regs end
sub_pos = sub_after2
else
sub_pos = sub_open + 1
end
elseif sub_ident == "atom_view" then
local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
if info_inner:sub(sub_open, sub_open) == "(" then
local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
view_binds = duffle.trim(sub_inner)
sub_pos = sub_after2
else
sub_pos = sub_open + 1
end
elseif sub_ident == "atom_reg_types" then
local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
if info_inner:sub(sub_open, sub_open) == "(" then
local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
local args = read_top_level_args(sub_inner, 1)
if args[1] then
reg_overrides = reg_overrides or {}
local reg_name = duffle.trim(args[1])
local type_name, depth = nil, 0
if args[2] then
local parsed_name, parsed_depth = parse_type_chain(args[2], 1)
if parsed_name then
type_name, depth = parsed_name, parsed_depth
else
type_name, depth = duffle.trim(args[2]), 0
end
end
reg_overrides[reg_name] = {
reg = reg_name,
type_name = type_name,
pointer_depth = depth,
source_line = info_line,
}
end
sub_pos = sub_after2
else
sub_pos = sub_open + 1
end
elseif sub_ident == "atom_ctx" then
-- scan: atom_ctx(<atom_name>)
-- The argument must be a single C identifier (no commas, no parens, no whitespace inside).
-- Anything else is silently rejected (no `ctx_atom_name` is set) so the DWARF chain falls through.
local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
if info_inner:sub(sub_open, sub_open) == "(" then
local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
local name = duffle.read_ident(sub_inner, 1)
if name then
local after_id = duffle.skip_ws_and_cmt(sub_inner, 1 + #name)
if after_id > #sub_inner then ctx_atom_name = name end
end
sub_pos = sub_after2
else
sub_pos = sub_open + 1
end
elseif sub_ident == "atom_phase" then
-- scan: atom_phase(<label>)
-- The argument is a free-form C identifier label (atomic single ident; no commas / parens / whitespace inside).
-- Silently reject malformed args; the DWARF chain treats the atom as un-grouped.
local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
if info_inner:sub(sub_open, sub_open) == "(" then
local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
local name = duffle.read_ident(sub_inner, 1)
if name then
local after_id = duffle.skip_ws_and_cmt(sub_inner, 1 + #name)
if after_id > #sub_inner then phase_label = name end
end
sub_pos = sub_after2
else
sub_pos = sub_open + 1
end
else
sub_pos = sub_end
local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end)
if info_inner:sub(sub_open, sub_open) == "(" then
local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open)
local handler = SUBCALL_HANDLERS[sub_ident]
if handler then handler(sub_inner, info_line) end
sub_pos = sub_after2
else
sub_pos = sub_open + 1
end
end
end
return binds, reads, writes, view_binds, reg_overrides, ctx_atom_name, phase_label
@@ -767,7 +709,7 @@ end
-- Track A helpers: enum / atom_reg / R_*_Code parsing
-- ════════════════════════════════════════════════════════════════════════════
--
-- The Track A parser walks `enum { <body> }` declarations and emits one AliasEntry per R_* entry whose value is followed by a bare `atom_reg` token.
-- The parser walks `enum { <body> }` declarations and emits one AliasEntry per R_* entry whose value is followed by a bare `atom_reg` token.
-- Value resolution handles decimal/negative/hex literals and `R_*_Code` symbol references;
-- symbol references resolve via the cross-source `_code_macros` registry built in two passes by `M.run`.
@@ -1027,7 +969,7 @@ local function parse_enum_atom_type_default(body, pos)
if pos > #body then return nil, 0, pos end
-- Bare `atom_type` word with word-bounding on both sides.
local ident, ident_end = duffle.read_ident(body, pos)
if ident ~= "atom_type" and ident ~= "atom_rtype" then return nil, 0, pos end
if ident ~= "atom_type" then return nil, 0, pos end
if pos > 1 then
local prev = body:byte(pos - 1)
if duffle.is_alnum_byte(prev) then return nil, 0, pos end
@@ -1075,17 +1017,19 @@ end
-- Adding a new construct = 1 row in DECL_PARSERS + 1 parser function. The scan_source() loop never needs editing.
--- Parse an empty debug-skip marker and retain its raw placement evidence.
--- The marker_kind is the source ident itself (e.g. `atom_dbg_skip_over`).
--- The dispatch table maps each ident to this same function;
--- the marker_kind is derived from the source so future idents route through the same row.
--- @param source string
--- @param pos integer
--- @param ident_end integer
--- @param line_of fun(pos: integer): integer
--- @param out SourceScan
--- @param marker_kind string
--- @return integer
local function parse_skip_over_marker(source, pos, ident_end, line_of, out, marker_kind)
local function parse_skip_over_marker(source, pos, ident_end, line_of, out)
local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
local marker = {
marker_kind = marker_kind,
marker_kind = source:sub(pos, ident_end - 1),
marker_line = line_of(pos),
marker_pos = pos,
after_paren = ident_end,
@@ -1102,17 +1046,12 @@ local function parse_skip_over_marker(source, pos, ident_end, line_of, out, mark
return marker.after_paren
end
local function parse_atom_dbg_skip_over(source, pos, ident_end, line_of, out)
return parse_skip_over_marker(source, pos, ident_end, line_of, out, "atom_dbg_skip_over")
end
-- Parse `atom_dbg_reg_default(R_X, <type>...)`;
-- the second argument may be a `Type` or `Type*`/`Type**` chain. Records in `out.types[R_X]`.
local function parse_atom_dbg_reg_default(source, pos, ident_end, line_of, out)
local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
if source:sub(open_paren, open_paren) ~= "(" then return open_paren + 1 end
local inner, after_paren = duffle.read_parens(source, open_paren)
local args = read_top_level_args(inner, 1)
local inner, after_paren = read_parens_after(source, ident_end)
if not inner then return after_paren end
local args = duffle.split_top_level_commas(inner)
if #args < 1 then
-- Annotation pass surfaces this; we still consume the marker.
return after_paren
@@ -1144,9 +1083,8 @@ end
--- @param out SourceScan
--- @return integer
local function parse_mips_atom(source, pos, ident_end, line_of, out)
local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
if source:sub(open_paren, open_paren) ~= "(" then return open_paren + 1 end
local inner, after_paren = duffle.read_parens(source, open_paren)
local inner, after_paren, open_paren = read_parens_after(source, ident_end)
if not inner then return after_paren end
local raw_name = duffle.read_ident(inner, 1)
@@ -1198,18 +1136,10 @@ local function parse_mips_atom(source, pos, ident_end, line_of, out)
end
end
local brace = duffle.scan_to_char(source, "{", brace_search_pos)
if not brace then return open_paren + 1 end
local body, after_brace = duffle.read_braces(source, brace)
local body, after_brace, body_off = find_body_braces(source, brace_search_pos, open_paren + 1)
if not body then return after_brace end
if raw_name and raw_name ~= "" then
local declaration_line = line_of(pos)
out.atoms[#out.atoms + 1] = {
line = declaration_line, name = raw_name, body = body, body_off = brace + 1,
kind = "atom", raw_name = raw_name,
ident_pos = pos, after_paren = after_paren,
}
associate_skip_over_marker(out, raw_name, raw_name, "atom", declaration_line, pos)
register_atom(out, "atom", line_of(pos), raw_name, body, body_off, raw_name, pos, after_paren)
end
return after_brace
@@ -1223,26 +1153,16 @@ end
--- @param out SourceScan
--- @return integer
local function parse_mips_atom_comp(source, pos, ident_end, line_of, out)
local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
if source:sub(open_paren, open_paren) ~= "(" then return open_paren + 1 end
local inner, after_paren = duffle.read_parens(source, open_paren)
local inner, after_paren, open_paren = read_parens_after(source, ident_end)
if not inner then return after_paren end
local raw_name = duffle.read_ident(inner, 1)
if not raw_name then return open_paren + 1 end
local brace = duffle.scan_to_char(source, "{", after_paren)
if not brace then return open_paren + 1 end
local body, after_brace = duffle.read_braces(source, brace)
local name = strip_ac_prefix(raw_name)
local declaration_line = line_of(pos)
out.atoms[#out.atoms + 1] = {
line = declaration_line, name = name, body = body, body_off = brace + 1,
kind = "comp_bare", raw_name = raw_name,
ident_pos = pos, after_paren = after_paren,
}
associate_skip_over_marker(out, name, raw_name, "comp_bare", declaration_line, pos)
local body, after_brace, body_off = find_body_braces(source, after_paren, open_paren + 1)
if not body then return after_brace end
local name = strip_ac_prefix(raw_name)
register_atom(out, "comp_bare", line_of(pos), name, body, body_off, raw_name, pos, after_paren)
return after_brace
end
@@ -1255,9 +1175,8 @@ end
--- @param out SourceScan
--- @return integer
local function parse_mips_atom_comp_proc(source, pos, ident_end, line_of, out)
local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
if source:sub(open_paren, open_paren) ~= "(" then return open_paren + 1 end
local inner, after_paren = duffle.read_parens(source, open_paren)
local inner, after_paren, open_paren = read_parens_after(source, ident_end)
if not inner then return after_paren end
-- Find the LAST `{` in inner (the body brace, not any potential embedded braces in expressions).
local last_brace_pos = nil
@@ -1274,16 +1193,10 @@ local function parse_mips_atom_comp_proc(source, pos, ident_end, line_of, out)
local raw_name = inner:match("^%s*([%w_]+)") or "?"
local name = strip_ac_prefix(raw_name)
local declaration_line = line_of(pos)
-- Position of body[1] in source = open_paren + 1 (start of inner) + last_brace_pos + 1 (past '{').
local body_off = open_paren + 2 + last_brace_pos
out.atoms[#out.atoms + 1] = {
line = declaration_line, name = name, body = body, body_off = body_off,
kind = "comp_proc", raw_name = raw_name,
ident_pos = pos, after_paren = after_paren,
}
associate_skip_over_marker(out, name, raw_name, "comp_proc", declaration_line, pos)
register_atom(out, "comp_proc", line_of(pos), name, body, body_off, raw_name, pos, after_paren)
return after_paren
end
@@ -1303,16 +1216,9 @@ local function parse_mips_code(source, pos, ident_end, line_of, out)
end
local atom_name = next_ident:sub(6)
local brace_pos = duffle.scan_to_char(source, "{", next_after)
if not brace_pos then return ident_end end
local body, after_brace = duffle.read_braces(source, brace_pos)
local declaration_line = line_of(pos)
out.raw_atoms[#out.raw_atoms + 1] = {
line = declaration_line, name = atom_name, body = body, body_off = brace_pos + 1,
kind = "raw_atom", raw_name = atom_name,
}
associate_skip_over_marker(out, atom_name, next_ident, "unrelated", declaration_line, pos)
local body, after_brace, body_off = find_body_braces(source, next_after, ident_end)
if not body then return after_brace end
register_raw_atom(out, line_of(pos), atom_name, body, body_off, atom_name, pos, "unrelated")
return after_brace
end
@@ -1425,16 +1331,12 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
-- ── Shape 1: `typedef Struct_(<name>) { <body> } <alias>;` ────────────
if id2 == "Struct_" then
local open_paren = duffle.skip_ws_and_cmt(source, id2_end)
if source:sub(open_paren, open_paren) ~= "(" then return id2_end end
local inner, after_paren = duffle.read_parens(source, open_paren)
local inner, after_paren, open_paren = read_parens_after(source, id2_end, id2_end)
if not inner then return id2_end end
local name = duffle.trim(inner)
local brace = duffle.scan_to_char(source, "{", after_paren)
if not brace then return open_paren + 1 end
local body, after_brace = duffle.read_braces(source, brace)
local body, after_brace = find_body_braces(source, after_paren, open_paren + 1)
if not body then return after_brace end
register_struct_type(body, name, pos, line_of, out)
associate_skip_over_marker(out, name, name, "unrelated", line_of(pos), pos)
return after_brace
@@ -1442,20 +1344,16 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
-- ── Shape 2: `typedef Enum_(<underlying>, <name>) { <body> } <alias>;`
if id2 == "Enum_" then
local open_paren = duffle.skip_ws_and_cmt(source, id2_end)
if source:sub(open_paren, open_paren) ~= "(" then return id2_end end
local inner, after_paren = duffle.read_parens(source, open_paren)
local inner, after_paren, open_paren = read_parens_after(source, id2_end, id2_end)
if not inner then return id2_end end
-- Split `inner` on the first top-level comma into (<underlying>, <name>).
local args = read_top_level_args(inner, 1)
local args = duffle.split_top_level_commas(inner)
if #args < 2 then return after_paren end
local underlying = duffle.trim(args[1])
local name = duffle.trim(args[2])
local brace = duffle.scan_to_char(source, "{", after_paren)
if not brace then return open_paren + 1 end
local body, after_brace = duffle.read_braces(source, brace)
local body, after_brace = find_body_braces(source, after_paren, open_paren + 1)
if not body then return after_brace end
register_enum_type(underlying, name, body, pos, line_of, out)
associate_skip_over_marker(out, name, name, "unrelated", line_of(pos), pos)
return after_brace
@@ -1470,9 +1368,8 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
-- Shape 4: `typedef <type> TSet_(<name>);`
if id3 == "TSet_" then
local open_paren = duffle.skip_ws_and_cmt(source, id3_end)
if source:sub(open_paren, open_paren) ~= "(" then return id3_end end
local tset_inner, tset_after = duffle.read_parens(source, open_paren)
local tset_inner, tset_after = read_parens_after(source, id3_end, id3_end)
if not tset_inner then return id3_end end
local tset_name = duffle.trim(tset_inner)
register_typedef_alias(id2, tset_name, pos, line_of, out)
associate_skip_over_marker(out, tset_name, tset_name, "unrelated", line_of(pos), pos)
@@ -1493,10 +1390,8 @@ end
--- @param out SourceScan
--- @return integer
local function parse_pragma_macro(source, pos, ident_end, line_of, out)
local open_paren = duffle.skip_ws_and_cmt(source, ident_end)
if source:sub(open_paren, open_paren) ~= "(" then return open_paren + 1 end
local str, str_end = duffle.read_parens(source, open_paren)
local str, str_end = read_parens_after(source, ident_end)
if not str then return str_end end
str = duffle.trim(str)
if str:sub(1, 1) ~= '"' or str:sub(-1) ~= '"' then return str_end end
@@ -1561,12 +1456,11 @@ local function parse_enum_value(body, pos, out)
return nil, pos
end
-- Walk one enum entry: read value, check for bare `atom_reg`,
-- and (if both are present and the name starts with `R_`) write an AliasEntry into `out.register_alias_registry`.
-- Walk one enum entry: read value, check for bare `atom_reg`, and
-- (if both are present and the name starts with `R_`) write an AliasEntry into `out.register_alias_registry`.
-- If `atom_reg` is followed by an adjacent `atom_type(<T>)`, the parsed T is stored on the AliasEntry
-- as `default_type` (type_name + pointer_depth). Silent if `atom_type(...)` is malformed.
-- Returns the new byte position within `body` (advanced past `atom_type(...)` if well-formed, past `atom_reg` alone,
-- or past the value if neither was present).
-- Returns the new byte position within `body` (advanced past `atom_type(...)` if well-formed, past `atom_reg` alone, or past the value if neither was present).
local function parse_enum_entry(source, body, body_offset, line_of, out, entry_name, name_body_pos, value_start)
-- value_start is within `body`, just past the `=`.
local after_ws = duffle.skip_ws_and_cmt(body, value_start)
@@ -1662,11 +1556,9 @@ local function parse_enum(source, pos, ident_end, line_of, out)
end
-- Find the opening brace of the enum body.
local brace_pos = duffle.scan_to_char(source, "{", after_ident)
if not brace_pos then return ident_end end
local body, after_brace = duffle.read_braces(source, brace_pos)
parse_enum_body(source, body, brace_pos + 1, line_of, out)
local body, after_brace, body_off = find_body_braces(source, after_ident, ident_end)
if not body then return after_brace end
parse_enum_body(source, body, body_off, line_of, out)
return after_brace
end
@@ -1674,7 +1566,6 @@ end
-- ════════════════════════════════════════════════════════════════════════════
-- DECL_PARSERS — data-driven construct dispatch (the plex pattern)
-- ════════════════════════════════════════════════════════════════════════════
--
-- Each entry maps a leading ident to its parser function. The main scan_source() loop is one line of dispatch:
-- local parser = DECL_PARSERS[ident]; if parser then pos = parser(...) end
--
@@ -1684,7 +1575,7 @@ local DECL_PARSERS = {
MipsAtom_ = parse_mips_atom,
MipsAtomComp_ = parse_mips_atom_comp,
MipsAtomComp_Proc_ = parse_mips_atom_comp_proc,
atom_dbg_skip_over = parse_atom_dbg_skip_over,
atom_dbg_skip_over = parse_skip_over_marker,
atom_dbg_reg_default = parse_atom_dbg_reg_default,
MipsCode = parse_mips_code,
typedef = parse_typedef_binds,
@@ -1813,7 +1704,7 @@ local M = {}
--- Walk each source once and attach the fat SourceScan payload to `src.scan`.
--- No output files; this is a pure in-memory pre-processing pass.
---
--- Track A: runs in 3 phases.
--- Runs in 3 phases.
--- Pass 1a: `scan_source_pre_pass` over every source, populating the cross-source `ctx.shared._code_macros` AND `ctx.shared._code_macro_bodies` registries.
--- The bodies table holds the raw post-`=` text of every `#define R_*_Code` line (cross-source) so the chain walker can fall back when a
--- sdefining `#define` lives in a different source than the chain call site.
scripts/passes/static_analysis.lua
+13 -16
View File
@@ -11,8 +11,8 @@
--- 5. **per-atom cycle budget** — sum each atom body's instruction latencies (per `duffle.INSTRUCTION_LATENCY`); report total.
--- Per-source rules (registry-driven, added 2026-07-16):
--- 6. **enum_alias_membership** — every `R_X` referenced from `atom_dbg_reg_default`, `atom_reg_types`,
--- `atom_rtype(...)`, `atom_reads`, or `atom_writes` must be in `scan.register_alias_registry`. Missing -> warning.
--- 7. **atom_rtype_consistency** — every `reg_type_overrides[R_X].type_name` must resolve in `scan.type_name_registry`. Missing -> error.
--- `atom_type(...)`, `atom_reads`, or `atom_writes` must be in `scan.register_alias_registry`. Missing -> warning.
--- 7. **atom_type_consistency** — every `reg_type_overrides[R_X].type_name` must resolve in `scan.type_name_registry`. Missing -> error.
--- 8. **binds_no_substruct_deref** — every `load_word(R_A, R_B, O_(Type, Field))` and `store_word(...)` in every atom body
--- must reference a leaf scalar (pointer-to-struct counts as leaf; nested struct members do NOT). Missing -> warning (build continues).
--- 9. **reads_writes_alias_membership** — distinct check name duplicating #6's reads/writes coverage so the report can
@@ -92,8 +92,7 @@ local OUTPUT_EXTENSION = ".static_analysis.txt"
--- @field errors table[]
--- @field warnings table[]
--- @alias AtomName string -- lower_snake_case atom name
--- @alias MacroName string -- lower_snake_case macro identifier
--- @alias AtomName string -- lower_snake_case atom nameMacroName string -- lower_snake_case macro identifier
--- @alias CheckName string -- "gte_pipeline_fill" | "mac_yield_uniformity" | "abi_handoff" | "gpu_port_store_shape" | "per_atom_cycle_budget"
--- @class AtomBody
@@ -709,7 +708,6 @@ local function analyze_atom_paths(atom)
-- Mutate the pre-allocated `atom.paths` slot in place (caller owns the table).
-- Mega-struct move: a single source of truth for all per-atom path-analysis data,
-- instead of returning a fresh table that would just get copied onto 5 atom fields.
-- If a caller ever DIDN'T pre-allocate (legacy code path), fall back to a fresh slot.
local p = atom.paths or {}
p.cycles_min = cycles_min
p.cycles_max = cycles_max
@@ -742,10 +740,10 @@ local function check_per_atom_cycle_budget(atom, pipe_ctx, findings)
end
-- ════════════════════════════════════════════════════════════════════════════
-- Check #6: enum_alias_membership (Track A Task 13)
-- Check #6: enum_alias_membership
-- ════════════════════════════════════════════════════════════════════════════
-- Every R_X referenced from a debug-visible surface — atom_dbg_reg_default, atom_reg_types, atom_rtype sub-entries, atom_reads, atom_writes;
-- Every R_X referenced from a debug-visible surface — atom_dbg_reg_default, atom_reg_types, atom_type sub-entries, atom_reads, atom_writes;
-- MUST be present in `pipe_ctx.register_alias_registry`.
-- The registry is the source-derived answer to "is this R_X a real, opt-in alias?"
-- (populated by scan_source's `parse_enum_aliases` from `enum { R_X = N atom_reg }` declarations).
@@ -777,7 +775,7 @@ local function check_enum_alias_membership(_src, pipe_ctx, findings)
end
end
-- (b) atom_reg_types(R_X, T) + (c) atom_rtype(R_X, T) sub-entries both populate `ai.reg_type_overrides` (Track A Task 5 merge).
-- (b) atom_reg_types(R_X, T) + (c) atom_type(R_X, T) sub-entries both populate `ai.reg_type_overrides`.
-- (d) atom_reads(R_X) + (e) atom_writes(R_X) populate the reads/writes arrays.
-- All four are checked against the same registry; the per-rule dispatch iterates `ai` once and covers all three locations
-- so we don't re-walk atom_infos for each sub-check.
@@ -823,17 +821,16 @@ local function check_enum_alias_membership(_src, pipe_ctx, findings)
end
-- ════════════════════════════════════════════════════════════════════════════
-- Check #7: atom_type_consistency (Track A Task 13; legacy alias atom_rtype_consistency)
-- Check #7: atom_type_consistency
-- ════════════════════════════════════════════════════════════════════════════
-- Every `reg_type_overrides[R_X].type_name` (populated by BOTH `atom_reg_types(R_X, <type>)`
-- and `atom_type(R_X, <type>)` sub-entries inside atom_reads/atom_writes — legacy `atom_rtype` is
-- accepted as a transparent alias) MUST resolve to a `type_name_registry` entry.
-- and `atom_type(R_X, <type>)` sub-entries inside atom_reads/atom_writes) MUST resolve to a `type_name_registry` entry.
-- The registry is the source-derived answer to "is this type name declared in this translation unit?"
-- (populated by `typedef Struct_(...)`, `typedef Enum_(...)`, `typedef ... TSet_(...)` declarations).
-- Missing type names are errors (the build stops) so the user adds the typedef before re-running.
-- Per-source rule.
local function check_atom_rtype_consistency(_src, pipe_ctx, findings)
local function check_atom_type_consistency(_src, pipe_ctx, findings)
local type_registry = pipe_ctx.type_name_registry or {}
for _, ai in ipairs(pipe_ctx.atom_infos_list or {}) do
local info_line = ai.info_line or 0
@@ -843,7 +840,7 @@ local function check_atom_rtype_consistency(_src, pipe_ctx, findings)
if not ov.type_name or not type_registry[ov.type_name] then
findings[#findings + 1] = {
atom = atom_name, line = info_line,
check = "atom_rtype_consistency", kind = "error",
check = "atom_type_consistency", kind = "error",
msg = string.format(
"atom '%s' at line %d reg_type_overrides[%q] uses unknown type %q (not in type_name_registry)",
atom_name, info_line, reg, tostring(ov.type_name)),
@@ -855,7 +852,7 @@ local function check_atom_rtype_consistency(_src, pipe_ctx, findings)
end
-- ════════════════════════════════════════════════════════════════════════════
-- Check #8: binds_no_substruct_deref (Track A Task 13)
-- Check #8: binds_no_substruct_deref
-- ════════════════════════════════════════════════════════════════════════════
-- For every `load_word(R_A, R_B, O_(<Type>, <Field>))` and matching `store_word(...)` call in every atom body,
@@ -945,7 +942,7 @@ local function check_binds_no_substruct_deref(_src, pipe_ctx, findings)
end
-- ════════════════════════════════════════════════════════════════════════════
-- Check #9: reads_writes_alias_membership (Track A Task 13)
-- Check #9: reads_writes_alias_membership
-- ════════════════════════════════════════════════════════════════════════════
-- For every `atom_reads(R_X)` and `atom_writes(R_X)` entry in every `atom_infos` entry, the `R_X` MUST be present in `pipe_ctx.register_alias_registry`.
@@ -1005,7 +1002,7 @@ local CHECK_RULES = {
{ name = "gpu_portstore_shape", per_atom = check_gpu_portstore_shape },
{ name = "per_atom_cycle_budget", per_atom = check_per_atom_cycle_budget },
{ name = "enum_alias_membership", per_source = check_enum_alias_membership },
{ name = "atom_rtype_consistency", per_source = check_atom_rtype_consistency },
{ name = "atom_type_consistency", per_source = check_atom_type_consistency },
{ name = "binds_no_substruct_deref", per_source = check_binds_no_substruct_deref },
{ name = "reads_writes_alias_membership",per_source = check_reads_writes_alias_membership},
}
scripts/passes/word_count_eval.lua
-4
View File
@@ -15,7 +15,6 @@
-- ════════════════════════════════════════════════════════════════════════════
-- Resolve `arg[0]` to an absolute-ish script directory so that `require("duffle")` resolves against `scripts/` regardless of CWD.
-- Note: this boilerplate is duplicated in 6 other entry scripts; extraction target (`duffle.setup_package_path()`).
-- Bootstrap: see `ps1_meta.lua` for the rationale.
-- Bootstrap: load `scripts/duffle_paths.lua` (sets package.path + package.cpath).
-- Uses `debug.getinfo` to find this file's own directory, so it works both standalone and when require'd from the orchestrator.
@@ -28,9 +27,6 @@ local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua")
-- Constants
-- ════════════════════════════════════════════════════════════════════════════
-- Windows separator char — used by `fname:match` to recognize `.macs.h` files.
local PATH_SEP_BACKSLASH = "\\"
-- Required native extension: lfs (LuaFileSystem). Built by `update_deps.ps1` to
-- `toolchain/lfs/lfs.dll` and wired into package.cpath by `scripts/duffle_paths.lua`.
-- If lfs is missing, `require` throws — fail loud per the build-tool convention.
scripts/ps1_meta.lua
+408 -151
View File
@@ -17,10 +17,25 @@
-- Module-scope requires + package.path setup
-- ════════════════════════════════════════════════════════════════════════════
-- Bootstrap: load `duffle_paths.lua` via `arg[0]` (this script's own path).
-- That single statement: (a) sets `package.path` + `package.cpath` (via cached `git rev-parse`),
-- (b) at the bottom returns `require("duffle")`. So the dofile's return value is the duffle module.
local duffle = dofile((arg[0]:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
-- Bootstrap: load `duffle_paths.lua` via this script's own path.
-- Use `arg[0]` when this file is the entry script (`arg[0]` ends in
-- "ps1_meta.lua"); fall back to `debug.getinfo(1, "S").source` when this
-- file is being dofile()'d or require()'d (in which case `arg[0]` is the
-- *caller's* path, not ours).
--
-- That single statement: (a) sets `package.path` + `package.cpath`
-- (via cached `git rev-parse`), (b) at the bottom returns `require("duffle")`.
-- So the dofile's return value is the duffle module.
local _is_entry_script = arg and arg[0] and arg[0]:match("ps1_meta%.lua$") ~= nil
local _bootstrap_src
if _is_entry_script then
_bootstrap_src = arg[0]
else
-- debug.getinfo(1, "S").source returns "@<path>" for the current chunk;
-- strip the leading "@" so the directory match works in both cases.
_bootstrap_src = debug.getinfo(1, "S").source:sub(2)
end
local duffle = dofile((_bootstrap_src:match("(.*[/\\])") or "./") .. "duffle_paths.lua")
-- ════════════════════════════════════════════════════════════════════════════
-- Constants
@@ -49,6 +64,8 @@ local PASS_FLAG_DISPATCH_KEY = "__pass__"
--- @field module string -- module name passed to require()
--- @field kind string -- "shared" | "header-output" | "validation" | "report"
--- @field deps string[] -- names of upstream passes
--- @field groups string[]? -- OPTIONAL build-phase groups this pass is a root of
--- -- (e.g. { "pre-link" }, { "post-link" }); absent ⇒ dependency-only
--- @field desc string -- human description (used by --help + ASCII graph)
--- @field out PassOutput[] -- output paths (used by --dry-run + report)
@@ -100,18 +117,26 @@ local PASS_FLAG_DISPATCH_KEY = "__pass__"
-- PASSES table (data, not code) — the orchestrator's dep graph
-- ════════════════════════════════════════════════════════════════════════════
-- Build-phase groups: each PASSES row may declare membership in one or more
-- named groups via `groups = { ... }`. The CLI flags --pre-link and
-- --post-link request the *roots* of their group; topo_sort then closes
-- transitive dependencies from those roots, and dispatch_passes runs every
-- pass in the resulting closure without phase-filtering.
--
-- A row without a `groups` entry is dependency-only: it runs only when a
-- transitive dep requests it, but it remains directly requestable through
-- its explicit CLI flag (e.g. --atoms-source-map, --scan-source).
local PASSES = {
["scan-source"] = {
module = "passes.scan_source",
kind = "shared",
deps = {},
kind = "shared", deps = {},
desc = "Walk each source once; produce the fat SourceScan payload for downstream passes",
out = {},
},
["word-counts"] = {
module = "passes.word_count_eval",
kind = "shared",
deps = {},
kind = "shared", deps = {},
desc = "Build the shared metadata table (metadata.h + .macs.h)",
out = {},
},
@@ -136,6 +161,7 @@ local PASSES = {
module = "passes.offsets",
kind = "header-output",
deps = {"scan-source", "word-counts", "components"},
groups = { "pre-link" },
desc = "Compute branch offsets for atom_label / atom_offset",
out = { { kind = "header", path_template = "<source_dir>/gen/<basename>.offsets.h" } },
},
@@ -143,7 +169,7 @@ local PASSES = {
module = "passes.static_analysis",
kind = "validation",
deps = {"scan-source", "word-counts", "components"},
desc = "[FUTURE] GTE pipeline-fill, mac_yield uniformity, etc.",
desc = "Static analysis: GTE pipeline-fill, mac_yield uniformity, ABI handoff, GPU port-store shape, per-atom cycle budget, type consistency",
out = { { kind = "report", path_template = "<out_root>/<basename>.static_analysis.txt" } },
},
["atoms-source-map"] = {
@@ -160,6 +186,7 @@ local PASSES = {
module = "passes.dwarf_injection",
kind = "shared",
deps = {"scan-source", "atoms-source-map"},
groups = { "post-link" },
desc = "Inject per-atom .debug_line + .debug_aranges (F') + per-atom .debug_info subprogram + per-wave-context-reg .debug_info variables (G') into the ELF (post-link; writes 7 section .bin blobs plus one deterministic .gdbinit sidecar). (rbind composite) reads ctx.sources[i].scan to find atom_bind(Binds_X) atoms + their Binds_X struct fields; emits per-Binds_X DW_TAG_structure_type DIEs + per-rbind-atom DW_TAG_variable 'bind_args' DIEs with piece-chain DW_OP_bregN/DW_OP_piece location expressions.",
out = {
{ kind = "report", path_template = "<out_root>/<basename>.dwarf_line.bin" },
@@ -176,11 +203,56 @@ local PASSES = {
module = "passes.report",
kind = "report",
deps = {"annotation", "static-analysis"},
groups = { "pre-link" },
desc = "Render the per-project summary",
out = { { kind = "report", path_template = "<out_root>/annotation_validation.txt" } },
},
}
-- ────────────────────────────────────────────────────────────────────────────
-- Phase-root selection: derive the sorted set of roots belonging to a named
-- build-phase group, then append them to `args.requested_set`. topo_sort
-- closes the transitive deps from there; dispatch_passes runs every resolved
-- pass without phase-filtering.
-- ────────────────────────────────────────────────────────────────────────────
--- @param group_name string -- the build-phase group ("pre-link" | "post-link")
--- @return string[] -- sorted root pass names belonging to that group
local function roots_for_group(group_name)
local names = {}
for name, pass in pairs(PASSES) do
if pass.groups then
for _, g in ipairs(pass.groups) do
if g == group_name then
names[#names + 1] = name
break
end
end
end
end
table.sort(names)
return names
end
--- Append every root belonging to `group_name` to `args.requested_set`.
--- Errors loudly if no PASSES row declares the group, so a typo'd or
--- future-removed group name cannot silently fall through to pre-link
--- (or any other default) and dispatch nothing.
--- @param args ParsedArgs
--- @param group_name string
local function request_roots_for_group(args, group_name)
local roots = roots_for_group(group_name)
if #roots == 0 then
error(string.format(
"ps1_meta: build-phase group %q has zero roots in PASSES; "
.. "check PASSES rows for a `groups = { %q }` field",
group_name, group_name))
end
for _, name in ipairs(roots) do
args.requested_set[#args.requested_set + 1] = name
end
end
-- Pass-kind taxonomy: which kinds stop the build on errors?
local PASS_KIND_STOP_ON_ERROR = {
["shared"] = false,
@@ -190,6 +262,13 @@ local PASS_KIND_STOP_ON_ERROR = {
}
-- Closed set of CLI flags -> pass names.
-- Per-pass flags (e.g. --word-counts) live here; phase flags (--pre-link,
-- --post-link, --all) live in FLAG_HANDLERS because they own side effects
-- or invoke group-derivation logic. --dwarf-injection is *also* a per-pass
-- opt-in flag, but its selection + opt-in state are both owned by the
-- explicit FLAG_HANDLERS entry below (it sets args.flags.dwarf_injection
-- and appends "dwarf-injection" to requested_set), so it is intentionally
-- absent from this table.
local PASS_FLAG_TO_NAME = {
["--word-counts"] = "word-counts",
["--components"] = "components",
@@ -197,35 +276,27 @@ local PASS_FLAG_TO_NAME = {
["--offsets"] = "offsets",
["--static-analysis"] = "static-analysis",
["--atoms-source-map"] = "atoms-source-map",
["--dwarf-injection"] = "dwarf-injection",
["--report"] = "report",
["--scan-source"] = "scan-source",
["--all"] = ALL_PASSES_SENTINEL,
}
local ALL_PASS_NAMES = {
"scan-source",
"word-counts",
"components",
"annotation",
"offsets",
"static-analysis",
"atoms-source-map",
"dwarf-injection",
"report",
}
--- Append every pass name to args.requested_set. Used by --all and by the "default to --all if no pass flags were given" fallback.
--- Append every pass name to args.requested_set. Names are derived from
--- PASSES (no parallel name list); used by --all and by any caller that
--- wants the full closure.
--- @param args ParsedArgs
local function request_all_passes(args)
for _, n in ipairs(ALL_PASS_NAMES) do
local names = {}
for name in pairs(PASSES) do names[#names + 1] = name end
table.sort(names)
for _, n in ipairs(names) do
args.requested_set[#args.requested_set + 1] = n
end
end
-- Per-flag handlers. Each handler takes (args, argv, arg_idx) and returns the new arg_idx (so multi-arg flags like --source FILE advance it).
-- Returning nil + os.exit() handles termination flags (--help).
-- This replaces the 8-way `if/elseif/elseif...` chain that nested 4 levels deep and made the dispatch logic hard to scan.
-- This replaces the 8-way `if/elseif/elseif...` chain that nested 4 levels deep and made the dispatch logic hard to scan.
local FLAG_HANDLERS = {}
-- ════════════════════════════════════════════════════════════════════════════
@@ -240,16 +311,28 @@ ps1_meta.lua - Tape-atom metaprogram orchestrator
USAGE:
ps1_meta.lua [PASS_FLAGS] [COMMON_FLAGS]
PASS_FLAGS (pick one or more, or use --all):
--word-counts Load metadata.h + scan for existing .macs.h
--components Generate <module>/gen/<basename>.macs.h
--validate Run atom annotation DSL validation
--offsets Generate <module>/gen/<basename>.offsets.h
--atoms-source-map Generate <basename>.atoms.sourcemap.txt per source
--dwarf-injection Inject per-atom .debug_line + .debug_aranges (post-link, requires --elf)
--static-analysis [FUTURE] GTE pipeline-fill, mac_yield uniformity
--report Render per-project summary
--all Equivalent to all 6 flags above (default)
PASS_FLAGS:
Pick a phase or one-or-more individual passes:
--pre-link [phase; default] Run the pre-link group + transitive deps.
The root set is data-driven from each PASSES row's
`groups` field; no parallel name list is maintained.
--post-link [phase] Run the post-link group + transitive deps.
Requires --elf. Sets --gdb-runtime and --dwarf-injection
opt-in flags as well.
--all Select every row of the PASSES table. Pass-local opt-in
guards remain active, so --dwarf-injection still requires
--elf and --gdb-runtime still requires a runtime emission.
Or pick any subset:
--scan-source Scan sources into the fat SourceScan payload
--word-counts Load metadata.h + scan for existing .macs.h
--components Generate <module>/gen/<basename>.macs.h
--validate Run atom annotation DSL validation
--offsets Generate <module>/gen/<basename>.offsets.h
--atoms-source-map Generate <basename>.atoms.sourcemap.txt per source
--dwarf-injection [opt-in] Select the post-link dwarf-injection pass + set the
opt-in flag. Requires --elf.
--static-analysis Static analysis: GTE pipeline-fill, mac_yield, ABI handoff, cycle budget
--report Render per-project summary
COMMON_FLAGS:
--source FILE Source file to process (repeatable)
@@ -257,7 +340,6 @@ COMMON_FLAGS:
--out-root DIR Output root for reports (default: build/gen)
--project-root DIR Project root for .macs.h scan (default: dirname(metadata))
--gdb-runtime Also emit <out_root>/gdb_tape_atoms_runtime.gdb (post-link, requires --elf)
--dwarf-injection Opt in to DWARF injection (writes <basename>.dwarf_*.bin blobs for objcopy splice; requires --elf)
--elf PATH Path to linked .elf (for --gdb-runtime / --dwarf-injection)
--dry-run Print dep order + ASCII graph; exit 0 without running
--verbose Print per-pass debug output
@@ -269,7 +351,9 @@ EXIT CODES:
2 Metaprogram internal error
EXAMPLE:
ps1_meta.lua --all --metadata metadata.h --source code/foo.c --source code/bar.c
ps1_meta.lua --pre-link --metadata metadata.h --source code/foo.c --source code/bar.c
ps1_meta.lua --post-link --metadata metadata.h --source code/foo.c --source code/bar.c --elf build/hello_gte.elf
ps1_meta.lua --all --metadata metadata.h --source code/foo.c --source code/bar.c
]])
end
@@ -292,16 +376,35 @@ FLAG_HANDLERS["--out-root"] = function(args, argv, arg_idx) args.out_root
FLAG_HANDLERS["--project-root"] = function(args, argv, arg_idx) args.project_root = argv[arg_idx + 1]; return arg_idx + 1 end
-- Per-pass stash flags. Read by `passes/atoms_source_map.lua` to opt into the post-link gdb-runtime emission.
-- Same shape as the existing per-flag handlers:
-- mutates `args.flags` (which propagates into `ctx.flags`).
FLAG_HANDLERS["--gdb-runtime"] = function(args) args.flags = args.flags or {}; args.flags.gdb_runtime = true end
FLAG_HANDLERS["--elf"] = function(args, argv, arg_idx) args.flags = args.flags or {}; args.flags.elf_path = argv[arg_idx + 1]; return arg_idx + 1 end
-- F' track: enable DWARF injection (default OFF; opt-in via .vscode/launch.json or ps1_meta CLI).
-- Same shape as the existing per-flag handlers. mutates `args.flags` (which propagates into `ctx.flags`).
FLAG_HANDLERS["--gdb-runtime"] = function(args) args.flags = args.flags or {}; args.flags.gdb_runtime = true end
FLAG_HANDLERS["--elf"] = function(args, argv, arg_idx) args.flags = args.flags or {}; args.flags.elf_path = argv[arg_idx + 1]; return arg_idx + 1 end
-- Enable DWARF injection (default OFF). Opts in to the post-link pass and
-- sets the flag in one shot — the explicit handler below owns both
-- selection and opt-in state, so --dwarf-injection is intentionally absent
-- from PASS_FLAG_TO_NAME.
FLAG_HANDLERS["--dwarf-injection"] = function(args)
args.flags = args.flags or {}
args.flags = args.flags or {}
args.flags.dwarf_injection = true
args.requested_set[#args.requested_set + 1] = "dwarf-injection"
end
-- Build-phase flags: --pre-link and --post-link request the roots of their
-- declared groups (see roots_for_group). topo_sort closes transitive deps
-- from those roots; dispatch_passes runs every pass in the resolved
-- closure without phase-filtering.
FLAG_HANDLERS["--pre-link"] = function(args)
request_roots_for_group(args, "pre-link")
end
-- Batch post-link phase: gdb-runtime + dwarf-injection in one luajit cold
-- start. Sets the same opt-in flags as --gdb-runtime + --dwarf-injection
-- and selects the post-link build-phase group.
-- --elf is required; parse_args enforces it after all flags are parsed.
FLAG_HANDLERS["--post-link"] = function(args)
args.flags = args.flags or {}
args.flags.gdb_runtime = true
args.flags.dwarf_injection = true
request_roots_for_group(args, "post-link")
end
-- G' (atom locals) is now consolidated into --dwarf-injection; no separate flag.
@@ -345,8 +448,10 @@ local function parse_args(argv)
pos = pos + 1
end
-- Default: --all if no explicit pass flags.
if #args.requested_set == 0 then request_all_passes(args) end
-- Default: --pre-link if no explicit pass flags were given. The first
-- invocation of a build is always pre-link, so this avoids silently
-- also invoking post-link work in builds without an ELF artifact.
if #args.requested_set == 0 then request_roots_for_group(args, "pre-link") end
-- Defaults: project_root = dirname(metadata).
if args.metadata and not args.project_root then
@@ -366,6 +471,20 @@ local function parse_args(argv)
os.exit(EXIT_INTERNAL_ERROR)
end
-- Post-link opt-ins (--gdb-runtime, --dwarf-injection) write output that
-- depends on the linked ELF. Without --elf the metaprogram can't satisfy
-- those requests, so refuse loud and early. This covers the explicit
-- --post-link batch, --dwarf-injection by itself, and --gdb-runtime by
-- itself.
local flags = args.flags or {}
local elf_path = flags.elf_path
local has_elf = type(elf_path) == "string" and #elf_path > 0
local post_links = flags.gdb_runtime or flags.dwarf_injection
if post_links and not has_elf then
io.stderr:write("ps1_meta: --elf PATH is required for post-link output\n")
os.exit(EXIT_INTERNAL_ERROR)
end
return args
end
@@ -380,6 +499,8 @@ end
local function build_ctx(args)
local sources = {}
for _, path in ipairs(args.sources) do
-- lfs handles path metadata and directories, not file-content streams.
-- Keep this io.open local so this entry point preserves its tailored diagnostic and exit path below.
local f = io.open(path, "r")
if not f then
io.stderr:write("ps1_meta: cannot open --source " .. path .. "\n")
@@ -427,11 +548,17 @@ end
-- Topological sort (Kahn's algorithm + cycle detection)
-- ════════════════════════════════════════════════════════════════════════════
--- Compute the dep-closure of `requested_set`: include every pass name transitively required by the requested set.
--- Topologically sort the requested pass set, augmented with all transitive deps.
--- Detects cycles and errors out with details.
--- @param passes table<string, PassDescriptor>
--- @param requested_set string[]
--- @return table<string, boolean> -- set of pass names needed (including transitive deps)
local function dep_closure(passes, requested_set)
--- @return string[] -- execution order
---
--- Implementation note: the 4 algorithm phases (dep-closure, in-degree, ready-queue, sort) are inlined as 3 small blocks within this function.
--- Each was a 1-caller helper; the 2-caller rule doesn't apply, so inlining produces a single readable function
--- (plex: small patterns → shared, but only when shared; here they're not).
local function topo_sort(passes, requested_set)
-- Phase 1: dep-closure. Include every pass name transitively required by `requested_set`.
local needed = {}
for _, name in ipairs(requested_set) do needed[name] = true end
local changed = true
@@ -450,23 +577,8 @@ local function dep_closure(passes, requested_set)
end
end
end
return needed
end
--- Count entries in a hash table (Lua's `#t` doesn't work for hash tables).
--- @param t table
--- @return integer
local function count_entries(t)
local n = 0
for _ in pairs(t) do n = n + 1 end
return n
end
--- Compute in-degrees for the Kahn sort: for each pass in `needed`, the number of its deps that are also in `needed`.
--- @param passes table<string, PassDescriptor>
--- @param needed table<string, boolean>
--- @return table<string, integer>
local function compute_in_degrees(passes, needed)
-- Phase 2: in-degrees for Kahn's algorithm. For each pass in `needed`, the number of its deps that are also in `needed`.
local in_degree = {}
for name, _ in pairs(needed) do in_degree[name] = 0 end
for name, _ in pairs(needed) do
@@ -476,65 +588,41 @@ local function compute_in_degrees(passes, needed)
end
end
end
return in_degree
end
--- Seed the Kahn ready queue with passes whose in-degree is 0, sorted alphabetically for deterministic execution order.
-- @param in_degree table<string, integer>
--- @return string[]
local function seed_ready_queue(in_degree)
-- Phase 3: seed the ready queue with passes whose in-degree is 0, sorted alphabetically for deterministic order.
local ready = {}
for name, deg in pairs(in_degree) do
if deg == 0 then ready[#ready + 1] = name end
end
table.sort(ready)
return ready
end
-- (internal) Pop the next ready pass, decrement the in-degree of every remaining pass that depended on it
-- (inserting newly-zero-degree passes back into the ready queue), and append to `order`. Keeps `ready` sorted.
-- @param passes table<string, PassDescriptor>
-- @param needed table<string, boolean>
-- @param in_degree table<string, integer>
-- @param ready string[]
-- @param order string[]
local function process_next_ready(passes, needed, in_degree, ready, order)
local just_finished = table.remove(ready, 1)
order[#order + 1] = just_finished
for name, _ in pairs(needed) do
if name ~= just_finished then
for _, dep in ipairs(passes[name].deps) do
if dep == just_finished then
in_degree[name] = in_degree[name] - 1
if in_degree[name] == 0 then
ready[#ready + 1] = name
table.sort(ready)
-- Phase 4: drain the ready queue. For each popped pass, decrement the in-degree of every remaining pass that depended on it.
-- Newly-zero-degree passes are inserted back into the ready queue (kept sorted).
local order = {}
while #ready > 0 do
local just_finished = table.remove(ready, 1)
order[#order + 1] = just_finished
for name, _ in pairs(needed) do
if name ~= just_finished then
for _, dep in ipairs(passes[name].deps) do
if dep == just_finished then
in_degree[name] = in_degree[name] - 1
if in_degree[name] == 0 then
ready[#ready + 1] = name
table.sort(ready)
end
end
end
end
end
end
end
--- Topologically sort the requested pass set, augmented with all transitive deps.
--- Detects cycles and errors out with details.
--- @param passes table<string, PassDescriptor>
--- @param requested_set string[]
--- @return string[] -- execution order
local function topo_sort(passes, requested_set)
local needed = dep_closure(passes, requested_set)
local in_degree = compute_in_degrees(passes, needed)
local ready = seed_ready_queue(in_degree)
local order = {}
while #ready > 0 do
process_next_ready(passes, needed, in_degree, ready, order)
end
-- Cycle detection: if order doesn't include all needed passes, some are stuck with in_degree > 0
-- Cycle detection: if `order` doesn't include all needed passes, some are stuck with in_degree > 0
-- (the cycle closed on itself before Kahn could process them).
-- Without this check, a fully-closed cycle (e.g. A -> B -> A) would silently return an emspty order list, leaving the orchestrator to dispatch nothing.
if #order ~= count_entries(needed) then
-- Without this check, a fully-closed cycle (e.g. A -> B -> A) would silently return an empty order list, leaving the orchestrator to dispatch nothing.
local needed_count = 0
for _ in pairs(needed) do needed_count = needed_count + 1 end -- count hash entries; Lua's #t doesn't work
if #order ~= needed_count then
for name, deg in pairs(in_degree) do
if deg > 0 then
error("dependency cycle detected involving pass '" .. name .. "'")
@@ -552,16 +640,15 @@ end
--- Render the dep graph as ASCII art. Output width capped at 78 columns.
--- Falls back to the simpler "Resolved dependency order" list only if graph width exceeds terminal width.
--- @param passes table<string, PassDescriptor>
--- @param requested string[] -- originally-requested passes (subset of closed)
--- @param closed string[] -- dep-closed execution order
--- @return string
local function render_dep_graph(passes, requested, closed)
local function render_dep_graph(passes, closed)
local lines = {}
local function add(s) lines[#lines + 1] = s end
add("[ps1_meta] Resolved dependency order (closed under deps):")
for pass_idx, name in ipairs(closed) do
local p = passes[name]
local p = passes[name]
local deps_str = (#p.deps == 0) and "(no deps)" or
"(deps: " .. table.concat(p.deps, ", ") .. ")"
add(string.format(" %d. %-22s %-45s [%s]",
@@ -570,51 +657,204 @@ local function render_dep_graph(passes, requested, closed)
add("")
-- Data-driven ASCII graph built from the actual PASSES table.
-- Shows the source -> scan_source -> pass chain. Each pass is shown once; edges are "feeds into" arrows based on deps.
-- Kahn layers determine the row of each box; each pass becomes a 4-row
-- box (top border, name, kind+output-count, bottom border). Boxes in
-- the same layer are rendered side-by-side; layers are connected by a
-- 'v' marker row whose 'v' chars are centered under each box, indicating
-- the downward 'feeds into' direction.
--
-- Layout invariants enforced here:
-- * MAX_GRAPH_WIDTH = 78 cols: no emitted line exceeds this. The
-- "simplest" way to stay under the budget is to limit each sub-row
-- to MAX_BOXES_PER_ROW = 3 boxes; for the canonical 9-row PASSES
-- table the largest layer has 3 boxes, so no wrap engages today.
-- If a future layer grows past 3 boxes, the layer is split into
-- adjacent sub-rows (each ending in its own 'v'-marker row).
-- * No silent truncation: per-layer box width is computed from the
-- layer's widest content (max(name length, kind-suffix length))
-- plus a 1-char leading + 1-char trailing padding + 2 wall chars.
-- Long names widen the box; they are NEVER truncated.
-- * Collision-safety: every PASSES row has a unique name, kind, and
-- out-list, so two distinct passes cannot produce visually identical
-- boxes.
add("[ps1_meta] Pass graph (read top-to-bottom; edges = 'feeds into'):")
add("")
-- Compute which passes feed which other passes (reverse of deps).
local feeds = {} -- feeds[X] = list of passes that X feeds into
for _, name in ipairs(closed) do feeds[name] = {} end
for name, p in pairs(passes) do
for _, dep in ipairs(p.deps) do
if feeds[dep] then feeds[dep][#feeds[dep] + 1] = name end
-- Compute Kahn layer per pass: layer L = max(deps' layer) + 1, layer 0
-- for deps-less passes. Repeated sweeps until every pass in `closed` is
-- assigned (handles forward refs that resolve on the second pass).
local pass_layer, max_layer = {}, 0
local sorted_closed = {}
for _, name in ipairs(closed) do sorted_closed[#sorted_closed + 1] = name end
table.sort(sorted_closed)
local function assign_layers()
local assigned_count = 0
for _, name in ipairs(sorted_closed) do
if pass_layer[name] == nil then
local p = passes[name]
local max_dep, ready = -1, true
for _, dep in ipairs(p.deps) do
if pass_layer[dep] == nil then ready = false; break end
if pass_layer[dep] > max_dep then max_dep = pass_layer[dep] end
end
if ready then
pass_layer[name] = max_dep + 1
if pass_layer[name] > max_layer then max_layer = pass_layer[name] end
assigned_count = assigned_count + 1
end
end
end
return assigned_count
end
while assign_layers() > 0 do end
-- Defensive invariant: any unresolved pass is a bug. topo_sort already
-- errors on cycles before this point, so reaching here means a logic
-- error in the renderer (or a synthetic call that bypassed topo_sort).
-- Surface the failure loudly with the offending names; never silently
-- place unresolved passes at layer 0 (which would corrupt the graph).
local unresolved = {}
for _, name in ipairs(sorted_closed) do
if pass_layer[name] == nil then unresolved[#unresolved + 1] = name end
end
if #unresolved > 0 then
error("render_dep_graph: unresolved Kahn layer for pass(es): "
.. table.concat(unresolved, ", ")
.. "; topo_sort should have caught this earlier")
end
-- Bucket passes by layer; sort each bucket alphabetically for stability.
local layers = {}
for i = 0, max_layer do layers[i] = {} end
for _, name in ipairs(sorted_closed) do
layers[pass_layer[name]][#layers[pass_layer[name]] + 1] = name
end
for i = 0, max_layer do table.sort(layers[i]) end
-- Layout constants. Boxes in the same layer share the same width
-- (computed as the layer's widest content + padding + walls).
local MAX_GRAPH_WIDTH = 78
local MAX_BOXES_PER_ROW = 3
local GAP = 3
local function pad_right(s, width)
if #s >= width then return s:sub(1, width) end
return s .. string.rep(" ", width - #s)
end
-- Compute the box width (in chars, including both walls) for a layer.
-- The interior is the wider of (a) the longest pass name + 1 leading
-- space and (b) the longest "<kind> <N>" suffix + 1 leading space.
-- Then add 2 for the wall chars.
--
-- Why +1 (not +2): the +1 formula means the layer's max-content row
-- has 0 padding before the right wall (the `|` is immediately after
-- the content). This is the collision-safe widening policy the task
-- requires — long names widen the box and never get trailing padding.
-- Shorter passes in the same layer get trailing padding to fill the
-- interior to the layer's uniform width; they never get truncated.
local function box_w_for_layer(bucket)
local max_content = 0
for _, name in ipairs(bucket) do
local p = passes[name]
local out_n = #(p.out or {})
local kind_suf = string.format("%s %d>", p.kind, out_n)
if #name > max_content then max_content = #name end
if #kind_suf > max_content then max_content = #kind_suf end
end
-- Interior = 1 leading space + max_content + 0 trailing (the
-- trailing `|` IS the right boundary); walls = 2.
return max_content + 3
end
-- Render one pass as a 4-row box at the given box_w. The interior is
-- always padded to fit exactly; no string is ever truncated.
local function render_box(name, box_w)
local p = passes[name]
local out_n = #(p.out or {})
local kind_suf = string.format("%s %d>", p.kind, out_n)
local interior = box_w - 2
local border = "+" .. string.rep("-", interior) .. "+"
return {
border,
"|" .. pad_right(" " .. name, interior) .. "|",
"|" .. pad_right(" " .. kind_suf, interior) .. "|",
border,
}
end
-- Join a single row (1..4) across all boxes in a sub-row, with GAP
-- spaces between adjacent boxes.
local function join_row(box_rows, row_idx)
local parts = {}
for i, b in ipairs(box_rows) do
parts[#parts + 1] = b[row_idx]
if i < #box_rows then parts[#parts + 1] = string.rep(" ", GAP) end
end
return table.concat(parts)
end
-- 'v' marker row beneath a sub-row: one 'v' centered under each box.
local function v_marker_row(box_rows)
local total = 0
local centers = {}
for i, b in ipairs(box_rows) do
local w = #b[1] -- box width = length of the top border row
local center = total + math.floor(w / 2)
centers[#centers + 1] = center
total = total + w + GAP
end
-- total now includes a trailing GAP we don't want; trim it.
total = total - GAP
local s = string.rep(" ", total)
for _, c in ipairs(centers) do
s = s:sub(1, c) .. "v" .. s:sub(c + 2)
end
return s
end
-- Render a single sub-row (a contiguous chunk of a layer's bucket).
-- Emits the 4 box rows + an empty line + the 'v' marker row + an
-- empty line, EXCEPT the very last sub-row of the very last layer
-- omits the trailing 'v' marker (nothing flows below it).
local function render_subrow(bucket_chunk, is_last_subrow, is_last_layer)
local box_w = box_w_for_layer(bucket_chunk)
local boxes = {}
for _, name in ipairs(bucket_chunk) do boxes[#boxes + 1] = render_box(name, box_w) end
add(join_row(boxes, 1)) -- top borders
add(join_row(boxes, 2)) -- names
add(join_row(boxes, 3)) -- kind + output-count
add(join_row(boxes, 4)) -- bottom borders
-- 'v' marker row beneath this sub-row connects downward to the
-- next sub-row of the same layer (if any) OR to the next layer.
-- Skip the trailing 'v' only on the very last sub-row of the
-- final layer, where nothing flows below it.
if not is_last_subrow or not is_last_layer then
add("")
add(v_marker_row(boxes))
add("")
end
end
-- Layout: source -> scan_source -> word-counts -> {components, annotation, offsets, static-analysis} -> report
-- Outputs are listed under each pass.
local outputs_for = function(name)
local p = passes[name]
if not p or not p.out or #p.out == 0 then return "" end
local outs = {}
for _, o in ipairs(p.out) do outs[#outs + 1] = o.path_template end
return table.concat(outs, ", ")
for layer_idx = 0, max_layer do
local bucket = layers[layer_idx]
local is_last = (layer_idx == max_layer)
-- Split the layer into sub-rows of at most MAX_BOXES_PER_ROW boxes.
-- With a 20-char box width (the canonical case: name "static-analysis"
-- is 15 chars, suffix "header-output 2>" is 16 chars) and GAP=3,
-- 3 boxes per sub-row = 3*20 + 2*3 = 66 cols + a 'v' row of 66 cols;
-- well within MAX_GRAPH_WIDTH. A 4th box would push to 4*20 + 3*3 = 89,
-- which is why MAX_BOXES_PER_ROW = 3 (wrap when >3).
local chunk_size = math.min(MAX_BOXES_PER_ROW, #bucket)
if chunk_size < 1 then chunk_size = 1 end
for chunk_start = 1, #bucket, chunk_size do
local chunk_end = math.min(chunk_start + chunk_size - 1, #bucket)
local chunk = {}
for i = chunk_start, chunk_end do chunk[#chunk + 1] = bucket[i] end
local is_last_subrow = (chunk_end == #bucket)
render_subrow(chunk, is_last_subrow, is_last)
end
end
add(" +-----------+ +-------------------+ +-----------------+")
add(" | source |-->| scan_source |--->| word-counts |")
add(" | files | | (scan_source.lua) | | (load) |")
add(" +-----------+ +-------------------+ +-----------------+")
add(" (single walk) |")
add(" |")
add(" +-------------------+-------------------+-----------+")
add(" v v v v")
add(" +--------------+ +--------------+ +--------------+ +---------------+")
add(" | components | | annotation | | offsets | |static-analysis|")
add(" +--------------+ +--------------+ +--------------+ +---------------+")
add(" |<src>/gen/ | |build/gen/ | |<src>/gen/ | |build/gen/ |")
add(" |<base>.macs.h | |<base>.errors | |<base>.offsets| |<base>.static |")
add(" | (header) | | .h | | .h | | _analysis |")
add(" +------+-------+ | +annot.txt | | (header) | | .txt |")
add(" | +--+-----------+ +--------------+ +------+--------+")
add(" v v v")
add(" +------+----------------+ +------+-------+ |")
add(" |offsets|static-analysis| |report| |<--------------------+")
add(" | | | +------+-------+")
add(" +-------+---------------+")
return table.concat(lines, "\n") .. "\n"
end
@@ -663,6 +903,7 @@ local function dispatch_passes(ctx, order)
local had_errors = false
for _, pass_name in ipairs(order) do
local pass = PASSES[pass_name]
io.stderr:write(string.format("[ps1_meta] %-22s running\n", pass_name))
local mod = require(pass.module)
local result = mod.run(ctx)
@@ -686,7 +927,7 @@ local function main(argv)
-- --dry-run: print dep order + ASCII graph, exit OK.
if args.dry_run then
io.write(render_dep_graph(PASSES, requested, closed))
io.write(render_dep_graph(PASSES, closed))
os.exit(EXIT_OK)
end
@@ -702,4 +943,20 @@ local function main(argv)
os.exit(EXIT_OK)
end
main({...})
-- Module export for in-process consumers (tests that dofile this script).
-- The closure above, `render_dep_graph`, and the canonical `PASSES` table
-- are exposed so a test can render the graph for synthetic PASSES tables
-- without spawning a subprocess. The conditional `main(...)` call below
-- only fires when this file is invoked as the entry script (arg[0] ends
-- in "ps1_meta.lua"); in dofile() mode (test's arg[0] does not match),
-- main() is skipped and the chunk returns `_M` to the caller.
local _M = {
render_dep_graph = render_dep_graph,
PASSES = PASSES,
}
if arg and arg[0] and arg[0]:match("ps1_meta%.lua$") then
main({...})
end
return _M