ITM Console and stimulus ports

The ITM Console displays text that firmware writes to the processor's Instrumentation Trace Macrocell, or ITM, through the SWO pin and probe. It is a receive-only console. Toolkit owns acquisition, decoding and recordings; install its complete package, including bkpt-trace. ViewAlyzer is not required.

This guide describes the Toolkit client migration branch. The existing Hardware Trace, Exceptions and ITM Console tiles remain the interface. Toolkit also supports exception trace and six DWT event counters, including hardware-only capture. DWT address/data trace and ETM remain unavailable here. Probe PC sampling has its own PC Sampling view.

Get your first line

1. Configure Toolkit, Arm GDB, your probe and matching firmware ELF, then attach halted. The board needs an ITM-capable core and a connected SWO signal.
2. Open Views → Hardware Trace and Views → ITM Console.
3. Select the SWO source core, enable ITM text, and select the one ITM stimulus port your firmware writes. Port 0 is conventional; all ports 0–31 support ordinary text.
4. Enter the actual Core clock (MHz) and SWO rate (MHz). Discovered AP endpoints also require SWO source clock (MHz); the SDK-selected endpoint resolves that clock through Toolkit's native catalog. These clocks can differ on a multicore device. Read any route/clock refusal before changing settings.
5. Start capture while paused, then Continue the target. The bounded capture runs for up to 10 seconds; Stop capture ends it earlier. Select all ports in the console to see the firmware text.

The capture stays bound to its source core when another core is selected. Its source revision, image set and content identities are retained through source refresh. ITM text carries no instruction address: the emitting image and runtime security state remain unknown, including with Secure and Non-Secure ELFs loaded.

Opening the console alone does not start acquisition. Firmware must actually write to the selected port; UART and semihosting output are not redirected.

Firmware: printing is an explicit operation

Firmware must route its output to ITM. A CMSIS ITM_SendChar() integration typically uses port 0; your C library's printf needs a suitable _write or fputc retarget if you want it to use that path. A UART retarget remains a UART retarget even when the debugger has ITM enabled.

For a simple best-effort text path on an ITM-capable target, this CMSIS-style helper avoids waiting forever when the debugger is absent or the FIFO is full. Include your device's CMSIS header first:

#include <stdbool.h>
#include <stdint.h>

static bool debug_text_try_char(uint32_t port, char c)
{
    if (port >= 32u) return false;
    if ((CoreDebug->DEMCR & CoreDebug_DEMCR_TRCENA_Msk) == 0u ||
        (ITM->TCR & ITM_TCR_ITMENA_Msk) == 0u ||
        (ITM->TER & (1UL << port)) == 0u ||
        ITM->PORT[port].u32 == 0u)
        return false;

    ITM->PORT[port].u8 = (uint8_t)c;
    return true;
}

/* Call from an appropriate firmware context after clocks are configured. */
static void debug_text_example(void)
{
    const char *message = "Sensor ready\n";
    while (*message) {
        if (!debug_text_try_char(0u, *message++)) break;
    }
}

This helper can drop output and returns failure instead of blocking. Handle that result if complete logs matter. Serialize writers in your firmware if multiple contexts share a port. A blocking print routine can affect firmware timing; text output is not zero-cost instrumentation. Do not call ITM code on a target that lacks the block or where the current privilege/security context cannot access it.

BKPT configures the trace hardware through the probe. Firmware should not continually overwrite that configuration while the session is using it. End text with \n so it appears as a completed console line.

Ports and console controls

Each capture selects one of the 32 ports, numbered 0–31. No port is reserved for a ViewAlyzer recorder. Match the selected port to the firmware's writes.

Text can arrive in fragments. The console assembles lines within their capture, core and port identity. Display history is bounded; the saved recording is the source for offline queries. Closing the console does not stop acquisition.

Saved recordings and timing

To capture hardware events, enable Exception enter / exit / return or selected counters in Hardware Trace. Disable ITM text for hardware-only capture. The Exceptions tile displays Toolkit's cumulative transition counts and maximum nesting depth; Hardware Trace shows cumulative counter packet totals. Counter packets are not elapsed cycles, rates or CPU utilization. Missing packets make totals incomplete, and nesting restarts after a gap. Loss epochs and decoder/native health remain visible. Enable fewer sources if the SWO stream overflows. Toolkit checks hardware support and conflicts when starting capture; same-core PC sampling and hardware trace cannot own the shared resources together.

For individual saved hardware events, use:

bkpt-trace query hardware-events --recording <recording.vadb> --limit 1000

Continue with --after-event <data.next_event_id> while data.truncated is true. Events retain timing validity, degraded/loss information and the frozen source context. Exception/counter packets have no instruction address, so they do not identify an emitting ELF or its runtime security state.

Toolkit finalizes a .vadb recording in the extension's capture storage and reports its location. Query it with the same Toolkit package:

bkpt-trace query itm-console --recording <recording.vadb> --port 0 --limit 1000

If data.truncated is true, request the next page with --after-event <data.next_event_id>. Keep reading until it is false. Each event has text, t_us and partial; a partial event continues without a newline. Replay uses the recorded source context and does not reopen ELFs or require a probe, ViewAlyzer or a license-helper lookup. Live capture uses Toolkit's shared licensing authority.

Failed captures may leave .vadb.partial evidence. Inspect data.complete; a file or successful stop alone does not establish useful, complete data. Check actual text and the reported native drops and decoder quality counters. Decoder time is relative and approximate, not an exact per-write timestamp or wall-clock measurement. The current client has no timestamp-prescaler control.

Nothing appears, or output is damaged

The Firmware generated badge identifies the source: the target firmware created this text, and ITM transports it.