Buffer

Component Type: Program

Status: Implemented

Overview

CProgBuffer stores notify-driven source samples in program-owned history RAM and exposes selected samples or selected sample chunks plus selector/status registers through program-owned virtual IO channels.

  • src: notify source

  • out: selected sample/chunk (same dtype as source)

  • sel: selector (0 newest, 1 previous, …)

  • stat: status words (count/depth/head/overflow/flags)

Implementation

CProgBuffer is a notify-driven program that stores samples in internal RAM and serves selected history entries on demand.

Virtual IO ownership is role-specific:

  • src is a consumer-side input and must already have a valid fixed shape before buffer starts

  • out, sel, and stat are output-side roles whose shape may be defined by buffer itself and may therefore target deferred virt objects

  • chunk_size controls how many source samples are exposed through out per read; buffer initializes out with src.dim * chunk_size elements

Configuration

Kconfig

  • CONFIG_DAWN_PROG_BUFFER: enables the Buffer program.

YAML

programs:
  - id: buffer1
    type: buffer
    config:
      iobind:
        - src: src1
          out: out1
          sel: sel1
          stat: stat1
      depth: 16
      flags: 1
      chunk_size: 4

ios:
  - id: out1
    type: virt
    dtype: uint32

Descriptor fields:

  • iobind: one entry with src, out, sel, stat IDs

  • depth: sample capacity

  • chunk_size: number of samples returned through out per selected read (defaults to 1)

  • flags: - bit0: auto-start capture - bit1: one-shot mode (stop capture when full) - bit2: keep data on stop

Chunk Output

out provides a bulk-read view over the captured ring when chunk_size is greater than 1. The selector value is the first history offset in the chunk. With scalar src and chunk_size: 32, selector 0 returns offsets 0..31 (newest to older), selector 32 returns offsets 32..63, and so on.

If the selected range reaches past the number of captured samples, CProgBuffer zero-fills the remainder of the chunk. Readers should use the stat count/depth words to determine how much returned data is valid.

External Control

ControlIO: supported.

CProgBuffer supports runtime start/stop control via CIOControl. Start/stop controls capture activity. Data retention on stop depends on flags bit2.

TriggerIO: supported.

  • reset clears stored samples.

  • trigger1 starts capture.

  • trigger2 stops capture without stopping the program object.

Brainstorming & Future Ideas

Notes

  • One CProgBuffer instance supports a single binding.

  • sel out-of-range returns error and keeps previous selected sample.

  • Existing descriptors with scalar out keep the original single-sample behavior.

Doxygen