Tracing

Overview

The tracing feature provides hooks that permits you to collect data from your application and allows tools running on a host to visualize the inner-working of the kernel and various subsystems.

Every system has application-specific events to trace out. Historically, that has implied:

  1. Determining the application-specific payload,

  2. Choosing suitable serialization-format,

  3. Writing the on-target serialization code,

  4. Deciding on and writing the I/O transport mechanics,

  5. Writing the PC-side deserializer/parser,

  6. Writing custom ad-hoc tools for filtering and presentation.

An application can use one of the existing formats or define a custom format by overriding the macros declared in include/zephyr/tracing/tracing.h.

Different formats, transports and host tools are available and supported in Zephyr.

In fact, I/O varies greatly from system to system. Therefore, it is instructive to create a taxonomy for I/O types when we must ensure the interface between payload/format (Top Layer) and the transport mechanics (bottom Layer) is generic and efficient enough to model these. See the I/O taxonomy section below.

Serialization Formats

Common Trace Format (CTF) Support

Common Trace Format, CTF, is an open format and language to describe trace formats. This enables tool reuse, of which line-textual (babeltrace) and graphical (TraceCompass) variants already exist.

CTF should look familiar to C programmers but adds stronger typing. See CTF - A Flexible, High-performance Binary Trace Format.

CTF allows us to formally describe application specific payload and the serialization format, which enables common infrastructure for host tools and parsers and tools for filtering and presentation.

A Generic Interface

In CTF, an event is serialized to a packet containing one or more fields. As seen from I/O taxonomy section below, a bottom layer may:

  • perform actions at transaction-start (e.g. mutex-lock),

  • process each field in some way (e.g. sync-push emit, concat, enqueue to thread-bound FIFO),

  • perform actions at transaction-stop (e.g. mutex-release, emit of concat buffer).

CTF Top-Layer Example

The CTF_EVENT macro will serialize each argument to a field:

/* Example for illustration */
static inline void ctf_top_foo(uint32_t thread_id, ctf_bounded_string_t name)
{
  CTF_EVENT(
    CTF_LITERAL(uint8_t, 42),
    thread_id,
    name,
    "hello, I was emitted from function: ",
    __func__  /* __func__ is standard since C99 */
  );
}

How to serialize and emit fields as well as handling alignment, can be done internally and statically at compile-time in the bottom-layer.

The CTF top layer is enabled using the configuration option CONFIG_TRACING_CTF and can be used with the different transport backends both in synchronous and asynchronous modes.

SEGGER SystemView Support

Zephyr provides built-in support for SEGGER SystemView that can be enabled in any application for platforms that have the required hardware support.

The payload and format used with SystemView is custom to the application and relies on RTT as a transport. Newer versions of SystemView support other transports, for example UART or using snapshot mode (both still not supported in Zephyr).

To enable tracing support with SEGGER SystemView add the configuration option CONFIG_SEGGER_SYSTEMVIEW to your project configuration file and set it to y. For example, this can be added to the Basic Synchronization sample to visualize fast switching between threads. SystemView can also be used for post-mortem tracing, which can be enabled with CONFIG_SEGGER_SYSVIEW_POST_MORTEM_MODE. In this mode, a debugger can be attached after the system has crashed using west attach after which the latest data from the internal RAM buffer can be loaded into SystemView:

CONFIG_STDOUT_CONSOLE=y
# enable to use thread names
CONFIG_THREAD_NAME=y
CONFIG_SEGGER_SYSTEMVIEW=y
CONFIG_USE_SEGGER_RTT=y
CONFIG_TRACING=y
# enable for post-mortem tracing
CONFIG_SEGGER_SYSVIEW_POST_MORTEM_MODE=n
SEGGER SystemView

Recent versions of SEGGER SystemView come with an API translation table for Zephyr which is incomplete and does not match the current level of support available in Zephyr. To use the latest Zephyr API description table, copy the file available in the tree to your local configuration directory to override the builtin table:

# On Linux and MacOS
cp $ZEPHYR_BASE/subsys/tracing/sysview/SYSVIEW_Zephyr.txt ~/.config/SEGGER/

User-Defined Tracing

This tracing format allows the user to define functions to perform any work desired when a task is switched in or out, when an interrupt is entered or exited, and when the cpu is idle.

Examples include: - simple toggling of GPIO for external scope tracing while minimizing extra cpu load - generating/outputting trace data in a non-standard or proprietary format that can not be supported by the other tracing systems

The following functions can be defined by the user:

void sys_trace_thread_create_user(struct k_thread *thread);
void sys_trace_thread_abort_user(struct k_thread *thread);
void sys_trace_thread_suspend_user(struct k_thread *thread);
void sys_trace_thread_resume_user(struct k_thread *thread);
void sys_trace_thread_name_set_user(struct k_thread *thread);
void sys_trace_thread_switched_in_user(struct k_thread *thread);
void sys_trace_thread_switched_out_user(struct k_thread *thread);
void sys_trace_thread_info_user(struct k_thread *thread);
void sys_trace_thread_sched_ready_user(struct k_thread *thread);
void sys_trace_thread_pend_user(struct k_thread *thread);
void sys_trace_thread_priority_set_user(struct k_thread *thread, int prio);
void sys_trace_isr_enter_user(int nested_interrupts);
void sys_trace_isr_exit_user(int nested_interrupts);
void sys_trace_idle_user();

Enable this format with the CONFIG_TRACING_USER option.

Transport Backends

The following backends are currently supported:

  • UART

  • USB

  • File (Using the native port with POSIX architecture based targets)

  • RTT (With SystemView)

  • RAM (buffer to be retrieved by a debugger)

Using Tracing

The sample samples/subsys/tracing demonstrates tracing with different formats and backends.

To get started, the simplest way is to use the CTF format with the native_sim port, build the sample as follows:

Using west:

west build -b native_sim samples/subsys/tracing -- -DCONF_FILE=prj_native_ctf.conf

