ed/pikuma_ps1
1
0
Fork 0
mirror of https://github.com/Ed94/pikuma_ps1.git synced 2026-07-17 06:41:27 -07:00
Code Issues Packages Projects Releases Wiki Activity

TODO: need to review snapshot

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-07-14 12:16:00 -04:00
parent 2d901003f9
commit 7d5b13aadb
14 changed files with 2461 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/passes/scan_source.lua
+306 -18
View File
@@ -6,6 +6,7 @@
--- MipsAtom_ (kind = "atom", with optional atom_info inner)
--- MipsAtomComp_ (kind = "comp_bare")
--- MipsAtomComp_Proc_ (kind = "comp_proc", body inside last {})
--- atom_dbg_skip_over (whole-atom/component debug-step marker; following declaration disambiguates)
--- MipsCode code_<name> (kind = "raw_atom", offsets pass only)
--- typedef Struct_(Binds_X) { fields }
--- #pragma mac_X tape_atom words=N + _Pragma("...")
@@ -35,8 +36,55 @@ local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua")
--- @field binds BindsEntry[] -- typedef Struct_(Binds_X) { fields } (fields pre-parsed)
--- @field atom_infos AtomInfoEntry[] -- MipsAtom_(name) atom_info(...) (sub-calls pre-parsed)
--- @field macros MacroEntry[] -- #pragma mac_X tape_atom words=N + _Pragma("...")
--- @field skip_over SkipOverScan -- atom/component debug-step markers + resolved declaration associations
--- @field types table<string, RegTypeDefault> -- atom_dbg_reg_default(R_X, <type>) declarations
--- @field atom_views table<string, AtomViewEntry> -- MipsAtom_(name) -> {binds_name, reg_type_overrides, info_line}
--- @field line_of fun(pos: integer): integer -- shared LineIndex closure
--- @class SkipOverScan
--- @field atoms table<string, SkipOverAssociation>
--- @field components table<string, SkipOverAssociation>
--- @field markers SkipOverMarker[]
--- @class SkipOverMarker
--- @field marker_kind string -- exact marker ident (always "atom_dbg_skip_over")
--- @field marker_line integer
--- @field marker_pos integer
--- @field after_paren integer
--- @field args string|nil -- trimmed marker args; valid Task 13 markers use ""
--- @field has_parens boolean
--- @field pending boolean
--- @field superseded_by_marker_line integer|nil
--- @field target_name string|nil -- stripped declaration name once observed
--- @field target_raw_name string|nil -- source-written declaration name once observed
--- @field target_kind string|nil -- "atom" | "comp_bare" | "comp_proc" | "unrelated" once observed
--- @field declaration_line integer|nil
--- @field declaration_pos integer|nil
--- @field proc_prelude boolean|nil -- marker has crossed FI_ and awaits MipsAtomComp_Proc_
--- @class RegTypeDefault
--- @field name string -- "R_TapePtr" (the register ident; without the value part)
--- @field type_name string -- "U4" / "V3_S2" / "void" (the pointer/struct base name)
--- @field pointer_depth integer -- 0 for `U4`, 1 for `U4*`, 2 for `U4**`
--- @field source_line integer -- 1-based source line of the declaration
--- @class RegTypeOverride
--- @field reg string -- "R_T0"
--- @field type_name string
--- @field pointer_depth integer
--- @class AtomViewEntry
--- @field atom_name string -- e.g. "red_cube_g4_face"
--- @field binds_name string|nil -- "Binds_CubeTri" if attached
--- @field reg_type_overrides table<string, RegTypeOverride> -- "R_T0" -> override
--- @field info_line integer -- line of the atom_info call
--- @class SkipOverAssociation
--- @field marker_line integer
--- @field declaration_line integer
--- @field kind string
--- @field marker SkipOverMarker
--- @class SourceFile
--- @field path string -- absolute path to the source file
--- @field text string -- the full source text
@@ -101,6 +149,94 @@ local function strip_ac_prefix(raw_name)
return raw_name
end
-- Preserve a source marker until the following declaration parser observes it.
-- Task 13 records evidence only; Task 14 diagnoses non-empty args,
-- duplicates, dangling markers, and unrelated declaration placement.
local function push_skip_over_marker(out, marker)
local markers = out.skip_over.markers
local prior = markers[#markers]
if prior and prior.pending then
prior.pending = false
prior.superseded_by_marker_line = marker.marker_line
end
marker.pending = true
markers[#markers + 1] = marker
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.
local function associate_skip_over_marker(out, target_name, target_raw_name, target_kind, declaration_line, declaration_pos)
local markers = out.skip_over.markers
local marker = markers[#markers]
if not (marker and marker.pending) then return end
marker.pending = false
marker.target_name = target_name
marker.target_raw_name = target_raw_name
marker.target_kind = target_kind
marker.declaration_line = declaration_line
marker.declaration_pos = declaration_pos
if not (marker.has_parens and marker.args == "") then return end
local association = {
marker_line = marker.marker_line,
declaration_line = declaration_line,
kind = target_kind,
marker = marker,
}
if target_kind == "atom" then
out.skip_over.atoms[target_name] = association
elseif target_kind == "comp_bare" or target_kind == "comp_proc" then
out.skip_over.components[target_name] = association
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
end
-- Parse a `Type*` chain (zero or more `*` separated by optional whitespace)
-- followed by the type ident. Returns (type_name, pointer_depth) or nil.
local function parse_type_chain(text, pos)
if pos > #text then return nil end
-- Skip leading whitespace before the type ident.
local start = duffle.skip_ws_and_cmt(text, pos)
local ident, after = duffle.read_ident(text, start)
if not ident then return nil end
local depth = 0
local cursor = duffle.skip_ws_and_cmt(text, after)
while cursor <= #text and text:sub(cursor, cursor) == "*" do
depth = depth + 1
cursor = cursor + 1
cursor = duffle.skip_ws_and_cmt(text, cursor)
end
return ident, depth, cursor
end
-- Parse the U4 fields from a Binds_X body. Returns (fields, byte_count).
local function scan_binds_fields(body)
local fields = {}
@@ -146,10 +282,13 @@ local function scan_reg_list(sub_inner)
return regs
end
-- Parse the sub-calls inside `atom_info(atom_bind(...), atom_reads(...), atom_writes(...))`.
-- Returns (binds, reads, writes).
-- Parse the sub-calls inside `atom_info(atom_bind(...), atom_reads(...), atom_writes(...), atom_view(...), atom_reg_types(...))`.
-- Returns (binds, reads, writes, view_binds, reg_overrides).
-- `view_binds` is the Binds_X ident from `atom_view(Binds_X)`.
-- `reg_overrides` is a {reg_name = {type_name, pointer_depth}} table for `atom_reg_types(R_X, <type>)`.
local function scan_atom_info_subcalls(info_inner)
local binds, reads, writes = nil, nil, nil
local view_binds, reg_overrides = nil, nil
local sub_pos = 1
while sub_pos <= #info_inner do
sub_pos = duffle.skip_ws_and_cmt(info_inner, sub_pos)
@@ -179,11 +318,43 @@ local function scan_atom_info_subcalls(info_inner)
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] = { type_name = type_name, pointer_depth = depth }
end
sub_pos = sub_after2
else
sub_pos = sub_open + 1
end
else
sub_pos = sub_end
end
end
return binds, reads, writes
return binds, reads, writes, view_binds, reg_overrides
end
-- Skip C qualifier keywords and return the position past the last one.
@@ -207,7 +378,7 @@ end
-- pos -- position of the construct's leading ident (e.g., `M` of `MipsAtom_`)
-- ident_end -- position past the leading ident (where the `(` should be)
-- line_of -- closure over LineIndex(source) for 1-based line lookups
-- out -- the SourceScan out table (mutated in place: out.atoms / out.raw_atoms / out.binds / out.atom_infos / out.macros)
-- out -- the SourceScan out table (mutated in place: out.atoms / out.raw_atoms / out.binds / out.atom_infos / out.macros / out.skip_over)
-- returns -- new position after the construct
--
-- All parsers read source-as-written via the duffle primitives (skip_ws_and_cmt / read_parens / read_braces / read_balanced).
@@ -216,6 +387,68 @@ 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.
--- @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 open_paren = duffle.skip_ws_and_cmt(source, ident_end)
local marker = {
marker_kind = marker_kind,
marker_line = line_of(pos),
marker_pos = pos,
after_paren = ident_end,
args = nil,
has_parens = false,
}
if source:sub(open_paren, open_paren) == "(" then
local inner, after_paren = duffle.read_parens(source, open_paren)
marker.after_paren = after_paren
marker.args = duffle.trim(inner)
marker.has_parens = true
end
push_skip_over_marker(out, marker)
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)
if #args < 1 then
-- Annotation pass surfaces this; we still consume the marker.
return after_paren
end
local reg_name = duffle.trim(args[1])
local type_part = args[2] or "void"
local type_name, depth = parse_type_chain(type_part, 1)
if not type_name then type_name, depth = duffle.trim(type_part), 0 end
out.types[reg_name] = {
name = reg_name,
type_name = type_name,
pointer_depth = depth,
source_line = line_of(pos),
}
out.type_occurrences = out.type_occurrences or {}
out.type_occurrences[#out.type_occurrences + 1] = {
reg = reg_name,
type_name = type_name,
source_line = line_of(pos),
}
return after_paren
end
--- Parse: `MipsAtom_(<name>) [atom_info(<binds>, <reads>, <writes>)] { <body> }`
--- @param source string
--- @param pos integer
@@ -238,12 +471,27 @@ local function parse_mips_atom(source, pos, ident_end, line_of, out)
local info_open = duffle.skip_ws_and_cmt(source, look_end)
if source:sub(info_open, info_open) == "(" then
local info_inner, info_after = duffle.read_parens(source, info_open)
local ai_binds, ai_reads, ai_writes = scan_atom_info_subcalls(info_inner)
local ai_binds, ai_reads, ai_writes, ai_view, ai_overrides = scan_atom_info_subcalls(info_inner)
out.atom_infos[#out.atom_infos + 1] = {
atom_name = raw_name or "?", binds = ai_binds,
reads = ai_reads or {}, writes = ai_writes or {},
view = ai_view,
reg_type_overrides = ai_overrides,
info_line = line_of(lookahead),
}
if ai_view and raw_name then
out.atom_views[raw_name] = {
atom_name = raw_name,
binds_name = ai_view,
reg_type_overrides = ai_overrides,
info_line = line_of(lookahead),
}
elseif raw_name and ai_overrides then
-- Record per-atom overrides even without atom_view.
out.atom_views[raw_name] = out.atom_views[raw_name]
or { atom_name = raw_name, binds_name = nil, reg_type_overrides = nil, info_line = line_of(lookahead) }
out.atom_views[raw_name].reg_type_overrides = ai_overrides
end
brace_search_pos = info_after
end
end
@@ -253,11 +501,13 @@ local function parse_mips_atom(source, pos, ident_end, line_of, out)
local body, after_brace = duffle.read_braces(source, brace)
if raw_name and raw_name ~= "" then
local declaration_line = line_of(pos)
out.atoms[#out.atoms + 1] = {
line = line_of(pos), name = raw_name, body = body, body_off = brace + 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)
end
return after_brace
@@ -282,12 +532,15 @@ local function parse_mips_atom_comp(source, pos, ident_end, line_of, out)
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 = line_of(pos), name = strip_ac_prefix(raw_name), body = body, body_off = brace + 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)
return after_brace
end
@@ -318,14 +571,17 @@ local function parse_mips_atom_comp_proc(source, pos, ident_end, line_of, out)
if close_pos > #inner + 1 then return after_paren end
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 = line_of(pos), name = strip_ac_prefix(raw_name), body = body, body_off = body_off,
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)
return after_paren
end
@@ -349,10 +605,12 @@ local function parse_mips_code(source, pos, ident_end, line_of, out)
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 = line_of(pos), name = atom_name, body = body, body_off = brace_pos + 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)
return after_brace
end
@@ -383,6 +641,7 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
local fields, byte_off = scan_binds_fields(body)
out.binds[#out.binds + 1] = { line = line_of(pos), name = name, fields = fields, bytes = byte_off }
end
associate_skip_over_marker(out, name, name, "unrelated", line_of(pos), pos)
return after_brace
end
@@ -443,13 +702,15 @@ end
-- Adding a new construct = 1 row here + 1 parser function above.
local DECL_PARSERS = {
MipsAtom_ = parse_mips_atom,
MipsAtomComp_ = parse_mips_atom_comp,
MipsAtomComp_Proc_ = parse_mips_atom_comp_proc,
MipsCode = parse_mips_code,
typedef = parse_typedef_binds,
_Pragma = parse_pragma_macro,
pragma = parse_pragma_dummy,
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_reg_default = parse_atom_dbg_reg_default,
MipsCode = parse_mips_code,
typedef = parse_typedef_binds,
_Pragma = parse_pragma_macro,
pragma = parse_pragma_dummy,
}
-- ════════════════════════════════════════════════════════════════════════════
@@ -459,7 +720,7 @@ local DECL_PARSERS = {
--- Single-pass source scan. Walks the source ONCE and extracts every construct type the metaprogram passes need.
--- Returns a fat SourceScan table. Each pass filters from this payload instead of re-walking the source.
--- @param source string
--- @return table -- SourceScan { atoms, raw_atoms, binds, atom_infos, macros, line_of }
--- @return table -- SourceScan { atoms, raw_atoms, binds, atom_infos, macros, skip_over, line_of }
local function scan_source(source)
local line_of = duffle.LineIndex(source)
local out = {
@@ -468,6 +729,13 @@ local function scan_source(source)
binds = {},
atom_infos = {},
macros = {},
skip_over = {
atoms = {},
components = {},
markers = {},
},
types = {},
atom_views = {},
line_of = line_of,
}
local pos = 1
@@ -492,10 +760,30 @@ local function scan_source(source)
if parser then
pos = parser(source, pos, ident_end, line_of, out)
else
-- Unrecognized ident — advance past it.
-- A component-procedure declaration has an FI_ signature before
-- MipsAtomComp_Proc_; keep the marker pending across that prelude.
-- Any other identifier begins an unrelated declaration/construct
-- and consumes the marker so it cannot drift to a later atom.
local markers = out.skip_over.markers
local marker = markers[#markers]
if marker and marker.pending then
if ident == "FI_" then
marker.proc_prelude = true
elseif not marker.proc_prelude then
associate_skip_over_marker(out, ident, ident, "unrelated", line_of(pos), pos)
end
end
pos = ident_end
end
else
local markers = out.skip_over.markers
local marker = markers[#markers]
if marker and marker.pending and marker.proc_prelude then
local c = source:sub(pos, pos)
if c == "{" or c == ";" then
associate_skip_over_marker(out, c, c, "unrelated", line_of(pos), pos)
end
end
pos = pos + 1
end
end