admin/Toyota-AVC-LAN
1
0
Fork 0
mirror of https://github.com/halleysfifthinc/AVCLAN-Mockingboard.git synced 2026-08-07 01:13:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Establish the Lua dissector action/device/etc tables as authoritative

Browse Source 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Allen Hill
2026-07-06 16:53:13 -07:00
parent e92d61adca
commit b538e07577
9 changed files with 632 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/sync_avclan_enums.py
Executable
+541
View File
@@ -0,0 +1,541 @@
#!/usr/bin/env python3
"""Keep the C++ Device/Action enums in sync with the Lua dissector tables.
The Wireshark dissector in scripts/packet-analysis/avclan_plugin.lua is the
authoritative source of truth for AVC-LAN device and action names. Its
`known_devices` / `known_actions` tables and the firmware's C++ enums
(`enum class Device` in src/avclan/device.hpp, `enum ... Action` in
src/avclan/avclan.h) encode the same numeric values and drift apart by hand.
This tool reconciles them, matching entries *by value* so a value renamed in
the dissector is propagated into C++ (and to every reference under src/), not
just added/removed.
Default (no flags) lint the dissector names AND report enum drift; write
nothing; exit non-zero if either has problems. This is
what the pre-commit hook runs.
--fix lint first (never fold an invalid name into C++), then
apply: rewrite the enum bodies and search-replace the
renamed members across src/.
--lint validate the dissector names only.
--verbose list every reference-site replacement made by --fix.
Reconciliation rules (see the project plan for the full rationale):
* Match by value. Names are compared with a case/separator-insensitive
canonical key, so a case-only difference (LIST_FUNCTIONS_REQ vs
List_Functions_Req) is NOT a change -- the existing C++ spelling is kept.
* A beyond-case difference is a rename: the C++ member is renamed to the
house-style form of the dissector name and all references are updated.
* Full mirror: every active dissector entry missing from C++ is added; if C++
carries a value the dissector lacks, that is an error (reported, not
dropped). Commented-out ("pencil-in") Lua entries are ignored.
* New/renamed members follow each enum's house style: Device -> UPPER_SNAKE,
Action -> Title_Case (with a small acronym allowlist kept uppercase).
* New members are inserted at their position in the Lua table (adjacent to
their nearest Lua neighbour that already exists in C++).
The dissector is expected to keep *approximately* valid identifiers: spaces and
punctuation are silently converted to single underscores. Only two hard rules
are enforced by --lint (a name must not start with a digit, and must be at
least 3 characters); the 3-char floor also keeps the reference search-replace
from colliding on 2-character tokens.
Runs as a pre-commit hook via .githooks/pre-commit; that directory is wired up
by the top-level CMake configure step (core.hooksPath). `git commit --no-verify`
still bypasses it.
"""
import argparse
import os
import re
import sys
# ---- locations -------------------------------------------------------------
LUA_REL = os.path.join("scripts", "packet-analysis", "avclan_plugin.lua")
SRC_REL = "src"
SRC_EXTS = (".c", ".cc", ".h", ".hpp")
# Enum specs are matched to a Lua table by NAME; addresses are auto-detected
# separately (no Address enum exists yet). `style` picks the identifier casing,
# `hexfmt` the literal format for freshly added members (matched per file).
ENUM_SPECS = [
{
"name": "Action",
"path": os.path.join("src", "avclan", "avclan.h"),
"lua_table": "known_actions",
"style": "action",
"hexfmt": "0x%02x",
},
{
"name": "Device",
"path": os.path.join("src", "avclan", "device.hpp"),
"lua_table": "known_devices",
"style": "device",
"hexfmt": "0x%02X",
},
]
# Tokens kept fully uppercase when Title-casing an Action name, matching the
# existing hand-written style (CD_Enable_Repeat, Report_TOC). Note LAN -> Lan.
ACTION_ACRONYMS = {"CD", "TOC"}
# ---- name helpers ----------------------------------------------------------
def sanitize(name):
"""Convert an approximate identifier to a valid one: non-word chars become
underscores and runs of underscores collapse to one."""
s = re.sub(r"[^0-9A-Za-z_]", "_", name)
s = re.sub(r"_+", "_", s)
return s.strip("_")
def canonical(name):
"""Case/separator-insensitive key used to match names by identity."""
return re.sub(r"[^0-9A-Za-z]", "", name).upper()
def style_device(name):
return sanitize(name).upper()
def style_action(name):
parts = [p for p in sanitize(name).split("_") if p]
out = []
for p in parts:
if p.upper() in ACTION_ACRONYMS:
out.append(p.upper())
else:
out.append(p[:1].upper() + p[1:].lower())
return "_".join(out)
STYLERS = {"device": style_device, "action": style_action}
# ---- parsing ---------------------------------------------------------------
# An active Lua entry: ` [0x11] = "NAME",` with no leading `--`. The regex
# anchors `[` right after the indentation, so commented `-- [0x..]` lines and
# prose comment lines never match. The name is taken from inside the quotes,
# so trailing `-- ...` comments are ignored.
LUA_ENTRY_RE = re.compile(r'^\s*\[\s*0x([0-9A-Fa-f]+)\s*\]\s*=\s*"([^"]*)"')
LUA_TABLE_OPEN = "local %s = {"
LUA_TABLE_CLOSE_RE = re.compile(r"^\s*\}")
# A C++ enum member: ` Name = 0x11,` (or decimal). `//`-commented members are
# skipped by the caller, so they count as absent.
CPP_MEMBER_RE = re.compile(r"^\s*([A-Za-z_]\w*)\s*=\s*(0x[0-9A-Fa-f]+|\d+)")
class LuaEntry:
def __init__(self, value, name, lineno):
self.value = value
self.name = name
self.lineno = lineno
class CppMember:
def __init__(self, value, name, idx):
self.value = value
self.name = name
self.idx = idx # 0-based index into the file's line list
def read_lines(path):
with open(path, "r") as f:
return f.readlines()
def parse_lua_table(lines, table_name):
"""Return the active entries of a Lua table, in file order."""
open_marker = LUA_TABLE_OPEN % table_name
start = None
for i, line in enumerate(lines):
if line.strip().startswith(open_marker):
start = i
break
if start is None:
return None
entries = []
for j in range(start + 1, len(lines)):
line = lines[j]
if LUA_TABLE_CLOSE_RE.match(line):
break
if line.lstrip().startswith("--"):
continue
m = LUA_ENTRY_RE.match(line)
if m:
entries.append(LuaEntry(int(m.group(1), 16), m.group(2), j + 1))
return entries
def find_enum_body(lines, enum_name):
"""Locate `enum [macro] <name> ... {` and its closing brace. Returns
(open_idx, close_idx) as line indices, or None."""
open_re = re.compile(r"^\s*enum\b[^{;]*\b%s\b[^{;]*\{" % re.escape(enum_name))
for i, line in enumerate(lines):
if open_re.match(line):
for j in range(i + 1, len(lines)):
if LUA_TABLE_CLOSE_RE.match(lines[j]): # `^\s*}` works for C++ too
return i, j
return i, len(lines) - 1
return None
def parse_cpp_enum(lines, enum_name):
"""Return (members, open_idx, close_idx, indent) for a C++ enum, ignoring
commented-out members."""
body = find_enum_body(lines, enum_name)
if body is None:
return None
open_idx, close_idx = body
members = []
indent = " "
for j in range(open_idx + 1, close_idx):
stripped = lines[j].lstrip()
if stripped.startswith("//") or not stripped:
continue
m = CPP_MEMBER_RE.match(lines[j])
if m:
token = m.group(2)
value = int(token, 16) if token.lower().startswith("0x") else int(token)
members.append(CppMember(value, m.group(1), j))
indent = lines[j][: len(lines[j]) - len(lines[j].lstrip())]
return members, open_idx, close_idx, indent
def find_address_spec(root):
"""Auto-detect an `enum ... Address ... {` under src/, so addresses sync
automatically once such an enum is introduced. None today."""
addr_re = re.compile(r"^\s*enum\b[^{;]*\bAddress\b[^{;]*\{")
for path in iter_src_files(root):
if not path.endswith((".h", ".hpp")):
continue
with open(path, "r") as f:
for line in f:
if addr_re.match(line):
return {
"name": "Address",
"path": os.path.relpath(path, root),
"lua_table": "known_addresses",
"style": "device",
"hexfmt": "0x%03X",
}
return None
def iter_src_files(root):
for dirpath, _dirs, files in os.walk(os.path.join(root, SRC_REL)):
for fn in sorted(files):
if fn.endswith(SRC_EXTS):
yield os.path.join(dirpath, fn)
# ---- lint ------------------------------------------------------------------
def lint_table(entries, path):
"""Return a list of (lineno, name, reason) for dissector names that break a
hard rule."""
problems = []
seen = {}
for e in entries:
s = sanitize(e.name)
if not s or s[0].isdigit():
problems.append((e.lineno, e.name, "starts with a digit"))
continue
if len(s) < 3:
problems.append((e.lineno, e.name, "shorter than 3 characters"))
key = s.upper()
if key in seen:
problems.append((e.lineno, e.name,
"collides with '%s' (line %d) after sanitize"
% (seen[key][0], seen[key][1])))
else:
seen[key] = (e.name, e.lineno)
return problems
# ---- reconciliation --------------------------------------------------------
class Drift:
def __init__(self, spec):
self.spec = spec
self.renames = [] # (old_name, new_name, value)
self.adds = [] # (value, new_name)
self.cpp_only = [] # (value, name)
def clean(self):
return not (self.renames or self.adds or self.cpp_only)
def reconcile(spec, lua_entries, members):
stylefn = STYLERS[spec["style"]]
drift = Drift(spec)
cpp_by_val = {m.value: m for m in members}
lua_vals = set()
for e in lua_entries:
lua_vals.add(e.value)
target = stylefn(e.name)
if e.value in cpp_by_val:
cur = cpp_by_val[e.value].name
if canonical(cur) != canonical(e.name):
drift.renames.append((cur, target, e.value))
else:
drift.adds.append((e.value, target))
for m in members:
if m.value not in lua_vals:
drift.cpp_only.append((m.value, m.name))
return drift
# ---- fix: rewrite enum bodies + references ---------------------------------
def compute_insertions(adds, lua_order, present_idx, close_idx, indent, hexfmt):
"""Map each added value to the line index it should be inserted before,
mirroring the Lua table order. Returns {index: [rendered_line, ...]}."""
groups = {}
order_pos = {v: i for i, v in enumerate(lua_order)}
for value, name in adds: # adds are already in Lua order
pos = order_pos[value]
ins = None
for j in range(pos - 1, -1, -1):
if lua_order[j] in present_idx:
ins = present_idx[lua_order[j]] + 1
break
if ins is None:
for j in range(pos + 1, len(lua_order)):
if lua_order[j] in present_idx:
ins = present_idx[lua_order[j]]
break
if ins is None:
ins = close_idx
line = "%s%s = %s,\n" % (indent, name, hexfmt % value)
groups.setdefault(ins, []).append(line)
return groups
def apply_additions(path, spec, lua_entries, drift):
if not drift.adds:
return
lines = read_lines(path)
parsed = parse_cpp_enum(lines, spec["name"])
members, _open_idx, close_idx, indent = parsed
present_idx = {m.value: m.idx for m in members}
lua_order = [e.value for e in lua_entries]
groups = compute_insertions(drift.adds, lua_order, present_idx,
close_idx, indent, spec["hexfmt"])
for ins in sorted(groups, reverse=True):
lines[ins:ins] = groups[ins]
with open(path, "w") as f:
f.writelines(lines)
def replace_in_code(content, pattern, repl):
"""Apply `pattern` only to code, leaving comments, string literals and char
literals untouched -- a bare token like a renamed enum member must not be
rewritten where it merely appears in prose (e.g. `CSMA/CD` in a comment)."""
out = []
i = 0
n = len(content)
while i < n:
c = content[i]
nxt = content[i + 1] if i + 1 < n else ""
if c == "/" and nxt == "/":
j = content.find("\n", i)
j = n if j == -1 else j
out.append(content[i:j])
i = j
elif c == "/" and nxt == "*":
j = content.find("*/", i + 2)
j = n if j == -1 else j + 2
out.append(content[i:j])
i = j
elif c == '"' or (c == "'" and not (i > 0 and (content[i - 1].isalnum()
or content[i - 1] == "_"))):
# string, or a char literal (not a C++ digit separator like 1'000)
quote = c
j = i + 1
while j < n:
if content[j] == "\\":
j += 2
continue
if content[j] == quote:
j += 1
break
j += 1
out.append(content[i:j])
i = j
else:
j = i
while j < n:
cj = content[j]
cj1 = content[j + 1] if j + 1 < n else ""
if cj == '"':
break
if cj == "'" and not (content[j - 1].isalnum() or content[j - 1] == "_"):
break
if cj == "/" and (cj1 == "/" or cj1 == "*"):
break
j += 1
out.append(pattern.sub(repl, content[i:j]))
i = j
return "".join(out)
# A token right after one of these keywords is *introducing a name* (a type,
# enum, etc.), not referencing our enum member -- skip it so a member name that
# collides with an unrelated type (e.g. `enum CD { ... }`) is left alone.
DECL_KEYWORD_RE = re.compile(r"\b(?:enum|class|struct|union|namespace|typedef)\s+$")
def apply_renames(root, renames, verbose):
"""Replace whole-word code occurrences of every renamed member across src/.
A single simultaneous pass (alternation) avoids A->B->C chaining."""
if not renames:
return
mapping = {old: new for old, new, _v in renames}
pattern = re.compile(r"\b(%s)\b" % "|".join(re.escape(o) for o in mapping))
for path in iter_src_files(root):
with open(path, "r") as f:
content = f.read()
count = [0]
def repl(m):
if DECL_KEYWORD_RE.search(m.string[: m.start()]):
return m.group(0) # a declaration, not a member reference
count[0] += 1
return mapping[m.group(1)]
new_content = replace_in_code(content, pattern, repl)
if new_content != content:
with open(path, "w") as f:
f.write(new_content)
if verbose:
print(" %s: %d replacement(s)" % (os.path.relpath(path, root), count[0]))
# ---- reporting -------------------------------------------------------------
def print_lint(spec, path, problems):
for lineno, name, reason in problems:
print(" %s:%d: %r -- %s" % (path, lineno, name, reason))
def print_drift(drift):
spec = drift.spec
for old, new, value in drift.renames:
print(" rename %s -> %s (0x%02X)" % (old, new, value))
for value, name in drift.adds:
print(" add %s = 0x%02X" % (name, value))
for value, name in drift.cpp_only:
print(" ERROR %s (0x%02X) is in C++ %s but not the dissector"
% (name, value, spec["name"]))
# ---- driver ----------------------------------------------------------------
def build_specs(root):
specs = list(ENUM_SPECS)
addr = find_address_spec(root)
if addr:
specs.append(addr)
return specs, addr is not None
def load(root, spec, lua_lines):
entries = parse_lua_table(lua_lines, spec["lua_table"])
if entries is None:
sys.exit("error: Lua table '%s' not found" % spec["lua_table"])
parsed = parse_cpp_enum(read_lines(os.path.join(root, spec["path"])), spec["name"])
if parsed is None:
sys.exit("error: C++ enum '%s' not found in %s" % (spec["name"], spec["path"]))
return entries, parsed[0]
def main():
parser = argparse.ArgumentParser(
description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument("--fix", action="store_true",
help="apply the sync (rewrite enums + references)")
parser.add_argument("--lint", action="store_true",
help="validate dissector names only")
parser.add_argument("--verbose", action="store_true",
help="list every reference replacement made by --fix")
parser.add_argument("--root",
help="repo root (default: inferred from this script)")
args = parser.parse_args()
root = args.root or os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
lua_path = os.path.join(root, LUA_REL)
lua_lines = read_lines(lua_path)
specs, have_address = build_specs(root)
if not have_address:
print("note: no Address enum found in src/ -- addresses not synced")
# ---- lint (all modes) ----
lint_failed = False
for spec in specs:
entries = parse_lua_table(lua_lines, spec["lua_table"])
if entries is None:
sys.exit("error: Lua table '%s' not found" % spec["lua_table"])
problems = lint_table(entries, LUA_REL)
if problems:
lint_failed = True
print("dissector name problems in %s (%s):" % (spec["lua_table"], LUA_REL))
print_lint(spec, LUA_REL, problems)
if args.lint:
if lint_failed:
print("lint: FAILED")
return 1
print("lint: ok")
return 0
# ---- reconcile ----
drifts = []
for spec in specs:
entries, members = load(root, spec, lua_lines)
drifts.append((spec, entries, reconcile(spec, entries, members)))
has_cpp_only = any(d.cpp_only for _s, _e, d in drifts)
has_drift = any(not d.clean() for _s, _e, d in drifts)
if args.fix:
if lint_failed:
print("fix aborted: resolve the dissector name problems above first")
return 1
if has_cpp_only:
for _s, _e, d in drifts:
if d.cpp_only:
print("%s:" % d.spec["name"])
print_drift(d)
print("fix aborted: C++ has values the dissector lacks (see ERRORs)")
return 1
all_renames = []
for spec, entries, drift in drifts:
apply_additions(os.path.join(root, spec["path"]), spec, entries, drift)
all_renames.extend(drift.renames)
apply_renames(root, all_renames, args.verbose)
for spec, entries, drift in drifts:
if not drift.clean():
print("%s: %d rename(s), %d addition(s)"
% (spec["name"], len(drift.renames), len(drift.adds)))
print("fix: applied" if has_drift else "fix: already in sync")
return 0
# ---- default: report ----
for spec, _entries, drift in drifts:
if not drift.clean():
print("%s drift:" % spec["name"])
print_drift(drift)
if lint_failed or has_drift:
print("out of sync -- run: scripts/sync_avclan_enums.py --fix")
return 1
print("enums in sync with the dissector")
return 0
if __name__ == "__main__":
sys.exit(main())