From 90787ec97e1a6a8a51333a7af4aacf27070b458d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dominic=20H=C3=B6glinger?= Date: Sat, 17 May 2025 15:30:35 +0200 Subject: [PATCH] Update README.md, fix old references to old project name --- README.md | 49 +++++++++++++++++++++++++++++-------------------- st_record.py | 6 +++--- 2 files changed, 32 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index febc206..2dcec59 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,10 @@ # Introduction ST is a small tracing library written in C99. -It is highly optimized for minimal data usage and aims to be easy to use +It is optimized for minimal data usage and aims to be easy to use while also being flexible enough to be integrated in hard real time systems. -Signals types supported are almost all 32 bit skalars (integers, floats), -32 bit integer arrays, events and strings. +Signals types supported are all integers up to 32 bit as well as their arrays, floats, events and strings. # How to use @@ -27,28 +26,28 @@ the text sent contains the packet preamble or epilouge, which are "\033[s" and " ## Simple example on Arduino ````c -#include "set.h" +#include "st.h" // Basic implementation of output and timestamp retrieval -void set_out(const char* const str, size_t len) { Serial.write(str, len); } -uint32_t set_timestamp(void) { return micros(); } +void st_out(const char* const str, size_t len) { Serial.write(str, len); } +uint32_t st_timestamp(void) { return micros(); } // No concurrency protection needed -void set_crit_on(uint32_t *h) {} -void set_crit_off(const uint32_t h) {} +void st_crit_on(uint32_t *h) {} +void st_crit_off(const uint32_t h) {} static const size_t s_tracesize = 256; -static set_trace_t s_tracebuf[256]; +static st_trace_t s_tracebuf[256]; void setup() { - set_init(s_tracebuf, s_tracesize); - set_enable(set_drop); // drop traces on full buffer + st_init(s_tracebuf, s_tracesize); + st_enable(st_drop); // drop traces on full buffer - set_u8trace("Serial.Ready", 0, false); + st_u8trace("Serial.Ready", 0, false); Serial.begin(2000000); while (!Serial); - set_u8trace("Serial.Ready", 1, false); + st_u8trace("Serial.Ready", 1, false); } void loop() @@ -57,23 +56,23 @@ void loop() if (sawtooth < 0xFFFF) sawtooth++; else sawtooth = 0; - set_u32trace("Main.Sawtooth", sawtooth, false); + st_u32trace("Main.Sawtooth", sawtooth, false); if (sawtooth == 4711) Serial.println("I can still be used with regular text."); - set_output(0, true, true); //send unlimited traces, compressed and clear console - set_diagtrace(); // add diagnostic traces + st_output(0, true, true); //send unlimited traces, compressed and clear console + st_diagtrace(); // add diagnostic traces } ```` # Basic operating principle Traces are identified by a signal name, which may be hierarchical such as `ExampleModule.Function.Value`. -These must be constant C strings as their pointers are stored in the trace buffer. +These must be statically accessible strings as they are later hashed when rendering traces. Once a trace is rendered, the signal name is hashed using the BSD sum function. This allows a client to identify a trace packet according to the source tree scanned. -For sending the traces to a client, they are rendered into a packet. +For sending the traces to a client, they are put into a packet. A packet consist of a preamble, a flag byte, frame data and an epilouge. The preamble and epilouge are chosen to be the ANSI escape sequences for storing the current position, and restoring it. @@ -97,9 +96,19 @@ Example usage tracing remotely via SSH: ````bash # Open /dev/ttyUSB0 via SSH and record to "trace.vcd" # with timescale of 1 microsecond with diagnostics enabled -ssh user@host -C "picocom -b 921600 /dev/ttyUSB0" | \ -./set_record.py -d trace.vcd -s ./Sources -t "1 us" --diagnostics +ssh user@host "picocom -b 921600 /dev/ttyUSB0" | \ +./st_record.py -d trace.vcd -s ./Sources -t "1 us" --diagnostics ```` The resulting VCD can be inspected with dedicated programs such as GTKwave. +This script also features a TUI mode, displaying live diagnostic information. +TUI mode requires the "rich" package in order to work. + + +# Special Thanks + +This repository uses code by the following people, so a thanks goes out to them! + - COBS algorithm with nonzero delimiter based on [this Wren library](https://rosettacode.org/wiki/Consistent_overhead_byte_stuffing#Wren) by unknown + - [FastLZ](https://github.com/ariya/FastLZ) by ariya + - [FastLZ Python native implementation](https://github.com/dargor0/pyfastlz-native/blob/main/src/fastlz_native/decompress.py) by Oscar Diaz diff --git a/st_record.py b/st_record.py index 65f13ec..53d39b2 100644 --- a/st_record.py +++ b/st_record.py @@ -349,7 +349,7 @@ class Retagger: class VcdSink: def __init__(self, fs, signals, timescale='1 us'): - self.writer = VCDWriter(fs, timescale=timescale, date=datetime.datetime.now().isoformat(), version=f"PET v1.0") + self.writer = VCDWriter(fs, timescale=timescale, date=datetime.datetime.now().isoformat(), version=f"ST v1.0.2") self.skalars = {} self.arrays = {} self.strings = {} @@ -475,7 +475,7 @@ class VcdSink: self._emit(timestamp, tag, value, None) def main(): - parser = argparse.ArgumentParser(description="scans stdin for PET packets and dumps the values into a VCD file") + parser = argparse.ArgumentParser(description="scans stdin for ST packets and dumps the values into a VCD file") parser.add_argument('-d', '--dump', type=str, required=True, help='output IEEE 1364-2005 Value Change Dump (vcd) file') parser.add_argument('-t', '--timescale', type=str, default="1 us", @@ -485,7 +485,7 @@ def main(): parser.add_argument('-s', '--source', type=str, required=True, help='source tree to scan for trace marks') parser.add_argument('--diagnostics', action=argparse.BooleanOptionalAction, - help='add additional signals tracing internal state of PET') + help='add additional signals tracing internal state of ST') parser.add_argument('--trace', action=argparse.BooleanOptionalAction, help='write out every trace that arrives') parser.add_argument('--tui', action=argparse.BooleanOptionalAction,