BKPT LabsDOCS/VIEWALYZER CLI/ATTACH USING FIRMWARE RAM METADATA VIEWALYZER · HEADLESS CLI
VIEWALYZER · CLI & AUTOMATION

Attach using firmware RAM metadata

Direct DROP-mode RAM-buffer recording enables metadata by default when no snapshot tee is configured. Use a compatible ViewAlyzer-RS build and the ELF that matches the firmware loaded on the target:

viewalyzer-cli capture --config board.vacf --elf firmware.elf --no-reset --duration 10 --output attached.vadb

In the GUI, select the firmware under ELF / Symbols > ELF File before recording. Choose the RAM-buffer transport and turn Reset on Connect off to attach to the running application.

The host reads task names, task attributes, trace definitions, object information and recorder configuration from target RAM. It requests a stream checkpoint and starts the recording there. Later registration changes arrive through the event stream. Events before attachment are not recovered.

Full setup bundles are not periodically retransmitted in this mode. If the host detects corruption or sequence loss, it requests fresh definitions and another checkpoint. The recording retains the actual loss counts.

Saved .vadb recordings and .va raw logs include the definitions needed for standalone replay. Neither the target nor its ELF is needed to decode them. An ELF is still useful for views that resolve firmware symbols.

Firmware settings

SETTING USAGE
VA_METADATADefaults to 1 for the supported RAM configuration; set 0 for setup-bundle capture
VA_METADATA_SIZETable capacity in bytes, default 2048u, plus a 64-byte descriptor and service state
CONFIG_VIEWALYZER_METADATAZephyr equivalent, defaults to y for the supported configuration
CONFIG_VIEWALYZER_METADATA_SIZEZephyr table capacity

Use VA_METADATA=0 for a viewer without metadata support, capture without an ELF, or reduced RAM usage. SWO, RTT, custom transports, buffered output, BLOCK/WRAP RAM modes and snapshot tees default to setup-bundle capture.

Firmware must call VA_TickOverflowCheck() periodically during quiet periods to handle timer rollover, idle attachment requests and small time/sequence checkpoints. Timestamped events already handle rollover. A 100 ms interval suits typical 32-bit timers; use a shorter interval, such as 10 ms, for a 16-bit timer at 1 MHz. The longest service gap must be below the timer's wrap period. Metadata capture needs no periodic VA_EmitSetupBundle() call.

Troubleshooting

  • Missing ELF: select the exact ELF loaded on the target, before recording.
  • Metadata overflow: increase the firmware's table capacity and rebuild.
  • Checkpoint timeout: confirm the target is running and periodically services VA_TickOverflowCheck() when no events are emitted.
  • Invalid descriptor or table: confirm the ELF matches, use one consuming host, and place all recorder shared memory in probe-visible, non-cacheable RAM on cached targets.

See the recorder's RAM metadata guide for firmware integration and memory placement.