Using CMake and ninja:

# Use cmake to configure a Ninja-based buildsystem:
cmake -Bbuild -GNinja -DBOARD=native_sim -DCONF_FILE=prj_native_ctf.conf samples/subsys/tracing

# Now run the build tool on the generated build system:
ninja -Cbuild

You can then run the resulting binary with the option -trace-file to generate the tracing data:

mkdir data
cp $ZEPHYR_BASE/subsys/tracing/ctf/tsdl/metadata data/
./build/zephyr/zephyr.exe -trace-file=data/channel0_0

The resulting CTF output can be visualized using babeltrace or TraceCompass by pointing the tool to the data directory with the metadata and trace files.

Using RAM backend

For devices that do not have available I/O for tracing such as USB or UART but have enough RAM to collect trace data, the ram backend can be enabled with configuration CONFIG_TRACING_BACKEND_RAM. Adjust CONFIG_RAM_TRACING_BUFFER_SIZE to be able to record enough traces for your needs. Then thanks to a runtime debugger such as gdb this buffer can be fetched from the target to an host computer:

(gdb) dump binary memory data/channel0_0 <ram_tracing_start> <ram_tracing_end>

The resulting channel0_0 file have to be placed in a directory with the metadata file like the other backend.

Visualisation Tools

TraceCompass

TraceCompass is an open source tool that visualizes CTF events such as thread scheduling and interrupts, and is helpful to find unintended interactions and resource conflicts on complex systems.

See also the presentation by Ericsson, Advanced Trouble-shooting Of Real-time Systems.

Future LTTng Inspiration

Currently, the top-layer provided here is quite simple and bare-bones, and needlessly copied from Zephyr’s Segger SystemView debug module.

For an OS like Zephyr, it would make sense to draw inspiration from Linux’s LTTng and change the top-layer to serialize to the same format. Doing this would enable direct reuse of TraceCompass’ canned analyses for Linux. Alternatively, LTTng-analyses in TraceCompass could be customized to Zephyr. It is ongoing work to enable TraceCompass visibility of Zephyr in a target-agnostic and open source way.

I/O Taxonomy

  • Atomic Push/Produce/Write/Enqueue:

    • synchronous:

      means data-transmission has completed with the return of the call.

    • asynchronous:

      means data-transmission is pending or ongoing with the return of the call. Usually, interrupts/callbacks/signals or polling is used to determine completion.

    • buffered:

      means data-transmissions are copied and grouped together to form a larger ones. Usually for amortizing overhead (burst dequeue) or jitter-mitigation (steady dequeue).

    Examples:
    • sync unbuffered

      E.g. PIO via GPIOs having steady stream, no extra FIFO memory needed. Low jitter but may be less efficient (can’t amortize the overhead of writing).

    • sync buffered

      E.g. fwrite() or enqueuing into FIFO. Blockingly burst the FIFO when its buffer-waterlevel exceeds threshold. Jitter due to bursts may lead to missed deadlines.

    • async unbuffered

      E.g. DMA, or zero-copying in shared memory. Be careful of data hazards, race conditions, etc!

    • async buffered

      E.g. enqueuing into FIFO.

  • Atomic Pull/Consume/Read/Dequeue:

    • synchronous:

      means data-reception has completed with the return of the call.

    • asynchronous:

      means data-reception is pending or ongoing with the return of the call. Usually, interrupts/callbacks/signals or polling is used to determine completion.

    • buffered:

      means data is copied-in in larger chunks than request-size. Usually for amortizing wait-time.

    Examples:
    • sync unbuffered

      E.g. Blocking read-call, fread() or SPI-read, zero-copying in shared memory.

    • sync buffered

      E.g. Blocking read-call with caching applied. Makes sense if read pattern exhibits spatial locality.

    • async unbuffered

      E.g. zero-copying in shared memory. Be careful of data hazards, race conditions, etc!

    • async buffered

      E.g. aio_read() or DMA.

