Zephelin usage examples

This chapter provides links to relevant resources, application examples and Trace Viewer views.

Note

For details on how each demo is executed, open the collapsible description of the launch example.

Before running commands, make sure you went through Initializing the workspace and Running sample project in Zephelin as it is needed to prepare the environment.

Using code scopes

This sample demonstrates the usage of ZPL_MARK_CODE_SCOPE which was described in Code scopes chapter.

Generating traces for code with scopes defined

To build a sample run:

west build -p -b max32690fthr/max32690/m4 samples/basic/marking_code_scopes -- -DCONFIG_ZPL_TRACE_FORMAT_CTF=y -DCONFIG_TRACING_BUFFER_SIZE=10000 -DCONFIG_BOOT_BANNER=n -DCONFIG_PRINTK=n -DCONFIG_LOG=n

The traces can be either obtained from hardware or a Renode simulation with:

For Renode, the simulation and collection of traces can be done with:

python3 ./scripts/run_renode.py --trace-output ./trace.ctf --timeout 45

Then, the TEF traces can be created with west zpl-prepare-trace like so:

west zpl-prepare-trace ./trace.ctf -o ./tef_marking_code_scopes.json

In the end, the generated tef_marking_code_scopes.json can be loaded in Trace Viewer.

Simple TFLite Micro profiling

This sample demonstrates tracing of the TensorFlow Lite Micro (or LiteRT) runtime. The collection of traces is performed as usual, but in west zpl-prepare-trace you need to provide the --tflm-model-path <path-to-model> flag with the used model.

Generating traces for TFLite Micro runtime

To build a sample, run:

west build -p -b max32690fthr/max32690/m4 samples/profiling/tflm_profiler -- -DCONFIG_ZPL_TRACE_FORMAT_CTF=y -DCONFIG_TRACING_BUFFER_SIZE=10000 -DCONFIG_BOOT_BANNER=n -DCONFIG_PRINTK=n -DCONFIG_LOG=n

The traces can be either obtained from hardware or a Renode simulation with:

For Renode, the simulation and collection of traces can be done with:

python3 ./scripts/run_renode.py --trace-output ./trace.ctf --timeout 45

Then, the TEF traces can be created with west zpl-prepare-trace like so:

west zpl-prepare-trace ./trace.ctf \
  --tflm-model-path ./samples/common/tflm/model/magic-wand.tflite \
  -o ./tef_tflm_profiler.json

In the end, the generated tef_tflm_profiler.json can be loaded in Trace Viewer.

Simple microTVM profiling

This sample demonstrates tracing of the microTVM runtime. The collection of traces is performed as usual, but in west zpl-prepare-trace you need to provide:

  • --tvm-model-path <path-to-model-graph> - path to JSON with model graph

  • --tvm-model-metadata-path <path-to-metadata> - path to metadata from compilation results

For more details on the above flags, check CTF to TEF conversion.

Generating traces for microTVM runtime

To build a sample run:

west build -p -b max32690fthr/max32690/m4 samples/profiling/tvm_profiler -- -DCONFIG_ZPL_TRACE_FORMAT_CTF=y -DCONFIG_TRACING_BUFFER_SIZE=10000 -DCONFIG_BOOT_BANNER=n -DCONFIG_PRINTK=n -DCONFIG_LOG=n

The traces can be either obtained from hardware or a Renode simulation with:

For Renode, the simulation and collection of traces can be done with:

python3 ./scripts/run_renode.py --trace-output ./trace.ctf --timeout 45

Then, the TEF traces can be created with west zpl-prepare-trace like so:

west zpl-prepare-trace ./trace.ctf \
  --tvm-model-path ./samples/common/tvm/model/magic-wand-graph.json \
  --tvm-model-metadata-path ./samples/common/tvm/model/magic-wand-metadata.json \
  -o ./tef_tvm_profiler.json

In the end, the generated tef_tvm_profiler.json can be loaded in Trace Viewer.

Full TFLite Micro traces with instrumentation using separate UART connection for instrumentation traces

This sample demonstrates combining Zephelin tracing with enabled instrumentation and additional metrics.

The collection of traces is performed using west zpl-instrumentation-uart-gdb-capture which collects:

  • Instrumentation data using UART

  • Zephelin data using GDB backend

