Recorder configuration

Every knob is a preprocessor macro with a default in core/ViewAlyzerConfig.h. That file includes nothing (no CMSIS, no RTOS header), so it is safe to include from anywhere, FreeRTOSConfig.h included. You never edit it in place: a package update would overwrite the edit.

Three ways to set a knob

In order of precedence:

1. Your own header, named on the command line as a bare token (no quotes, no angle brackets):

add_definitions(-DVA_CONFIG_HEADER=va_config.h)

/* va_config.h: only what differs from the defaults */
#define VA_DEVICE_HEADER  stm32g474xx.h
#define VA_RAMBUF_SIZE    16384u
#define VA_TRACE_DEFAULT  0          /* opt in below */
#define VA_TRACE_TASKS    1
#define VA_TRACE_ISRS     1
#define VA_TRACE_MUTEX_CONTENTION 1
#define VA_TRACE_USER_VALUES 1

1. **-D on the command line** (every knob is #ifndef-guarded).
2. Editing ViewAlyzerConfig.h (lost on update; do not).

The only setting without a default is the device header. Put it in va_config.h too (the Zephyr module supplies it automatically):

#define VA_DEVICE_HEADER stm32g474xx.h

core/va_config_template.h lists every knob, commented out, as a starting point.

Master switches

RAM metadata is enabled by default for direct DROP-mode RAM-buffer recording without a snapshot tee. Use a compatible ViewAlyzer-RS host and the matching firmware ELF. Set VA_METADATA=0 for setup-bundle capture.

Categories

Each category is 0 or 1 and defaults to VA_TRACE_DEFAULT (1), except VA_TRACE_TASK_STATES, which follows VA_TRACE_TASKS, and VA_TRACE_TIMER_CALLBACKS, which follows VA_TRACE_TIMERS. The usual pattern is either "everything on" or VA_TRACE_DEFAULT 0 plus an opt-in list. Turning a category off removes its packets from the wire and its functions from the binary.

For fixed-coverage benchmarks and HIL baselines, explicitly set VA_TRACE_TASK_STATES=0 and VA_TRACE_TIMER_CALLBACKS=0 to retain task switches and timer lifecycle events without the newer state/priority and callback packets. VA_TRACE_DEFAULT=0 alone does not disable subcategories of enabled parents. In Zephyr, use CONFIG_VIEWALYZER_TRACE_TASK_STATES=n and CONFIG_VIEWALYZER_TRACE_TIMER_CALLBACKS=n. Callback spans are currently automatic only on Zephyr kernels that expose the stock handler entry/exit hooks. Enabling this flag adds no automatic events on FreeRTOS or older Zephyr kernels; FreeRTOS timer-expiry events still follow VA_TRACE_TIMERS.

Transport

Pass the matching firmware ELF with --elf for default RAM metadata capture. With VA_METADATA=0, the host can also locate the ring by scanning RAM (--rambuf-scan-start, --rambuf-scan-size). On cached cores, use linker/MPU configuration to put the ring, descriptors and metadata in non-cacheable RAM.

Post-mortem snapshot

VA_SnapshotFreeze() stops the ring; viewalyzer-cli snapshot reads it without resetting the target. See Transports and snapshots.

Registries

Raise VA_MAX_TASKS on a Zephyr system with many threads (the Zephyr demo uses 28) and VA_MAX_TASK_NAME_LEN when your names are longer than 15 characters.

Session, clock, OS and error metadata use a separate fixed capacity, so short display names do not truncate control messages. Custom transport packet capacity is derived from both names and logs; neither setting imposes a minimum on the other. The current ViewAlyzer-RS decoder accepts names up to 64 characters; larger recorder settings are memory-safe but need corresponding viewer support.

Timestamps

Timestamped events automatically track counter rollover. During quiet periods, call VA_TickOverflowCheck() more often than the source timer wraps. It also services idle attachment requests and time/sequence checkpoints. Example service intervals (allow for scheduling delays; see API reference):

VA_TIMESTAMP_BITS is 32 and not a knob; VA_SEQ_COUNTER (the per-packet sequence byte that lets the host count losses) is always on.

Timing and wire

FreeRTOS stack tracing uses a word scanner with the same high-water accuracy and sampling schedule. It needs aligned, downward-growing 32-bit stacks with known bounds and the standard 0xA5 fill. Unsupported layouts, unknown bounds or a scan that exhausts its bound use uxTaskGetStackHighWaterMark() instead. There is no scanner-selection setting; VA_TRACE_STACK_USAGE=0 disables stack measurements. Other RTOSes are unaffected. See FreeRTOS stack scanning.

Zephyr: the same knobs as Kconfig

The Zephyr module maps CONFIG_VIEWALYZER_* options onto these macros (zephyr/CMakeLists.txt): transport (CONFIG_VIEWALYZER_TRANSPORT_ITM / _RTT / _RAMBUF), timestamp (CONFIG_VIEWALYZER_TS_DWT / _TS_CUSTOM_TIMER, CONFIG_VIEWALYZER_TIMER_BITS), every category (CONFIG_VIEWALYZER_TRACE_THREADS, _ISRS, _MUTEXES, _MUTEX_CONTENTION, _SEMAPHORES, _MESSAGE_QUEUES, _EVENT_FLAGS, _WORK, _SLEEP, _TIMERS, _HEAPS, _PM, _USER_VALUES, _USER_EVENTS, _STRINGS, _GPIO, _COUNTERS, _HEAP_METRICS), CONFIG_VIEWALYZER_STACK_USAGE, the registry sizes (_MAX_TASKS, _MAX_SYNC_OBJECTS, _MAX_USER_EVENTS, _MAX_USER_TRACES, _MAX_GPIOS, _MAX_HEAP_GAUGES, _MAX_TASK_NAME_LEN), the RTT and RAM-buffer knobs (_RTT_CHANNEL, _CONFIGURE_RTT, _RTT_BUFFER_SIZE, _RAMBUF_SIZE, _RAMBUF_BLOCK, _RAMBUF_WRAP, _RAMBUF_BUSY_IDLE), metadata (_METADATA, _METADATA_SIZE), the snapshot (_SNAPSHOT, _SNAPSHOT_SIZE, _SNAPSHOT_SETUP_SIZE), _BUFFERED / _BUFFER_SIZE, _ALLOW_DISABLE_INTERRUPTS, _AUTO_SETUP_INTERVAL_MS, _STACK_USAGE_HEARTBEAT_MS. Two things are fixed by the module: VA_DEVICE_HEADER=cmsis_core.h and task notifications off. CUSTOM_TRANSPORT is not selectable from Kconfig.