mirror of
https://github.com/halleysfifthinc/AVCLAN-Mockingboard.git
synced 2026-08-06 17:03:17 +00:00
Allen Hill
542 lines
20 KiB
Python
Executable File
542 lines
20 KiB
Python
Executable File
#!/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())
|