In this scenario, you need to provide the instrumentation traces separately using the -i flag.

Check CTF to TEF conversion for more details.

Collecting regular and instrumentation traces

To build a sample run:

west build -p -b max32690fthr/max32690/m4 samples/profiling/tflm_instrumentation -- -DEXTRA_CONF_FILE="instrumentation_uart.conf;zpl.conf"

Secondly, flash the device or run a simulation and collect traces:

For Renode, the simulation and collection of traces can be done with:

python3 ./scripts/run_renode.py --simulation-only --debug

This can run in a separate shell, since traces in this case will be obtained separately with the following command:

west zpl-instrumentation-uart-gdb-capture /tmp/uart-log 115200 ./renode_tflm.instr.ctf ./renode_tflm.gdb.ctf --no-debug-server --timeout 20

Then, the TEF traces can be created with west zpl-prepare-trace like so:

west zpl-prepare-trace -o tef_tflm_instrumentation.json -i renode_tflm.instr.ctf renode_tflm.gdb.ctf --tflm-model-path ./samples/common/tflm/model/sine.tflite --trim-metadata

In the end, the generated tef_tflm_instrumentation.json can be loaded in Trace Viewer.

Note

The renode_tflm.instr.ctf can be saved under a different path (e.g. renode_tflm.instr.ctf) due to resets - check paths reported by west zpl-instrumentation-uart-gdb-capture and update the command accordingly.

Full TFLite Micro traces with instrumentation sent through tracing subsystem

This sample demonstrates how to collect regular traces, custom traces, execution metrics, model-specific metrics and instrumentation traces using only the tracing subsystem transport, without delivering instrumentation traces separately.

In this scenario, instead of west zpl-instrumentation-uart-gdb-capture, you can use regular Zephelin capture commands, such as west zpl-uart-capture.

Collecting regular and instrumentation traces using zpl-uart-capture

To build a sample, run:

west build -p -b max32690fthr/max32690/m4 samples/profiling/tflm_instrumentation -- -DEXTRA_CONF_FILE="instrumentation_tracing.conf;zpl.conf"

Secondly, flash the device or run a simulation and collect traces:

For Renode, the simulation and collection of traces can be done with:

python3 ./scripts/run_renode.py --trace-output ./trace.ctf --timeout 45

Then, the TEF traces can be created with west zpl-prepare-trace like so:

west zpl-prepare-trace ./trace.ctf \
  --tflm-model-path ./samples/common/tflm/model/sine.tflite \
  -o ./tef_tflm_instrumentation_tracing.json

In the end, the generated ./tef_tflm_instrumentation_tracing.json can be loaded in Trace Viewer.

Multithreaded application running multiple models

Zephelin allows for tracing of applications running on multiple threads and cores with no additional configuration changes. Each event contains the ID of the CPU which emitted it; this ID is used during parsing traces.

This sample loads four simple models using TVM runtime. Those models are then executed on different CPUs using random input data generated by the main thread.

Tracing multiple threads with Zephelin

To build a sample, run:

west build -p -b  mpfs_icicle/polarfire/u54/smp samples/profiling/smp_tvm

Note

The mpfs_icicle/polarfire/u54/smp is used to demonstrate the work on several cores.

The above sample can be executed on hardware or simulated in Renode with:

python ./scripts/run_renode.py --trace-output ./smp.ctf

Finally, to parse produced ./smp.ctf run:

west zpl-prepare-trace ./smp.ctf -o ./tef_smp_tvm_models.json \
  --tvm-model-paths ./samples/common/tvm/model/sine-graph.json \
    ./samples/common/tvm/model/magic-wand-graph.json \
  --tvm-model-metadata-paths ./samples/common/tvm/model/sine-metadata.json \
    ./samples/common/tvm/model/magic-wand-metadata.json \
  --tvm-model-op-remove-prefix 'tvmgen_[a-zA-Z0-9]+_fused_' \
  --trim-metadata

In the Trace Viewer, there should be a separate thread for each model; each of those threads should contain events produced by that model.

Simple tracing of two applications running on different SoCs with common external clock

This sample demonstrates the tracing of two Zephyr applications running on separate boards.