Unfortunately, I/O may not be atomic and may, therefore, require locking. Locking may not be needed if multiple independent channels are available.

  • The system has non-atomic write and one shared channel

    E.g. UART. Locking required.

    lock(); emit(a); emit(b); emit(c); release();

  • The system has non-atomic write but many channels

    E.g. Multi-UART. Lock-free if the bottom-layer maps each Zephyr thread+ISR to its own channel, thus alleviating races as each thread is sequentially consistent with itself.

    emit(a,thread_id); emit(b,thread_id); emit(c,thread_id);

  • The system has atomic write but one shared channel

    E.g. native_sim or board with DMA. May or may not need locking.

    emit(a ## b ## c); /* Concat to buffer */

    lock(); emit(a); emit(b); emit(c); release(); /* No extra mem */

  • The system has atomic write and many channels

    E.g. native_sim or board with multi-channel DMA. Lock-free.

    emit(a ## b ## c, thread_id);

Object tracking

The kernel can also maintain lists of objects that can be used to track their usage. Currently, the following lists can be enabled:

struct k_timer *_track_list_k_timer;
struct k_mem_slab *_track_list_k_mem_slab;
struct k_sem *_track_list_k_sem;
struct k_mutex *_track_list_k_mutex;
struct k_stack *_track_list_k_stack;
struct k_msgq *_track_list_k_msgq;
struct k_mbox *_track_list_k_mbox;
struct k_pipe *_track_list_k_pipe;
struct k_queue *_track_list_k_queue;
struct k_event *_track_list_k_event;

Those global variables are the head of each list - they can be traversed with the help of macro SYS_PORT_TRACK_NEXT. For instance, to traverse all initialized mutexes, one can write:

struct k_mutex *cur = _track_list_k_mutex;
while (cur != NULL) {
  /* Do something */

  cur = SYS_PORT_TRACK_NEXT(cur);
}

To enable object tracking, enable CONFIG_TRACING_OBJECT_TRACKING. Note that each list can be enabled or disabled via their tracing configuration. For example, to disable tracking of semaphores, one can disable CONFIG_TRACING_SEMAPHORE.

Object tracking is behind tracing configuration as it currently leverages tracing infrastructure to perform the tracking.

API

Common

group subsys_tracing_apis

Tracing APIs.

Functions

void sys_trace_isr_enter(void)

Called when entering an ISR.

void sys_trace_isr_exit(void)

Called when exiting an ISR.

void sys_trace_isr_exit_to_scheduler(void)

Called when exiting an ISR and switching to scheduler.

void sys_trace_idle(void)

Called when the cpu enters the idle state.

Threads

group subsys_tracing_apis_thread

Thread Tracing APIs.

Defines

sys_port_trace_k_thread_foreach_enter()

Called when entering a k_thread_foreach call.

sys_port_trace_k_thread_foreach_exit()

Called when exiting a k_thread_foreach call.

sys_port_trace_k_thread_foreach_unlocked_enter()

Called when entering a k_thread_foreach_unlocked.

sys_port_trace_k_thread_foreach_unlocked_exit()

Called when exiting a k_thread_foreach_unlocked.

sys_port_trace_k_thread_create(new_thread)

Trace creating a Thread.

Parameters:

  • new_thread – Thread object

sys_port_trace_k_thread_user_mode_enter()

Trace Thread entering user mode.

sys_port_trace_k_thread_join_enter(thread, timeout)

Called when entering a k_thread_join.

Parameters:

  • thread – Thread object

  • timeout – Timeout period

sys_port_trace_k_thread_join_blocking(thread, timeout)

Called when k_thread_join blocks.

Parameters:

  • thread – Thread object

  • timeout – Timeout period

sys_port_trace_k_thread_join_exit(thread, timeout, ret)

Called when exiting k_thread_join.

Parameters:

  • thread – Thread object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_thread_sleep_enter(timeout)

Called when entering k_thread_sleep.

Parameters:

  • timeout – Timeout period

sys_port_trace_k_thread_sleep_exit(timeout, ret)

Called when exiting k_thread_sleep.

Parameters:

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_thread_msleep_enter(ms)

Called when entering k_thread_msleep.

Parameters:

  • ms – Duration in milliseconds

sys_port_trace_k_thread_msleep_exit(ms, ret)

Called when exiting k_thread_msleep.

Parameters:

  • ms – Duration in milliseconds

  • ret – Return value

sys_port_trace_k_thread_usleep_enter(us)

Called when entering k_thread_usleep.

Parameters:

  • us – Duration in microseconds

sys_port_trace_k_thread_usleep_exit(us, ret)

Called when exiting k_thread_usleep.

Parameters:

  • us – Duration in microseconds

  • ret – Return value

sys_port_trace_k_thread_busy_wait_enter(usec_to_wait)

Called when entering k_thread_busy_wait.

Parameters:

  • usec_to_wait – Duration in microseconds

sys_port_trace_k_thread_busy_wait_exit(usec_to_wait)

Called when exiting k_thread_busy_wait.

Parameters:

  • usec_to_wait – Duration in microseconds

sys_port_trace_k_thread_yield()

Called when a thread yields.

sys_port_trace_k_thread_wakeup(thread)

Called when a thread wakes up.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_start(thread)

Called when a thread is started.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_abort(thread)

Called when a thread is being aborted.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_abort_enter(thread)

Called when a thread enters the k_thread_abort routine.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_abort_exit(thread)

Called when a thread exits the k_thread_abort routine.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_priority_set(thread)

Called when setting priority of a thread.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_suspend_enter(thread)

Called when a thread enters the k_thread_suspend function.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_suspend_exit(thread)

Called when a thread exits the k_thread_suspend function.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_resume_enter(thread)

Called when a thread enters the resume from suspension function.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_resume_exit(thread)

Called when a thread exits the resumed from suspension function.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_sched_lock()

Called when the thread scheduler is locked.

sys_port_trace_k_thread_sched_unlock()

Called when the thread scheduler is unlocked.

sys_port_trace_k_thread_name_set(thread, ret)

Called when a thread name is set.

Parameters:

  • thread – Thread object

  • ret – Return value

sys_port_trace_k_thread_switched_out()

Called before a thread has been selected to run.

sys_port_trace_k_thread_switched_in()

Called after a thread has been selected to run.

sys_port_trace_k_thread_ready(thread)

Called when a thread is ready to run.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_pend(thread)

Called when a thread is pending.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_info(thread)

Provide information about specific thread.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_sched_wakeup(thread)

Trace implicit thread wakeup invocation by the scheduler.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_sched_abort(thread)

Trace implicit thread abort invocation by the scheduler.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_sched_priority_set(thread, prio)

Trace implicit thread set priority invocation by the scheduler.

Parameters:

  • thread – Thread object

  • prio – Thread priority

sys_port_trace_k_thread_sched_ready(thread)

Trace implicit thread ready invocation by the scheduler.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_sched_pend(thread)

Trace implicit thread pend invocation by the scheduler.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_sched_resume(thread)

Trace implicit thread resume invocation by the scheduler.

Parameters:

  • thread – Thread object

sys_port_trace_k_thread_sched_suspend(thread)

Trace implicit thread suspend invocation by the scheduler.

Parameters:

  • thread – Thread object

Work Queues

group subsys_tracing_apis_work

Work Tracing APIs.

Defines

sys_port_trace_k_work_init(work)

Trace initialisation of a Work structure.

Parameters:

  • work – Work structure

sys_port_trace_k_work_submit_to_queue_enter(queue, work)

Trace submit work to work queue call entry.

Parameters:

  • queue – Work queue structure

  • work – Work structure

sys_port_trace_k_work_submit_to_queue_exit(queue, work, ret)

Trace submit work to work queue call exit.

Parameters:

  • queue – Work queue structure

  • work – Work structure

  • ret – Return value

sys_port_trace_k_work_submit_enter(work)

Trace submit work to system work queue call entry.

Parameters:

  • work – Work structure

sys_port_trace_k_work_submit_exit(work, ret)

Trace submit work to system work queue call exit.

Parameters:

  • work – Work structure

  • ret – Return value

sys_port_trace_k_work_flush_enter(work)

Trace flush work call entry.

Parameters:

  • work – Work structure

sys_port_trace_k_work_flush_blocking(work, timeout)

Trace flush work call blocking.

Parameters:

  • work – Work structure

  • timeout – Timeout period

sys_port_trace_k_work_flush_exit(work, ret)

Trace flush work call exit.

Parameters:

  • work – Work structure

  • ret – Return value

sys_port_trace_k_work_cancel_enter(work)

Trace cancel work call entry.

Parameters:

  • work – Work structure

sys_port_trace_k_work_cancel_exit(work, ret)

Trace cancel work call exit.

Parameters:

  • work – Work structure

  • ret – Return value

sys_port_trace_k_work_cancel_sync_enter(work, sync)

Trace cancel sync work call entry.

Parameters:

  • work – Work structure

  • sync – Sync object

sys_port_trace_k_work_cancel_sync_blocking(work, sync)

Trace cancel sync work call blocking.

Parameters:

  • work – Work structure

  • sync – Sync object

sys_port_trace_k_work_cancel_sync_exit(work, sync, ret)

Trace cancel sync work call exit.

Parameters:

  • work – Work structure

  • sync – Sync object

  • ret – Return value

Poll

group subsys_tracing_apis_poll

Poll Tracing APIs.

Defines

sys_port_trace_k_poll_api_event_init(event)

Trace initialisation of a Poll Event.

Parameters:

  • event – Poll Event

sys_port_trace_k_poll_api_poll_enter(events)

Trace Polling call start.

Parameters:

  • events – Poll Events

sys_port_trace_k_poll_api_poll_exit(events, ret)

Trace Polling call outcome.

Parameters:

  • events – Poll Events

  • ret – Return value

sys_port_trace_k_poll_api_signal_init(signal)

Trace initialisation of a Poll Signal.

Parameters:

  • signal – Poll Signal

sys_port_trace_k_poll_api_signal_reset(signal)

Trace resetting of Poll Signal.

Parameters:

  • signal – Poll Signal

sys_port_trace_k_poll_api_signal_check(signal)

Trace checking of Poll Signal.

Parameters:

  • signal – Poll Signal

sys_port_trace_k_poll_api_signal_raise(signal, ret)

Trace raising of Poll Signal.

Parameters:

  • signal – Poll Signal

  • ret – Return value

Semaphore

group subsys_tracing_apis_sem

Semaphore Tracing APIs.

Defines

sys_port_trace_k_sem_init(sem, ret)

Trace initialisation of a Semaphore.

Parameters:

  • sem – Semaphore object

  • ret – Return value

sys_port_trace_k_sem_give_enter(sem)

Trace giving a Semaphore entry.

Parameters:

  • sem – Semaphore object

sys_port_trace_k_sem_give_exit(sem)

Trace giving a Semaphore exit.

Parameters:

  • sem – Semaphore object

sys_port_trace_k_sem_take_enter(sem, timeout)

Trace taking a Semaphore attempt start.

Parameters:

  • sem – Semaphore object

  • timeout – Timeout period

sys_port_trace_k_sem_take_blocking(sem, timeout)

Trace taking a Semaphore attempt blocking.

Parameters:

  • sem – Semaphore object

  • timeout – Timeout period

sys_port_trace_k_sem_take_exit(sem, timeout, ret)

Trace taking a Semaphore attempt outcome.

Parameters:

  • sem – Semaphore object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_sem_reset(sem)

Trace resetting a Semaphore.

Parameters:

  • sem – Semaphore object

Mutex

group subsys_tracing_apis_mutex

Mutex Tracing APIs.

Defines

sys_port_trace_k_mutex_init(mutex, ret)

Trace initialization of Mutex.

Parameters:

  • mutex – Mutex object

  • ret – Return value

sys_port_trace_k_mutex_lock_enter(mutex, timeout)

Trace Mutex lock attempt start.

Parameters:

  • mutex – Mutex object

  • timeout – Timeout period

sys_port_trace_k_mutex_lock_blocking(mutex, timeout)

Trace Mutex lock attempt blocking.

Parameters:

  • mutex – Mutex object

  • timeout – Timeout period

sys_port_trace_k_mutex_lock_exit(mutex, timeout, ret)

Trace Mutex lock attempt outcome.

Parameters:

  • mutex – Mutex object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_mutex_unlock_enter(mutex)

Trace Mutex unlock entry.

Parameters:

  • mutex – Mutex object

sys_port_trace_k_mutex_unlock_exit(mutex, ret)

Trace Mutex unlock exit.

Condition Variables

group subsys_tracing_apis_condvar

Conditional Variable Tracing APIs.

Defines

sys_port_trace_k_condvar_init(condvar, ret)

Trace initialization of Conditional Variable.

Parameters:

  • condvar – Conditional Variable object

  • ret – Return value

sys_port_trace_k_condvar_signal_enter(condvar)

Trace Conditional Variable signaling start.

Parameters:

  • condvar – Conditional Variable object

sys_port_trace_k_condvar_signal_blocking(condvar, timeout)

Trace Conditional Variable signaling blocking.

Parameters:

  • condvar – Conditional Variable object

  • timeout – Timeout period

sys_port_trace_k_condvar_signal_exit(condvar, ret)

Trace Conditional Variable signaling outcome.

Parameters:

  • condvar – Conditional Variable object

  • ret – Return value

sys_port_trace_k_condvar_broadcast_enter(condvar)

Trace Conditional Variable broadcast enter.

Parameters:

  • condvar – Conditional Variable object

sys_port_trace_k_condvar_broadcast_exit(condvar, ret)

Trace Conditional Variable broadcast exit.

Parameters:

  • condvar – Conditional Variable object

  • ret – Return value

sys_port_trace_k_condvar_wait_enter(condvar)

Trace Conditional Variable wait enter.

Parameters:

  • condvar – Conditional Variable object

sys_port_trace_k_condvar_wait_exit(condvar, ret)

Trace Conditional Variable wait exit.

Parameters:

  • condvar – Conditional Variable object

  • ret – Return value

Queues

group subsys_tracing_apis_queue

Queue Tracing APIs.

Defines

sys_port_trace_k_queue_init(queue)

Trace initialization of Queue.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_cancel_wait(queue)

Trace Queue cancel wait.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_queue_insert_enter(queue, alloc)

Trace Queue insert attempt entry.

Parameters:

  • queue – Queue object

  • alloc – Allocation flag

sys_port_trace_k_queue_queue_insert_blocking(queue, alloc, timeout)

Trace Queue insert attempt blocking.

Parameters:

  • queue – Queue object

  • alloc – Allocation flag

  • timeout – Timeout period

sys_port_trace_k_queue_queue_insert_exit(queue, alloc, ret)

Trace Queue insert attempt outcome.

Parameters:

  • queue – Queue object

  • alloc – Allocation flag

  • ret – Return value

sys_port_trace_k_queue_append_enter(queue)

Trace Queue append enter.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_append_exit(queue)

Trace Queue append exit.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_alloc_append_enter(queue)

Trace Queue alloc append enter.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_alloc_append_exit(queue, ret)

Trace Queue alloc append exit.

Parameters:

  • queue – Queue object

  • ret – Return value

sys_port_trace_k_queue_prepend_enter(queue)

Trace Queue prepend enter.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_prepend_exit(queue)

Trace Queue prepend exit.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_alloc_prepend_enter(queue)

Trace Queue alloc prepend enter.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_alloc_prepend_exit(queue, ret)

Trace Queue alloc prepend exit.

Parameters:

  • queue – Queue object

  • ret – Return value

sys_port_trace_k_queue_insert_enter(queue)

Trace Queue insert attempt entry.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_insert_blocking(queue, timeout)

Trace Queue insert attempt blocking.

Parameters:

  • queue – Queue object

  • timeout – Timeout period

sys_port_trace_k_queue_insert_exit(queue)

Trace Queue insert attempt exit.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_append_list_enter(queue)

Trace Queue append list enter.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_append_list_exit(queue, ret)

Trace Queue append list exit.

Parameters:

  • queue – Queue object

  • ret – Return value

sys_port_trace_k_queue_merge_slist_enter(queue)

Trace Queue merge slist enter.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_merge_slist_exit(queue, ret)

Trace Queue merge slist exit.

Parameters:

  • queue – Queue object

  • ret – Return value

sys_port_trace_k_queue_get_enter(queue, timeout)

Trace Queue get attempt enter.

Parameters:

  • queue – Queue object

  • timeout – Timeout period

sys_port_trace_k_queue_get_blocking(queue, timeout)

Trace Queue get attempt blockings.

Parameters:

  • queue – Queue object

  • timeout – Timeout period

sys_port_trace_k_queue_get_exit(queue, timeout, ret)

Trace Queue get attempt outcome.

Parameters:

  • queue – Queue object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_queue_remove_enter(queue)

Trace Queue remove enter.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_remove_exit(queue, ret)

Trace Queue remove exit.

Parameters:

  • queue – Queue object

  • ret – Return value

sys_port_trace_k_queue_unique_append_enter(queue)

Trace Queue unique append enter.

Parameters:

  • queue – Queue object

sys_port_trace_k_queue_unique_append_exit(queue, ret)

Trace Queue unique append exit.

Parameters:

  • queue – Queue object

  • ret – Return value

sys_port_trace_k_queue_peek_head(queue, ret)

Trace Queue peek head.

Parameters:

  • queue – Queue object

  • ret – Return value

sys_port_trace_k_queue_peek_tail(queue, ret)

Trace Queue peek tail.

Parameters:

  • queue – Queue object

  • ret – Return value

FIFO

group subsys_tracing_apis_fifo

FIFO Tracing APIs.

Defines

sys_port_trace_k_fifo_init_enter(fifo)

Trace initialization of FIFO Queue entry.

Parameters:

  • fifo – FIFO object

sys_port_trace_k_fifo_init_exit(fifo)

Trace initialization of FIFO Queue exit.

Parameters:

  • fifo – FIFO object

sys_port_trace_k_fifo_cancel_wait_enter(fifo)

Trace FIFO Queue cancel wait entry.

Parameters:

  • fifo – FIFO object

sys_port_trace_k_fifo_cancel_wait_exit(fifo)

Trace FIFO Queue cancel wait exit.

Parameters:

  • fifo – FIFO object

sys_port_trace_k_fifo_put_enter(fifo, data)

Trace FIFO Queue put entry.

Parameters:

  • fifo – FIFO object

  • data – Data item

sys_port_trace_k_fifo_put_exit(fifo, data)

Trace FIFO Queue put exit.

Parameters:

  • fifo – FIFO object

  • data – Data item

sys_port_trace_k_fifo_alloc_put_enter(fifo, data)

Trace FIFO Queue alloc put entry.

Parameters:

  • fifo – FIFO object

  • data – Data item

sys_port_trace_k_fifo_alloc_put_exit(fifo, data, ret)

Trace FIFO Queue alloc put exit.

Parameters:

  • fifo – FIFO object

  • data – Data item

  • ret – Return value

sys_port_trace_k_fifo_put_list_enter(fifo, head, tail)

Trace FIFO Queue put list entry.

Parameters:

  • fifo – FIFO object

  • head – First ll-node

  • tail – Last ll-node

sys_port_trace_k_fifo_put_list_exit(fifo, head, tail)

Trace FIFO Queue put list exit.

Parameters:

  • fifo – FIFO object

  • head – First ll-node

  • tail – Last ll-node

sys_port_trace_k_fifo_alloc_put_slist_enter(fifo, list)

Trace FIFO Queue put slist entry.

Parameters:

  • fifo – FIFO object

  • list – Syslist object

sys_port_trace_k_fifo_alloc_put_slist_exit(fifo, list)

Trace FIFO Queue put slist exit.

Parameters:

  • fifo – FIFO object

  • list – Syslist object

sys_port_trace_k_fifo_get_enter(fifo, timeout)

Trace FIFO Queue get entry.

Parameters:

  • fifo – FIFO object

  • timeout – Timeout period

sys_port_trace_k_fifo_get_exit(fifo, timeout, ret)

Trace FIFO Queue get exit.

Parameters:

  • fifo – FIFO object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_fifo_peek_head_enter(fifo)

Trace FIFO Queue peek head entry.

Parameters:

  • fifo – FIFO object

sys_port_trace_k_fifo_peek_head_exit(fifo, ret)

Trace FIFO Queue peek head exit.

Parameters:

  • fifo – FIFO object

  • ret – Return value

sys_port_trace_k_fifo_peek_tail_enter(fifo)

Trace FIFO Queue peek tail entry.

Parameters:

  • fifo – FIFO object

sys_port_trace_k_fifo_peek_tail_exit(fifo, ret)

Trace FIFO Queue peek tail exit.

Parameters:

  • fifo – FIFO object

  • ret – Return value

LIFO

group subsys_tracing_apis_lifo

LIFO Tracing APIs.

Defines

sys_port_trace_k_lifo_init_enter(lifo)

Trace initialization of LIFO Queue entry.

Parameters:

  • lifo – LIFO object

sys_port_trace_k_lifo_init_exit(lifo)

Trace initialization of LIFO Queue exit.

Parameters:

  • lifo – LIFO object

sys_port_trace_k_lifo_put_enter(lifo, data)

Trace LIFO Queue put entry.

Parameters:

  • lifo – LIFO object

  • data – Data item

sys_port_trace_k_lifo_put_exit(lifo, data)

Trace LIFO Queue put exit.

Parameters:

  • lifo – LIFO object

  • data – Data item

sys_port_trace_k_lifo_alloc_put_enter(lifo, data)

Trace LIFO Queue alloc put entry.

Parameters:

  • lifo – LIFO object

  • data – Data item

sys_port_trace_k_lifo_alloc_put_exit(lifo, data, ret)

Trace LIFO Queue alloc put exit.

Parameters:

  • lifo – LIFO object

  • data – Data item

  • ret – Return value

sys_port_trace_k_lifo_get_enter(lifo, timeout)

Trace LIFO Queue get entry.

Parameters:

  • lifo – LIFO object

  • timeout – Timeout period

sys_port_trace_k_lifo_get_exit(lifo, timeout, ret)

Trace LIFO Queue get exit.

Parameters:

  • lifo – LIFO object

  • timeout – Timeout period

  • ret – Return value

Stacks

group subsys_tracing_apis_stack

Stack Tracing APIs.

Defines

sys_port_trace_k_stack_init(stack)

Trace initialization of Stack.

Parameters:

  • stack – Stack object

sys_port_trace_k_stack_alloc_init_enter(stack)

Trace Stack alloc init attempt entry.

Parameters:

  • stack – Stack object

sys_port_trace_k_stack_alloc_init_exit(stack, ret)

Trace Stack alloc init outcome.

Parameters:

  • stack – Stack object

  • ret – Return value

sys_port_trace_k_stack_cleanup_enter(stack)

Trace Stack cleanup attempt entry.

Parameters:

  • stack – Stack object

sys_port_trace_k_stack_cleanup_exit(stack, ret)

Trace Stack cleanup outcome.

Parameters:

  • stack – Stack object

  • ret – Return value

sys_port_trace_k_stack_push_enter(stack)

Trace Stack push attempt entry.

Parameters:

  • stack – Stack object

sys_port_trace_k_stack_push_exit(stack, ret)

Trace Stack push attempt outcome.

Parameters:

  • stack – Stack object

  • ret – Return value

sys_port_trace_k_stack_pop_enter(stack, timeout)

Trace Stack pop attempt entry.

Parameters:

  • stack – Stack object

  • timeout – Timeout period

sys_port_trace_k_stack_pop_blocking(stack, timeout)

Trace Stack pop attempt blocking.

Parameters:

  • stack – Stack object

  • timeout – Timeout period

sys_port_trace_k_stack_pop_exit(stack, timeout, ret)

Trace Stack pop attempt outcome.

Parameters:

  • stack – Stack object

  • timeout – Timeout period

  • ret – Return value

Message Queues

group subsys_tracing_apis_msgq

Message Queue Tracing APIs.

Defines

sys_port_trace_k_msgq_init(msgq)

Trace initialization of Message Queue.

Parameters:

  • msgq – Message Queue object

sys_port_trace_k_msgq_alloc_init_enter(msgq)

Trace Message Queue alloc init attempt entry.

Parameters:

  • msgq – Message Queue object

sys_port_trace_k_msgq_alloc_init_exit(msgq, ret)

Trace Message Queue alloc init attempt outcome.

Parameters:

  • msgq – Message Queue object

  • ret – Return value

sys_port_trace_k_msgq_cleanup_enter(msgq)

Trace Message Queue cleanup attempt entry.

Parameters:

  • msgq – Message Queue object

sys_port_trace_k_msgq_cleanup_exit(msgq, ret)

Trace Message Queue cleanup attempt outcome.

Parameters:

  • msgq – Message Queue object

  • ret – Return value

sys_port_trace_k_msgq_put_enter(msgq, timeout)

Trace Message Queue put attempt entry.

Parameters:

  • msgq – Message Queue object

  • timeout – Timeout period

sys_port_trace_k_msgq_put_blocking(msgq, timeout)

Trace Message Queue put attempt blocking.

Parameters:

  • msgq – Message Queue object

  • timeout – Timeout period

sys_port_trace_k_msgq_put_exit(msgq, timeout, ret)

Trace Message Queue put attempt outcome.

Parameters:

  • msgq – Message Queue object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_msgq_get_enter(msgq, timeout)

Trace Message Queue get attempt entry.

Parameters:

  • msgq – Message Queue object

  • timeout – Timeout period

sys_port_trace_k_msgq_get_blocking(msgq, timeout)

Trace Message Queue get attempt blockings.

Parameters:

  • msgq – Message Queue object

  • timeout – Timeout period

sys_port_trace_k_msgq_get_exit(msgq, timeout, ret)

Trace Message Queue get attempt outcome.

Parameters:

  • msgq – Message Queue object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_msgq_peek(msgq, ret)

Trace Message Queue peek.

Parameters:

  • msgq – Message Queue object

  • ret – Return value

sys_port_trace_k_msgq_purge(msgq)

Trace Message Queue purge.

Parameters:

  • msgq – Message Queue object

Mailbox

group subsys_tracing_apis_mbox

Mailbox Tracing APIs.

Defines

sys_port_trace_k_mbox_init(mbox)

Trace initialization of Mailbox.

Parameters:

  • mbox – Mailbox object

sys_port_trace_k_mbox_message_put_enter(mbox, timeout)

Trace Mailbox message put attempt entry.

Parameters:

  • mbox – Mailbox object

  • timeout – Timeout period

sys_port_trace_k_mbox_message_put_blocking(mbox, timeout)

Trace Mailbox message put attempt blocking.

Parameters:

  • mbox – Mailbox object

  • timeout – Timeout period

sys_port_trace_k_mbox_message_put_exit(mbox, timeout, ret)

Trace Mailbox message put attempt outcome.

Parameters:

  • mbox – Mailbox object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_mbox_put_enter(mbox, timeout)

Trace Mailbox put attempt entry.

Parameters:

  • mbox – Mailbox object

  • timeout – Timeout period

sys_port_trace_k_mbox_put_exit(mbox, timeout, ret)

Trace Mailbox put attempt blocking.

Parameters:

  • mbox – Mailbox object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_mbox_async_put_enter(mbox, sem)

Trace Mailbox async put entry.

Parameters:

  • mbox – Mailbox object

  • sem – Semaphore object

sys_port_trace_k_mbox_async_put_exit(mbox, sem)

Trace Mailbox async put exit.

Parameters:

  • mbox – Mailbox object

  • sem – Semaphore object

sys_port_trace_k_mbox_get_enter(mbox, timeout)

Trace Mailbox get attempt entry.

Parameters:

  • mbox – Mailbox entry

  • timeout – Timeout period

sys_port_trace_k_mbox_get_blocking(mbox, timeout)

Trace Mailbox get attempt blocking.

Parameters:

  • mbox – Mailbox entry

  • timeout – Timeout period

sys_port_trace_k_mbox_get_exit(mbox, timeout, ret)

Trace Mailbox get attempt outcome.

Parameters:

  • mbox – Mailbox entry

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_mbox_data_get(rx_msg)

Trace Mailbox data get.

rx_msg Receive Message object

Pipes

group subsys_tracing_apis_pipe

Pipe Tracing APIs.

Defines

sys_port_trace_k_pipe_init(pipe)

Trace initialization of Pipe.

Parameters:

  • pipe – Pipe object

sys_port_trace_k_pipe_cleanup_enter(pipe)

Trace Pipe cleanup entry.

Parameters:

  • pipe – Pipe object

sys_port_trace_k_pipe_cleanup_exit(pipe, ret)

Trace Pipe cleanup exit.

Parameters:

  • pipe – Pipe object

  • ret – Return value

sys_port_trace_k_pipe_alloc_init_enter(pipe)

Trace Pipe alloc init entry.

Parameters:

  • pipe – Pipe object

sys_port_trace_k_pipe_alloc_init_exit(pipe, ret)

Trace Pipe alloc init exit.

Parameters:

  • pipe – Pipe object

  • ret – Return value

sys_port_trace_k_pipe_flush_enter(pipe)

Trace Pipe flush entry.

Parameters:

  • pipe – Pipe object

sys_port_trace_k_pipe_flush_exit(pipe)

Trace Pipe flush exit.

Parameters:

  • pipe – Pipe object

sys_port_trace_k_pipe_buffer_flush_enter(pipe)

Trace Pipe buffer flush entry.

Parameters:

  • pipe – Pipe object

sys_port_trace_k_pipe_buffer_flush_exit(pipe)

Trace Pipe buffer flush exit.

Parameters:

  • pipe – Pipe object

sys_port_trace_k_pipe_put_enter(pipe, timeout)

Trace Pipe put attempt entry.

Parameters:

  • pipe – Pipe object

  • timeout – Timeout period

sys_port_trace_k_pipe_put_blocking(pipe, timeout)

Trace Pipe put attempt blocking.

Parameters:

  • pipe – Pipe object

  • timeout – Timeout period

sys_port_trace_k_pipe_put_exit(pipe, timeout, ret)

Trace Pipe put attempt outcome.

Parameters:

  • pipe – Pipe object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_pipe_get_enter(pipe, timeout)

Trace Pipe get attempt entry.

Parameters:

  • pipe – Pipe object

  • timeout – Timeout period

sys_port_trace_k_pipe_get_blocking(pipe, timeout)

Trace Pipe get attempt blocking.

Parameters:

  • pipe – Pipe object

  • timeout – Timeout period

sys_port_trace_k_pipe_get_exit(pipe, timeout, ret)

Trace Pipe get attempt outcome.

Parameters:

  • pipe – Pipe object

  • timeout – Timeout period

  • ret – Return value

Heaps

group subsys_tracing_apis_heap

Heap Tracing APIs.

Defines

sys_port_trace_k_heap_init(h)

Trace initialization of Heap.

Parameters:

  • h – Heap object

sys_port_trace_k_heap_aligned_alloc_enter(h, timeout)

Trace Heap aligned alloc attempt entry.

Parameters:

  • h – Heap object

  • timeout – Timeout period

sys_port_trace_k_heap_aligned_alloc_blocking(h, timeout)

Trace Heap align alloc attempt blocking.

Parameters:

  • h – Heap object

  • timeout – Timeout period

sys_port_trace_k_heap_aligned_alloc_exit(h, timeout, ret)

Trace Heap align alloc attempt outcome.

Parameters:

  • h – Heap object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_heap_alloc_enter(h, timeout)

Trace Heap alloc enter.

Parameters:

  • h – Heap object

  • timeout – Timeout period

sys_port_trace_k_heap_alloc_exit(h, timeout, ret)

Trace Heap alloc exit.

Parameters:

  • h – Heap object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_heap_free(h)

Trace Heap free.

Parameters:

  • h – Heap object

sys_port_trace_k_heap_sys_k_aligned_alloc_enter(heap)

Trace System Heap aligned alloc enter.

Parameters:

  • heap – Heap object

sys_port_trace_k_heap_sys_k_aligned_alloc_exit(heap, ret)

Trace System Heap aligned alloc exit.

Parameters:

  • heap – Heap object

  • ret – Return value

sys_port_trace_k_heap_sys_k_malloc_enter(heap)

Trace System Heap aligned alloc enter.

Parameters:

  • heap – Heap object

sys_port_trace_k_heap_sys_k_malloc_exit(heap, ret)

Trace System Heap aligned alloc exit.

Parameters:

  • heap – Heap object

  • ret – Return value

sys_port_trace_k_heap_sys_k_free_enter(heap, heap_ref)

Trace System Heap free entry.

Parameters:

  • heap – Heap object

  • heap_ref – Heap reference

sys_port_trace_k_heap_sys_k_free_exit(heap, heap_ref)

Trace System Heap free exit.

Parameters:

  • heap – Heap object

  • heap_ref – Heap reference

sys_port_trace_k_heap_sys_k_calloc_enter(heap)

Trace System heap calloc enter.

Parameters:

  • heap –

sys_port_trace_k_heap_sys_k_calloc_exit(heap, ret)

Trace System heap calloc exit.

Parameters:

  • heap – Heap object

  • ret – Return value

Memory Slabs

group subsys_tracing_apis_mslab

Memory Slab Tracing APIs.

Defines

sys_port_trace_k_mem_slab_init(slab, rc)

Trace initialization of Memory Slab.

Parameters:

  • slab – Memory Slab object

  • rc – Return value

sys_port_trace_k_mem_slab_alloc_enter(slab, timeout)

Trace Memory Slab alloc attempt entry.

Parameters:

  • slab – Memory Slab object

  • timeout – Timeout period

sys_port_trace_k_mem_slab_alloc_blocking(slab, timeout)

Trace Memory Slab alloc attempt blocking.

Parameters:

  • slab – Memory Slab object

  • timeout – Timeout period

sys_port_trace_k_mem_slab_alloc_exit(slab, timeout, ret)

Trace Memory Slab alloc attempt outcome.

Parameters:

  • slab – Memory Slab object

  • timeout – Timeout period

  • ret – Return value

sys_port_trace_k_mem_slab_free_enter(slab)

Trace Memory Slab free entry.

Parameters:

  • slab – Memory Slab object

sys_port_trace_k_mem_slab_free_exit(slab)

Trace Memory Slab free exit.

Parameters:

  • slab – Memory Slab object

Timers

group subsys_tracing_apis_timer

Timer Tracing APIs.

Defines

sys_port_trace_k_timer_init(timer)

Trace initialization of Timer.

Parameters:

  • timer – Timer object

sys_port_trace_k_timer_start(timer, duration, period)

Trace Timer start.

Parameters:

  • timer – Timer object

  • duration – Timer duration

  • period – Timer period

sys_port_trace_k_timer_stop(timer)

Trace Timer stop.

Parameters:

  • timer – Timer object

sys_port_trace_k_timer_status_sync_enter(timer)

Trace Timer status sync entry.

Parameters:

  • timer – Timer object

sys_port_trace_k_timer_status_sync_blocking(timer, timeout)

Trace Timer Status sync blocking.

Parameters:

  • timer – Timer object

  • timeout – Timeout period

sys_port_trace_k_timer_status_sync_exit(timer, result)

Trace Time Status sync outcome.

Parameters:

  • timer – Timer object

  • result – Return value

Object tracking

group subsys_tracing_object_tracking

Object tracking.

Object tracking provides lists to kernel objects, so their existence and current status can be tracked.

The following global variables are the heads of available lists:

  • _track_list_k_timer

  • _track_list_k_mem_slab

  • _track_list_k_sem

  • _track_list_k_mutex

  • _track_list_k_stack

  • _track_list_k_msgq

  • _track_list_k_mbox

  • _track_list_k_pipe

  • _track_list_k_queue

  • _track_list_k_event

Defines

SYS_PORT_TRACK_NEXT(list)

Gets node’s next element in a object tracking list.

Parameters:

  • list – Node to get next element from.

Syscalls

group subsys_tracing_apis_syscall

Syscall Tracing APIs.

Defines

sys_port_trace_syscall_enter(id, name, ...)

Trace syscall entry.

Parameters:

  • id – Syscall ID (as defined in the generated syscall_list.h)

  • name – Syscall name as a token (ex: k_thread_create)

  • ... – Other parameters passed to the syscall

sys_port_trace_syscall_exit(id, name, ...)

Trace syscall exit.

Parameters:

  • id – Syscall ID (as defined in the generated syscall_list.h)

  • name – Syscall name as a token (ex: k_thread_create)

  • ... – Other parameters passed to the syscall, if the syscall has a return, the return value is the last parameter in the list