st/README.md

   ▌  ╬ ▗▄▄▖ ▗▄▄▄▖▗▄▄▄▖
  ▐▐ ▐  ▐▌ ▐▌▐▌     █    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.