trace_capture.h File Reference

Pre/post-trigger sample-window assembler (PC_ENABLE_TRACE_CAPTURE) - the v5 high-rate acquisition primitive. More...

#include "protocore_config.h"

Go to the source code of this file.

Detailed Description

Pre/post-trigger sample-window assembler (PC_ENABLE_TRACE_CAPTURE) - the v5 high-rate acquisition primitive.

The consumer sitting downstream of services/system/dma on a sampling front end (an external ADC front-end - e.g. an AD9226/AD9238 - draining into the device over SPI or UART DMA, a benchtop scope's digitizer output, or any other high-rate source): pc_tc_feed() is called with every batch of samples as they arrive (from a DMA-complete handler, most naturally), and a continuously-running pre-trigger ring always holds the most recent pc_tc_config::pretrigger_samples samples. When pc_tc_trigger() fires - a GPIO ISR, a software threshold detector, or an external front-end's own trigger line - the ring's current content becomes the pre-trigger half of the window and subsequent feeds fill the post-trigger half, so the emitted window straddles the trigger instant exactly like a benchtop oscilloscope's pretrigger/posttrigger split, even though the trigger is detected only after the pre-trigger samples already went by.

One capture in flight at a time, fail-closed: a trigger while a window is still filling is rejected and counted (pc_tc_stats::triggers_dropped), never queued or stomped - the same determinism contract as services/system/dma's one-TX-in-flight rule. Storage is static (PC_TC_MAX_WINDOW_SAMPLES samples, zero heap); feed() and trigger() are ISR-safe (no blocking, no allocation) so the natural wiring is a DMA-complete callback calling feed() and a GPIO ISR calling trigger(), both posting nothing further themselves - the window callback fires inline the instant the post-trigger half completes.

Window-assembly latency (trigger() to the completed callback) is timestamped with pc_cycles() (services/system/clock.h) rather than pc_micros(): at the sample rates this feeds from (an SPI-drained ADC burst can complete several feed() calls within a single microsecond tick) a 1 us clock under-resolves the jitter that matters for sizing PC_DMA_BUF_SIZE / the post-trigger sample count; pc_cycles_to_ns() converts the measured cycle delta to nanoseconds once the caller supplies the running CPU frequency.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file trace_capture.h.