Reserve USB KISS framing before normal parsers consume it

This commit is contained in:
mikecarper committed 2026-10-26 17:49:20 -07:00
1 parent ff51126508
commit 1aef6de288
20 files changed
+624 -10

No files matched your search

+36 -1
View File
@@ -12,6 +12,10 @@ import struct
import zipfile
import zlib
from rp2040_application import read_application as read_rp2040_application
from host_kiss_capabilities import (CAPABILITY as HOST_KISS_CAPABILITY,
USB_CAPABILITY as HOST_KISS_USB_CAPABILITY, TCP_CAPABILITY as HOST_KISS_TCP_CAPABILITY,
COMMAND_MARKERS as HOST_KISS_COMMAND_MARKERS, TCP_MARKER as HOST_KISS_TCP_MARKER,
evidence as host_kiss_evidence)
from package_meshtext_license import (CAPABILITY as MESHTEXT_CAPABILITY,
meshtext_evidence, notice_bytes as meshtext_notice_bytes,
notice_record as meshtext_notice_record)
@@ -81,6 +85,10 @@ def parse_args() -> argparse.Namespace:
"--require-meshtext", action="store_true",
help="Require linked Meshtext encode/decode and Companion raw-frame transport implementations.",
)
parser.add_argument(
"--require-host-kiss", action="store_true",
help="Require linked KISS framing/Dispatcher transport and packaged USB/TCP service commands.",
)
parser.add_argument("--firmware-bin", type=Path)
parser.add_argument("--partitions", type=Path)
parser.add_argument("--dfu-package", type=Path)
@@ -231,12 +239,34 @@ def main() -> int:
"evidence": "Meshtext encode/decode, Companion send/receive, and Dispatcher raw-frame queue implementations",
"present": False, "source": "linked ELF symbols"})
application = b""
if args.expect_application:
if args.expect_application or args.require_host_kiss:
try:
application = read_application(args)
except (OSError, ValueError, KeyError, zipfile.BadZipFile) as exc:
print(f"capability check: cannot read packaged application: {exc}", file=sys.stderr)
malformed = True
host_kiss_symbols = []
host_kiss_verified = False
if args.require_host_kiss:
try:
host_kiss_symbols = host_kiss_evidence(args.image)
except (OSError, ValueError) as exc:
print(f"capability check: cannot qualify linked host KISS code: {exc}", file=sys.stderr)
malformed = True
checks.append({"capability": HOST_KISS_CAPABILITY,
"evidence": "; ".join(host_kiss_symbols) if host_kiss_symbols else
"executable KISS frame decoder/encoder and Dispatcher raw-frame queue",
"present": bool(host_kiss_symbols), "source": "linked ELF symbols"})
usb_present = all(marker in application for marker in HOST_KISS_COMMAND_MARKERS)
checks.append({"capability": HOST_KISS_USB_CAPABILITY,
"evidence": "; ".join(marker.decode("ascii") for marker in HOST_KISS_COMMAND_MARKERS),
"present": usb_present, "source": "packaged application"})
tcp_present = args.platform != "ESP32_PLATFORM" or HOST_KISS_TCP_MARKER in application
if args.platform == "ESP32_PLATFORM":
checks.append({"capability": HOST_KISS_TCP_CAPABILITY,
"evidence": HOST_KISS_TCP_MARKER.decode("ascii"),
"present": tcp_present, "source": "packaged application"})
host_kiss_verified = bool(host_kiss_symbols) and usb_present and tcp_present
expectations = [(value, image, "linked image") for value in args.expect]
expectations += [(value, application, "packaged application") for value in args.expect_application]
gzip_assets = linked_gzip_assets(image) if args.expect_gzip else []
@@ -269,6 +299,11 @@ def main() -> int:
# Neither a requested capability nor CLI strings prove the optional
# codec and its complete Companion transport survived linking.
capabilities = [value for value in capabilities if value != MESHTEXT_CAPABILITY]
if not host_kiss_verified:
capabilities = [value for value in capabilities if value not in
(HOST_KISS_CAPABILITY, HOST_KISS_USB_CAPABILITY, HOST_KISS_TCP_CAPABILITY)]
if args.platform != "ESP32_PLATFORM":
capabilities = [value for value in capabilities if value != HOST_KISS_TCP_CAPABILITY]
missing = [check for check in checks if not check["present"]]
ota_methods = stable_unique([
check["capability"].removeprefix("ota.update.")
+111
View File
@@ -0,0 +1,111 @@
#!/usr/bin/env python3
"""Qualify the optional host KISS service from effective flags and linked code."""
from __future__ import annotations
import argparse
import json
import os
from pathlib import Path
import re
import shlex
import sys
from package_meshtext_license import linked_symbols
CAPABILITY = "radio2.kiss.host"
USB_CAPABILITY = "radio2.kiss.usb"
TCP_CAPABILITY = "radio2.kiss.tcp"
COMMAND_MARKERS = (b"Error: use set kiss on|off",
b"Error: use set kiss.transport usb|tcp",
b"USB: send KISS FEND to start")
TCP_MARKER = b"station TCP 5004"
def evidence(path):
# LTO can inline the transport callbacks. Require executable framing and
# the bounded Dispatcher queue shared by the actual RX/TX implementation.
# A declaration, an undefined reference, or a CLI help string is not code.
symbols = linked_symbols(path)
required = ("_ZN4mesh8hostkiss5Codec4feedE",
"_ZN4mesh8hostkiss5Codec11queueOutputE",
"_ZN4mesh10Dispatcher22queueForeignRadioFrameE")
selected = []
for operation in required:
matches = [name for name in symbols if name.startswith(operation)]
if not matches:
return []
selected.append(matches[0])
return selected
def operations(value):
words = iter(shlex.split(value if isinstance(value, str) else "\n".join(map(str, value))))
result = []
for word in words:
if word in ("-D", "-U"):
word += next(words, "")
match = re.fullmatch(r"-([DU])(\w+)(?:=(.*))?", word)
if match:
result.append(match.groups())
return result
def required(config, env, platform, full_companion, overlay="", unflags=""):
if platform not in ("ESP32_PLATFORM", "NRF52_PLATFORM"):
return False
rows = {name: dict(options) for name, options in config}
options = rows.get("env:" + env, {})
flags = operations(options.get("build_flags", [])) + operations(overlay)
removed = set(operations(options.get("build_unflags", [])) + operations(unflags))
flags = [flag for flag in flags if flag not in removed
and not (flag[0] == "D" and ("D", flag[1], None) in removed)]
defines = {name: "1" if value is None else value
for kind, name, value in flags if kind == "D"}
# PlatformIO emits surviving -U after CPPDEFINES, so -U always wins.
for kind, name, _value in flags:
if kind == "U":
defines.pop(name, None)
def enabled(name, default=False, seen=()):
if name not in defines:
return default
if name in seen:
return None
value = defines[name].strip().strip("() ")
if value in ("false", "true"):
return value == "true"
if re.fullmatch(r"[A-Za-z_]\w*", value):
return enabled(value, False, (*seen, name))
number = re.fullmatch(r"([+-]?(?:0[xX][0-9a-fA-F]+|[0-9]+))[uUlL]*", value)
if number:
value = number[1]
base = 16 if "x" in value.lower() else 8 if re.fullmatch(r"[+-]?0[0-7]+", value) else 10
return int(value, base) != 0
return None
# Match HostKissConfig.h's hard exclusion even with an explicit enable.
if enabled("MESH_PRIMARY_ESPNOW") is True:
return False
if "MESH_ENABLE_HOST_KISS" in defines:
return enabled("MESH_ENABLE_HOST_KISS") is not False
return enabled("COMPANION_RADIO_FULL", full_companion) is not False
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--required", action="store_true")
parser.add_argument("--env", required=True)
parser.add_argument("--platform", required=True)
parser.add_argument("--full-companion", action="store_true")
args = parser.parse_args()
try:
selected = required(json.load(sys.stdin), args.env, args.platform, args.full_companion,
os.environ.get("PLATFORMIO_BUILD_FLAGS", ""),
os.environ.get("PLATFORMIO_BUILD_UNFLAGS", ""))
except (OSError, ValueError, TypeError) as error:
parser.exit(2, f"Cannot determine host KISS capability contract: {error}\n")
return 0 if selected else 3
if __name__ == "__main__":
raise SystemExit(main())