Those boards share a common clock provider, allowing for traces to be synchronized. An artificial time offset is introduced for demonstration purposes.

Tracing the same solution on two machines

To build a sample, run:

west build -p -b max32650fthr --sysbuild samples/multi_machine/two_models/node_0 -- \
   -Dnode_0_CONFIG_ZPL_TRACE_FORMAT_CTF=y \
   -Dnode_0_CONFIG_TRACING_BUFFER_SIZE=10000 \
   -Dnode_1_CONFIG_ZPL_TRACE_FORMAT_CTF=y \
   -Dnode_1_CONFIG_TRACING_BUFFER_SIZE=10000

The demonstration uses the same application for both boards.

The above sample can be simulated in Renode with:

python3 ./scripts/run_renode_multimachine.py \
	--boards max32650fthr max32650fthr \
	--elfs build/node_0/zephyr/zephyr.elf build/node_1/zephyr/zephyr.elf \
	--trace_uarts uart0 uart0 \
	--shared_clock_address 0x400FFFF0 \
	--offset 2000 \
	--trace-output ./trace.ctf \
	--timeout 20

To parse the produced ./trace.ctf and ./trace_1.ctf, run:

west zpl-prepare-trace ./trace.ctf \
  --build-dir build/node_0 \
  --tflm-model-path ./samples/common/tflm/model/magic-wand.tflite \
  --zephyr-elf-path build/node_0/zephyr/zephyr.elf \
  -o ./tef_tflm_profiler_0.json
west zpl-prepare-trace ./trace_1.ctf \
  --build-dir build/node_1 \
  --tflm-model-path ./samples/common/tflm/model/magic-wand.tflite \
  --zephyr-elf-path build/node_1/zephyr/zephyr.elf \
  -o ./tef_tflm_profiler_1.json

In Trace Viewer, traces from the same model run should be available but with 2s offset between them.

Preprocessing to micro-speech pipeline

This sample demonstrates deployment of a Micro-speech model on two SoCs connected via UART. The preprocessor running on the first SoC converts a raw audio sample into a spectrographic feature. The processed data is passed via UART to the second SoC, which runs a Micro-speech model once sufficient data has been accumulated. The model responses can be yes, no, silence and undefined. The sample expects .h files as input. To prepare the .wav file, you can use following script. Example usage:

python3 wav_to_h.py input.wav output.h
Micro-speech pipeline

To build a sample, run:

west build -p -b max32650fthr --sysbuild samples/multi_machine/micro_speech/micro_speech -- \
   -Dmicro_speech_CONFIG_ZPL_TRACE_FORMAT_CTF=y \
   -Dmicro_speech_CONFIG_TRACING_BUFFER_SIZE=10000 \
   -Dpreprocessor_CONFIG_ZPL_TRACE_FORMAT_CTF=y \
   -Dpreprocessor_CONFIG_TRACING_BUFFER_SIZE=10000

The above sample can be executed on hardware or simulated in Renode with:

python3 ./scripts/run_renode_multimachine.py \
--boards max32650fthr max32650fthr \
--elfs build/micro_speech/zephyr/zephyr.elf build/preprocessor/zephyr/zephyr.elf \
--repls samples/multi_machine/boards/max32650fthr.repl samples/multi_machine/boards/max32650fthr.repl \
--trace_uarts uart0 uart0 \
--uart-connect uart1 \
--shared-clock-address 0x400FFFF0 \
--trace-output micro_speech.ctf \
--timeout 45

To parse the produced ./microspeech.ctf and ./microspeech_1.ctf, run:

west zpl-prepare-trace ./micro_speech.ctf \
  --build-dir build/micro_speech \
  --tflm-model-path ./samples/common/tflm/model/micro_speech_quantized.tflite \
  -o ./tef_micro_speech.json \
  --zephyr-elf-path build/micro_speech/zephyr/zephyr.elf

west zpl-prepare-trace ./micro_speech_1.ctf \
  --build-dir build/micro_speech \
  --tflm-model-path ./samples/common/tflm/model/audio_preprocessor_int8.tflite \
  -o ./tef_preprocessor.json \
  --zephyr-elf-path build/preprocessor/zephyr/zephyr.elf
Last update: 2026-08-28