Purpose
This document holds information about how the Design Studio and S32Debugger probe can be used to debug Zephyr OS (Operating System) applications running on NXP’ S32 family processors.
Scope
This document is addressed to the software developer or tester (referred below as user) looking to debug or verify its software using the S32Debugger probe.
The document assumes the user has basic knowledge about Zephyr OS and he can rebuild the image with debug configuration.
The information about the building of the Zephyr application using NXP’s Zephyr distribution is not in the scope of this document. This is part of the user manual delivered with the Zephyr NXP release.
Hardware support
This support is available for Cortex-A53 and Cortex-R52 cores only.
It has been confirmed on S32R41, S32R45 and S32Z/E SoCs (System on Chip).
Software support
This feature is available starting with Design Studio 3.5.3.
It is confirmed with Zephyr OS versions 2.7.2 (S32R41), 3.2.0 (S32Z/E), 3.3.0 (S32R41).
Background
Zephyr is a lightweight RTOS (Real Time Operating System) that supplies support for multiple architectures (aarch64, arm, riscv, x86).
The thread awareness support stands for the capability of the debugger to supply low-level information about OS threads (referred below as standard support) or system-level OS information (referred below as extended support).
Standard support
Design Studio can supply low-level information about Zephyr threads:
- Name
- State
- CPU registers - including FPU (Floating Point Unit)
- Call stack
- Priority
- User options
- Core number
Prerequisites
S32Debugger automatically detects the Zephyr OS image using the specific debug symbols.
The Zephyr application image should include the following configuration options:
|
Mandatory |
If this choice is not set, the debugger is not able to parse the kernel internal data. In debug view, the user will see one thread only and no extra information about this. |
Debug window
The Zephyr threads are listed in the Debug window when the CPU is stopped.
This is an example about how to follow thread entry can be read:
The Thread with index #15 and thread ID 868402064 (TCB (Thread Control Block) address in decimal format) is running on the CPU core 0 and it is in the Stopped state.
It has running priority 15, the user options 0x01 and its name is “idle 00”.
This is suspended in a breakpoint set in function arch_cpu_idle();
Thread states
The thread states names reported by debugger are accordingly with the output of the kernel function k_thread_state_str() excluding Stopped, that is the active Zephyr thread suspended by debugger.
|
Thread’s state values: |
|
Stopped |
|
Dummy |
|
Pending |
|
Prestart |
|
Dead |
|
Suspended |
|
Aborting |
|
Queued |
CPU registers
The CPU registers of the thread selected in the Debug window can be read from the Registers window. This window is updated automatically when other thread is selected.
Known limitations
- The warning message “ccs: Invalid parameter” is printed twice into the Design Studio IDE console (for S32Z/E only).
These can be ignored because the functionality is not affected.
- Breakpoint per thread is not supported
- Write thread registers is not supported (excluding the thread in state Stopped)
- Performance may be affected by high number of Zephyr threads
- FPU registers read support requires patch of Zephyr OS to save the offset in the table for ARM64 build. This is the snippet code that must be added in the initialization of _kernel_thread_info_offsets into file thread_info.c
#elif defined(CONFIG_FPU) && defined(CONFIG_FPU_SHARING) && defined(CONFIG_ARM64) [THREAD_INFO_OFFSET_T_PREEMPT_FLOAT] = offsetof(struct _thread_arch, saved_fp_context),
[THREAD_INFO_OFFSET_T_COOP_FLOAT] = THREAD_INFO_UNIMPLEMENTED,
Extended support
Design Studio can supply system-level information about Zephyr OS resources like:
- Timer
- Semaphore
- Mutex
- Stack
- Message queue
- Mailboxes
- Pipes
- Queues
- Threads
This implementation is not CPU architecture specific like standard support.
Prerequisites
The Zephyr application image should include the following configuration options:
|
Mandatory |
If this choice is not set, the debugger is not able to parse kernel internal data and to supply information about resource owners or waiting lists. |
|
|
CONFIG_TRACING CONFIG_TRACING_OBJECT_TRACKING CONFIG_TRACING_NONE |
Mandatory |
Enable the kernel object tracking. If this is not set, the debugger can show system information about Threads only. Note: This configuration is working on Zephyr version 3.0.0 or higher. |
|
CONFIG_INIT_STACKS |
Optional |
Enable the fill of stack with a marker that can be used by debugger to report the peak stack usage. This information might be useful for stack size tunning. |
|
CONFIG_THREAD_STACK_INFO |
Recommended |
The debugger supplies information about the stack (address, size or usage). |
GDB (GNU Debugger)
This support is available through extended GDB commands.
|
Command name |
Description |
|
thread-aware-list-supported-os |
List the supported OS types and the detected OS |
|
thread-aware-list-supported-objs |
List the supported kernel objects by the detected or specified OS. This is based on types used by the current image only. |
|
thread-aware-read-objs |
Read the specified or all objects supported by current image. |
These commands can be configured to supply the output in JSON (JavaScript Object Notation) or table format.
Use the help command to get more information about these thread awareness commands.
Figure 2 GDB - Get Thread, Mutex & Semaphore info
Common attributes
Most of the object's attributes are type specific with 2 exceptions:
|
Attribute name |
Description |
Format |
|
S32Debugger Zephyr Thread Awareness |
User Manual v1.3 |
|
address |
Object data address |
integer |
|
name |
ELF Symbol name |
string |
Thread attributes
|
Attribute name |
Description |
Format |
|
user_options |
User options |
integer |
|
state |
Thread state – see Thread states |
string |
|
prio |
Thread priority |
integer |
|
stack_addr |
|
integer |
|
stack_delta |
|
integer |
|
stack_size |
|
integer |
|
stack_usage_max |
Largest stack usage |
float |
|
stack_usage |
Current stack usage |
float |
MemSlab attributes
|
Attribute name |
Description |
Format |
|
num_blocks |
|
integer |
|
block_size |
|
integer |
|
buffer |
|
integer |
|
free_list |
|
integer |
|
num_used |
|
integer |
|
locked |
Locked by this thread (name) |
string |
|
waiting |
Threads (name) waiting for this object |
string list |
Queue attributes
|
Attribute name |
Description |
Format |
|
locked |
Locked by this thread (name) |
string |
|
waiting |
Threads (name) waiting for this object |
string list |
Pipe attributes
|
Attribute name |
Description |
Format |
|
buffer |
|
integer |
|
size |
|
integer |
|
bytes_used |
|
integer |
|
read_index |
|
integer |
|
write_index |
|
integer |
|
flags |
|
integer |
|
locked |
Locked by this thread (name) |
string |
|
waiting_tx |
Threads (name) waiting for this object on write |
string list |
|
waiting_rx |
Threads (name) waiting for this object on read |
string list |
MBox attributes
|
Attribute name |
Description |
Format |
|
locked |
Locked by this thread (name) |
string |
|
waiting_tx |
Threads (name) waiting for this object on write |
string list |
|
waiting_rx |
Threads (name) waiting for this object on read |
string list |
|
Attribute name |
Description |
Format |
|
timeout |
|
integer |
|
period |
|
integer |
MsgQ
|
Attribute name |
Description |
Format |
attributes
|
Attribute name |
Description |
Format |
|
msg_size |
|
integer |
|
max_msgs |
|
integer |
|
buffer_start |
|
integer |
|
buffer_end |
|
integer |
|
read_ptr |
|
integer |
|
write_ptr |
|
integer |
|
used_msgs |
|
integer |
|
flags |
|
integer |
|
locked |
Locked by this thread (name) |
string |
|
waiting |
Threads (name) waiting for this object |
string list |
Stack attributes
|
Attribute name |
Description |
Format |
|
base |
|
integer |
|
next |
|
integer |
|
top |
|
integer |
|
flags |
|
integer |
|
locked |
Locked by this thread (name) |
string |
|
waiting |
Threads (name) waiting for this object on write |
string list |
Timer attributes
|
status |
|
integer |
|
waiting |
Threads (name) waiting for this object on write |
string list |
Mutex attributes
|
owner |
Own by this thread (name) |
string |
|
lock_count |
|
integer |
|
owner_orig_prio |
|
integer |
|
waiting |
Threads (name) waiting for this object on write |
string list |
Semaphore attributes
|
Attribute name |
Description |
Format |
|
limit |
|
integer |
|
count |
|
integer |
|
waiting |
Threads (name) waiting for this object on write |
string list |
DS (Design Studio)
The DS version 3.5.3 or higher offers the possibility to display the Thread information only into a dedicated view.
The extended support is still available in DS by running the extended GDB commands directly from the Debugger Console window.
Figure 3 DS - Execute thread awareness GDB commands
Thread view
This window can be accessed from the menu RTOS/Zephyr RTOS/Threads.
Figure 4 DS IDE - Thread view
Some information can be missing from the view depending on the build configuration used. For example, in the above figure, the Peak stack usage is not available because the CONFIG_INIT_STACKS is not set.
Note the Thread’s field names into DS IDE Thread view can be different than GDB Thread attributes.
Stack
The thread view holds more information about the stack.
The Stack usage stands for the current stack usage, and it is based on SP (Stack Pointer) register while the Peak stack usage stands for the maximum usage of the stack.
Known limitations
- Performance may be affected by number of OS resources
- Limited configurations tested
