From a9e05180340964af1289aff2751ecb8b43098784 Mon Sep 17 00:00:00 2001 From: ahmadalguydi Date: Wed, 29 Jul 2026 19:37:35 +0300 Subject: [PATCH] feat: add hex input to latch-dump --- CMakeLists.txt | 6 +++ README.md | 10 ++++ tests/test_latch_dump.py | 69 ++++++++++++++++++++++++ tools/latch_dump.c | 111 +++++++++++++++++++++++++++++++++------ 4 files changed, 181 insertions(+), 15 deletions(-) create mode 100644 tests/test_latch_dump.py diff --git a/CMakeLists.txt b/CMakeLists.txt index 51d10e4..094ba79 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -259,6 +259,12 @@ endif() if(LS_BUILD_TOOLS) add_executable(latch-dump tools/latch_dump.c) target_link_libraries(latch-dump PRIVATE latch) + if(LS_BUILD_TESTS) + find_package(Python3 COMPONENTS Interpreter REQUIRED) + add_test(NAME latch-dump-hex-tests + COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_latch_dump.py + $ ${CMAKE_CURRENT_SOURCE_DIR}/tests/vectors/lep-v1-basic.hex) + endif() endif() if(LS_BUILD_EXAMPLES) if(CMAKE_CROSSCOMPILING) diff --git a/README.md b/README.md index 0a07fae..444bdf9 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,16 @@ LEP v1 type=2 arch=0 flags=0x00 sequence=1 event=b63f7832 payload=263 See [the complete host example](examples/host/main.c) for initialization, in-memory storage, and transport registration. +### Inspect a hexadecimal LEP vector + +`latch-dump` keeps its existing binary-file interface and also accepts bounded hexadecimal input with `--hex`. From the repository root: + +```sh +build/host-debug/latch-dump --hex tests/vectors/lep-v1-basic.hex +``` + +ASCII whitespace is accepted between hexadecimal digits. Decoded input is limited to `LS_MAX_EVENT_SIZE`; odd-length, non-hexadecimal, and oversized inputs fail before envelope validation. + ## What survives the reboot Latch is built for failures where ordinary logging becomes least reliable: diff --git a/tests/test_latch_dump.py b/tests/test_latch_dump.py new file mode 100644 index 0000000..6799ebf --- /dev/null +++ b/tests/test_latch_dump.py @@ -0,0 +1,69 @@ +#!/usr/bin/env python3 +"""Exercise the host decoder's bounded hexadecimal input mode.""" + +from __future__ import annotations + +import subprocess +import sys +import tempfile +from pathlib import Path + + +def run(decoder: str, *arguments: str) -> subprocess.CompletedProcess[str]: + return subprocess.run( + [decoder, *arguments], + check=False, + capture_output=True, + text=True, + ) + + +def main() -> int: + decoder, vector = sys.argv[1:] + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + + valid = root / "valid.hex" + vector_bytes = "".join(Path(vector).read_text().split()) + separators = (" ", "\t", "\r", "\n", "\f", "\v") + pairs = [vector_bytes[index : index + 2] for index in range(0, len(vector_bytes), 2)] + valid.write_text( + "".join(pair + separators[index % len(separators)] for index, pair in enumerate(pairs)) + ) + result = run(decoder, "--hex", str(valid)) + assert result.returncode == 0, result.stderr + assert "LEP v1" in result.stdout + + binary = root / "valid.lst" + binary.write_bytes(bytes.fromhex(vector_bytes)) + result = run(decoder, str(binary)) + assert result.returncode == 0, result.stderr + assert "LEP v1" in result.stdout + + result = run(decoder, "--hex") + assert result.returncode == 2 + assert "usage:" in result.stderr + + odd = root / "odd.hex" + odd.write_text("abc") + result = run(decoder, "--hex", str(odd)) + assert result.returncode != 0 + assert "odd number of digits" in result.stderr + + invalid = root / "invalid.hex" + invalid.write_text("00xz") + result = run(decoder, "--hex", str(invalid)) + assert result.returncode != 0 + assert "non-hex character" in result.stderr + + oversized = root / "oversized.hex" + oversized.write_text("00" * 4097) + result = run(decoder, "--hex", str(oversized)) + assert result.returncode != 0 + assert "exceeds LS_MAX_EVENT_SIZE" in result.stderr + + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/latch_dump.c b/tools/latch_dump.c index e47890d..d797c07 100644 --- a/tools/latch_dump.c +++ b/tools/latch_dump.c @@ -1,22 +1,113 @@ #include #include +#include #include "laststate/latch.h" + +static int is_ascii_whitespace(int character) { + return character == ' ' || character == '\t' || character == '\n' || character == '\r' || + character == '\f' || character == '\v'; +} + +static int hex_digit(int character) { + if (character >= '0' && character <= '9') { + return character - '0'; + } + if (character >= 'a' && character <= 'f') { + return character - 'a' + 10; + } + if (character >= 'A' && character <= 'F') { + return character - 'A' + 10; + } + return -1; +} + +static int read_hex(FILE *file, uint8_t *data, size_t capacity, size_t *length) { + int high = -1; + int character; + while ((character = fgetc(file)) != EOF) { + if (is_ascii_whitespace(character)) { + continue; + } + int digit = hex_digit(character); + if (digit < 0) { + fprintf(stderr, "invalid hex input: non-hex character 0x%02x\n", + (unsigned)(unsigned char)character); + return 1; + } + if (high < 0) { + high = digit; + continue; + } + if (*length >= capacity) { + fprintf(stderr, "hex input exceeds LS_MAX_EVENT_SIZE (%u bytes)\n", + (unsigned)LS_MAX_EVENT_SIZE); + return 1; + } + data[*length] = (uint8_t)((high << 4) | digit); + ++*length; + high = -1; + } + if (ferror(file)) { + perror("read"); + return 1; + } + if (high >= 0) { + fprintf(stderr, "invalid hex input: odd number of digits\n"); + return 1; + } + return 0; +} + static ls_result_t print_tlv(void *context, uint16_t type, const uint8_t *value, uint16_t length) { (void)context; (void)value; printf(" tlv type=%u length=%u\n", (unsigned)type, (unsigned)length); return LS_OK; } + +static int dump_envelope(const uint8_t *data, size_t length) { + ls_envelope_info_t info; + ls_result_t result = ls_envelope_validate(data, length, &info); + if (result != LS_OK) { + fprintf(stderr, "invalid LEP envelope: %d\n", result); + return 1; + } + printf("LEP v%u type=%u arch=%u flags=0x%02x sequence=%u event=%08x payload=%u\n", info.version, + info.type, info.architecture, info.flags, (unsigned)info.sequence, (unsigned)info.event_id, + (unsigned)info.payload_length); + result = ls_envelope_visit(data, length, print_tlv, 0); + return result == LS_OK ? 0 : 1; +} + int main(int argc, char **argv) { - if (argc != 2) { - fprintf(stderr, "usage: latch-dump EVENT.lst\n"); + int hex_input = argc > 1 && strcmp(argv[1], "--hex") == 0; + if ((!hex_input && argc != 2) || (hex_input && argc != 3)) { + fprintf(stderr, "usage: latch-dump [--hex] EVENT\n"); return 2; } - FILE *file = fopen(argv[1], "rb"); + const char *path = hex_input ? argv[2] : argv[1]; + FILE *file = fopen(path, "rb"); if (!file) { perror("open"); return 2; } + if (hex_input) { + uint8_t *data = (uint8_t *)malloc(LS_MAX_EVENT_SIZE); + if (!data) { + fclose(file); + return 2; + } + size_t length = 0; + int result = read_hex(file, data, LS_MAX_EVENT_SIZE, &length); + fclose(file); + if (result) { + free(data); + return 1; + } + result = dump_envelope(data, length); + free(data); + return result; + } if (fseek(file, 0, SEEK_END) || ftell(file) < 0) { fclose(file); return 2; @@ -34,17 +125,7 @@ int main(int argc, char **argv) { free(data); return 2; } - ls_envelope_info_t info; - ls_result_t result = ls_envelope_validate(data, read, &info); - if (result != LS_OK) { - fprintf(stderr, "invalid LEP envelope: %d\n", result); - free(data); - return 1; - } - printf("LEP v%u type=%u arch=%u flags=0x%02x sequence=%u event=%08x payload=%u\n", info.version, - info.type, info.architecture, info.flags, (unsigned)info.sequence, - (unsigned)info.event_id, (unsigned)info.payload_length); - result = ls_envelope_visit(data, read, print_tlv, 0); + int result = dump_envelope(data, read); free(data); - return result == LS_OK ? 0 : 1; + return result; }