Skip to content

Instrumentation Trace Macrocell (ITM)

lbuild module: modm:platform:itm

This module provides the ITM port 0 as a (buffered) Uart interface. You can use this class as a transmit-only alternative for logging:

                      modm::IOBuffer::DiscardIfFull> itm_device;
modm::IOStream stream(itm_device);

stream << "Hello World" << modm::endl;


The ITM is part of the ARM Cortex-M debug functionality and forwards its data to the Trace Port Interface Unit (TPIU) which outputs over the trace pins. Only the SWO trace pin is currently supported (asynchronous tracing).

The ITM is not a UART replacement!

The TPIU only outputs data when a debugger is attached to the target!

The Itm class will safely discard any data if a debugger is not attached, so you can use it for debugging without running the risk of a deadlock.

The ITM requires polling!

The hardware does not generate a "buffer empty" interrupt, so the buffered implementation requires you to call the update() function!

By default the Itm class is non-buffered and therefore blocking. You must set the modm:platform:itm:buffer.tx option to non-zero to use the buffered version!

Receiving Data

You must use OpenOCD to configure your target's hardware, as well as capture the asynchronous trace stream.

Is the SWO pin connected to your debugger?

Check if your debugger supports trace output and if the SWO pin is actually connected to it on your development board!

To log the output to a file called itm.fifo you can call the modm_log_itm command manually.

openocd -f modm/openocd.cfg -c "modm_log_itm itm.fifo 64000000"

You can then either use tail -f itm.fifo to display the raw data stream (which is often enough) or use the itmdump program for an advanced use-case (like de-multiplexing data streams).

OpenOCD requires the CPU/HCLK frequency

You must provide the CPU/HCLK frequency of your target, so that OpenOCD can correctly set the prescaler for the asynchronous SWO output.

When using the modm:build:scons module, you can also use the convenience wrapper, which logs to a temporary file and displays it's contents on the terminal

 $ scons log-itm fcpu=64000000
╭───OpenOCD───> Single Wire Viewer
╰─────SWO────── stm32f103rbt
Hello from the SWO.
loop 0
loop 1
loop 2
loop 3
loop 4
loop 5

This module is only available for sam{d5x/e5x,e7x/s7x/v7x,g5x}, stm32{f1,f2,f3,f4,f7,g4,h7,l1,l4,l5}.



Transmit buffer size

You must call the update() function repeatedly when a transmit buffer is used, otherwise you have to call flushWriteBuffer() to empty the buffer.

Default: 0
Inputs: [0 ... 64Ki-2]


modm:platform:itm modm_platform_itm modm: platform: itm modm_architecture_uart modm: architecture: uart modm_platform_itm->modm_architecture_uart modm_cmsis_device modm: cmsis: device modm_platform_itm->modm_cmsis_device

Limited availability: Check with 'lbuild discover' if this module is available for your target!