41 lines
2.2 KiB
Markdown
41 lines
2.2 KiB
Markdown
```
|
|
▌ ╬ ▗▄▄▖ ▗▄▄▄▖▗▄▄▄▖
|
|
▐▐ ▐ ▐▌ ▐▌▐▌ █ Pocket Event Trace
|
|
▌ ▌▌ ▐▛▀▘ ▐▛▀▀▘ █ A tiny tracing library
|
|
═══▐══ ▐▌ ▐▙▄▄▖ █ ═════════════════════════════
|
|
```
|
|
|
|
# Introduction
|
|
|
|
PET is a small (less than 1k implementation lines) tracing library written in C and is highly optimized for minimal data usage
|
|
and aims to be easy to set up and use while also being flexible enough to be integrated in hard real time systems.
|
|
|
|
# How to use
|
|
|
|
PET requires the integrator to implement a few functions such as the timestamp and output functions in order to work.
|
|
|
|
# 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.
|
|
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.
|
|
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.
|
|
|
|
The frame data may be compressed using fastlz, which is indicated by the Z flag in the packet.
|
|
Regardless of compression, it is COBS encoded with delimiter 0033 to not interfere with the preamble or epilouge.
|
|
|
|
Frame data consists of multiple frames, COBS encoded with delimiter 0 and delimited with the same value.
|
|
Each frame contains the signal hash, its type and depending on it a value ranging from 1-4 bytes and indexing information.
|
|
Timestamps are sent in increments to conserve bandwidth.
|
|
All trace functions feature a parameter which enables timestamp capture, if it is omitted this means no time delta is sent,
|
|
making the trace appear to coincide with the last trace which captured a timestamp.
|
|
|
|
# The recorder utility
|
|
|
|
The repository contains an example client application which captures packages and outputs the traces in a Value Change Dump.
|
|
This script uses the PyVCD package which is the only dependency.
|