From 3520cfcf1d4d4f9d80b5ca7776d0856f14143dfd Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Sun, 15 Nov 2026 13:33:24 +0000 Subject: [PATCH 1/5] debug_stream: include rtos/symbol.h for EXPORT_SYMBOL() debug_stream_text_msg.c exports ds_msg() and assert_print() with EXPORT_SYMBOL(), but does not include rtos/symbol.h. On PTL the header comes in through other includes; on TGL it does not, so a TGL build with app/debug_stream_overlay.conf fails. Include it. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Liam Girdwood --- src/debug/debug_stream/debug_stream_text_msg.c | 1 + 1 file changed, 1 insertion(+) diff --git a/src/debug/debug_stream/debug_stream_text_msg.c b/src/debug/debug_stream/debug_stream_text_msg.c index f4b67d4d307a..2e1efaec7fdf 100644 --- a/src/debug/debug_stream/debug_stream_text_msg.c +++ b/src/debug/debug_stream/debug_stream_text_msg.c @@ -8,6 +8,7 @@ #include #include #include +#include #include #include From 10ae981d3b6633d9b3620593dd561f7b76c7dd5c Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Sun, 15 Nov 2026 13:33:37 +0000 Subject: [PATCH 2/5] debug_stream: move the debug stream slot to src/kernel/debug debug_stream_slot.c is kernel-only: it sets up the debug stream slot in the ADSP debug window at boot, writes the records to it under per-core spinlocks, and holds both halves of the debug_stream_slot_send_record() system call. The debug stream clients only reach it through the system call. Move it to src/kernel/debug/debug_stream, built under the same option, and update the system call table of the user-space README. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Liam Girdwood --- src/debug/debug_stream/CMakeLists.txt | 2 -- src/include/sof/userspace/README.md | 2 +- src/kernel/debug/CMakeLists.txt | 1 + src/kernel/debug/debug_stream/CMakeLists.txt | 3 +++ src/{ => kernel}/debug/debug_stream/debug_stream_slot.c | 0 5 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 src/kernel/debug/debug_stream/CMakeLists.txt rename src/{ => kernel}/debug/debug_stream/debug_stream_slot.c (100%) diff --git a/src/debug/debug_stream/CMakeLists.txt b/src/debug/debug_stream/CMakeLists.txt index 36de0d24a46d..02d11a7cdffb 100644 --- a/src/debug/debug_stream/CMakeLists.txt +++ b/src/debug/debug_stream/CMakeLists.txt @@ -1,7 +1,5 @@ # SPDX-License-Identifier: BSD-3-Clause -add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_SLOT sof debug_stream_slot.c) - add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_THREAD_INFO sof debug_stream_thread_info.c) add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_TEXT_MSG sof debug_stream_text_msg.c) diff --git a/src/include/sof/userspace/README.md b/src/include/sof/userspace/README.md index 8ee63ea87515..a3ce19d38383 100644 --- a/src/include/sof/userspace/README.md +++ b/src/include/sof/userspace/README.md @@ -125,7 +125,7 @@ syscall by subsystem: | Module management | `mod_balloc_align`, `mod_alloc_ext`, `mod_free`, `mod_free_all`, `mod_data_blob_handler_new`, `mod_data_blob_set`, `mod_fast_get` | `sof/audio/module_adapter/module/generic.h` | scattered: `audio/module_adapter/module/generic.c` | | Library manager | `lib_manager_free_module` | `sof/lib_manager.h` | scattered: `kernel/library_manager/lib_manager.c` | | Scheduling | `zephyr_ll_task_sem_alloc`, `zephyr_ll_task_sem_free`, `scheduler_dp_internal_free`, `scheduler_dp_ll_tick` | `sof/schedule/ll_schedule_domain.h`, `sof/schedule/dp_schedule.h` | scattered: `kernel/schedule/zephyr_ll-kernel.c`, `kernel/schedule/zephyr_dp_schedule*-kernel.c` | -| Debug | `debug_stream_slot_send_record` | `user/debug_stream_slot.h` | scattered: `debug/debug_stream/debug_stream_slot.c` | +| Debug | `debug_stream_slot_send_record` | `user/debug_stream_slot.h` | `kernel/debug/debug_stream/debug_stream_slot.c` | | KPB | `kpb_notifier_init` | `sof/audio/kpb.h` | scattered: `audio/kpb.c` | ### Allowed callers diff --git a/src/kernel/debug/CMakeLists.txt b/src/kernel/debug/CMakeLists.txt index e364c4233063..9c467cf5de10 100644 --- a/src/kernel/debug/CMakeLists.txt +++ b/src/kernel/debug/CMakeLists.txt @@ -3,6 +3,7 @@ is_zephyr(zephyr) if(zephyr) ### Zephyr ### +add_subdirectory(debug_stream) add_subdirectory(telemetry) zephyr_library_sources_ifdef(CONFIG_COLD_STORE_EXECUTE_DEBUG dram.c) diff --git a/src/kernel/debug/debug_stream/CMakeLists.txt b/src/kernel/debug/debug_stream/CMakeLists.txt new file mode 100644 index 000000000000..3c8e6c00d5c3 --- /dev/null +++ b/src/kernel/debug/debug_stream/CMakeLists.txt @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: BSD-3-Clause + +add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_SLOT sof debug_stream_slot.c) diff --git a/src/debug/debug_stream/debug_stream_slot.c b/src/kernel/debug/debug_stream/debug_stream_slot.c similarity index 100% rename from src/debug/debug_stream/debug_stream_slot.c rename to src/kernel/debug/debug_stream/debug_stream_slot.c From 6ca2dad03dfb21d2e3fd1a3de1975db69b616abf Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Sun, 15 Nov 2026 13:33:51 +0000 Subject: [PATCH 3/5] debug_stream: move the thread info client to src/kernel/debug debug_stream_thread_info.c is kernel-only: it starts a kernel thread per core at boot, which walks the Zephyr threads of its core and reports their CPU use and stack use through the debug stream. Move it to src/kernel/debug/debug_stream, built under the same option. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Liam Girdwood --- src/debug/debug_stream/CMakeLists.txt | 2 -- src/kernel/debug/debug_stream/CMakeLists.txt | 2 ++ src/{ => kernel}/debug/debug_stream/debug_stream_thread_info.c | 0 3 files changed, 2 insertions(+), 2 deletions(-) rename src/{ => kernel}/debug/debug_stream/debug_stream_thread_info.c (100%) diff --git a/src/debug/debug_stream/CMakeLists.txt b/src/debug/debug_stream/CMakeLists.txt index 02d11a7cdffb..b150aa4f1a11 100644 --- a/src/debug/debug_stream/CMakeLists.txt +++ b/src/debug/debug_stream/CMakeLists.txt @@ -1,5 +1,3 @@ # SPDX-License-Identifier: BSD-3-Clause -add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_THREAD_INFO sof debug_stream_thread_info.c) - add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_TEXT_MSG sof debug_stream_text_msg.c) diff --git a/src/kernel/debug/debug_stream/CMakeLists.txt b/src/kernel/debug/debug_stream/CMakeLists.txt index 3c8e6c00d5c3..4d353128a819 100644 --- a/src/kernel/debug/debug_stream/CMakeLists.txt +++ b/src/kernel/debug/debug_stream/CMakeLists.txt @@ -1,3 +1,5 @@ # SPDX-License-Identifier: BSD-3-Clause add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_SLOT sof debug_stream_slot.c) + +add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_THREAD_INFO sof debug_stream_thread_info.c) diff --git a/src/debug/debug_stream/debug_stream_thread_info.c b/src/kernel/debug/debug_stream/debug_stream_thread_info.c similarity index 100% rename from src/debug/debug_stream/debug_stream_thread_info.c rename to src/kernel/debug/debug_stream/debug_stream_thread_info.c From 9b97a8c28265d18e7f64f6a6d54754c27969dd72 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Sun, 15 Nov 2026 13:34:30 +0000 Subject: [PATCH 4/5] debug_stream: split the kernel part of debug_stream_text_msg.c into src/kernel/debug debug_stream_text_msg.c mixes ds_msg() and ds_vamsg(), which format a text record and send it through the debug_stream_slot_send_record() system call, so they can be called in user mode, with the exception dump hook, which runs in the fatal error handler. Move the kernel part to src/kernel/debug/debug_stream/debug_stream_text_msg-kernel.c: - the per-core exception dump state, the dump and drain hooks and their registration with arch_exception_set_dump_hook() at boot; - assert_print(), which shares the per-core exception dump state. debug_stream_text_msg.c keeps ds_msg() and ds_vamsg() and the log module. The kernel part is built with the same option. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Liam Girdwood --- .../debug_stream/debug_stream_text_msg.c | 143 +--------------- src/kernel/debug/debug_stream/CMakeLists.txt | 3 + .../debug_stream_text_msg-kernel.c | 160 ++++++++++++++++++ 3 files changed, 167 insertions(+), 139 deletions(-) create mode 100644 src/kernel/debug/debug_stream/debug_stream_text_msg-kernel.c diff --git a/src/debug/debug_stream/debug_stream_text_msg.c b/src/debug/debug_stream/debug_stream_text_msg.c index 2e1efaec7fdf..b65c23deebe8 100644 --- a/src/debug/debug_stream/debug_stream_text_msg.c +++ b/src/debug/debug_stream/debug_stream_text_msg.c @@ -10,12 +10,15 @@ #include #include #include -#include #include LOG_MODULE_REGISTER(debug_stream_text_msg); +/* The exception dump hook and assert_print(), which run in kernel mode, are in + * src/kernel/debug/debug_stream/debug_stream_text_msg-kernel.c + */ + void ds_vamsg(const char *format, va_list args) { struct { @@ -45,141 +48,3 @@ void ds_msg(const char *format, ...) va_end(args); } EXPORT_SYMBOL(ds_msg); - -#if defined(CONFIG_EXCEPTION_DUMP_HOOK) -/* The debug stream debug window slot is 4k, and when it is split - * between the cores and the header/other overhead is removed, with 5 - * cores the size is 768 bytes. The dump record must be smaller than - * that to get through to the host side. - * - * Also, because of the limited circular buffer size, we should only - * send one exception record. On some situations the exceptions happen - * in bursts, and sending more than one record in short time makes the - * host-side decoder lose track of things. - */ - -/* Per-CPU state for exception dump and assert_print(). Static data is - * currently placed in .bss and its ATM uncached so the ds_cpu table - * elements do not need to be cache aligned, but if this changes we - * need __aligned(CONFIG_DCACHE_LINE_SIZE) here. - */ -static struct ds_cpu_state { - struct { - struct debug_stream_text_msg msg; - char text[640]; - } __packed buf; - int reports_sent; - size_t pos; -} ds_cpu[CONFIG_SOF_DEBUG_STREAM_SLOT_FORCE_MAX_CPUS]; - -static void ds_exception_drain(bool flush) -{ - unsigned int cpu = arch_proc_id(); - struct ds_cpu_state *cs = &ds_cpu[cpu]; - - if (flush) { - cs->pos = 0; - return; - } - - if (cs->pos == 0) - return; - - if (cs->reports_sent > 0) - return; - - cs->buf.msg.hdr.id = DEBUG_STREAM_RECORD_ID_TEXT_MSG; - cs->buf.msg.hdr.size_words = - SOF_DIV_ROUND_UP(sizeof(cs->buf.msg) + cs->pos, - sizeof(cs->buf.msg.hdr.data[0])); - - /* Make sure the possible up to 3 extra bytes at end of msg are '\0' */ - memset(cs->buf.text + cs->pos, 0, - cs->buf.msg.hdr.size_words * sizeof(cs->buf.msg.hdr.data[0]) - cs->pos); - debug_stream_slot_send_record(&cs->buf.msg.hdr); - cs->reports_sent = 1; - cs->pos = 0; -} - -static void ds_exception_dump(const char *format, va_list args) -{ - ssize_t len; - size_t avail; - size_t written; - unsigned int cpu = arch_proc_id(); - struct ds_cpu_state *cs = &ds_cpu[cpu]; - - if (cs->reports_sent > 0) - return; - - avail = sizeof(cs->buf.text) - cs->pos; - if (avail == 0) { - ds_exception_drain(false); - return; - } - - if (format[0] == '\0') - return; - - /* Skip useless " ** " prefix to save bytes */ - if (strlen(format) >= 4 && - format[0] == ' ' && format[1] == '*' && format[2] == '*' && format[3] == ' ') - format += 4; - - len = vsnprintf(cs->buf.text + cs->pos, avail, format, args); - if (len < 0) { - cs->pos = 0; - return; - } - - if (len == 0) - return; - - if ((size_t)len >= avail) - written = avail - 1; - else - written = (size_t)len; - - cs->pos += written; - - if (cs->pos >= sizeof(cs->buf.text)) - ds_exception_drain(false); -} - -static int init_exception_dump_hook(void) -{ - arch_exception_set_dump_hook(ds_exception_dump, ds_exception_drain); - LOG_DBG("exception_dump_hook set"); - return 0; -} - -SYS_INIT(init_exception_dump_hook, APPLICATION, CONFIG_KERNEL_INIT_PRIORITY_DEFAULT); - -#if defined(CONFIG_SOF_DEBUG_STREAM_TEXT_MSG_ASSERT_PRINT) -void assert_print(const char *fmt, ...) -{ - va_list ap; - - /* Do not print assert after exception has been dumped */ - if (ds_cpu[arch_proc_id()].reports_sent > 0) - return; - - va_start(ap, fmt); -#if !defined(CONFIG_EXCEPTION_DUMP_HOOK_ONLY) - { - va_list ap2; - - va_copy(ap2, ap); -#endif - ds_vamsg(fmt, ap); -#if !defined(CONFIG_EXCEPTION_DUMP_HOOK_ONLY) - vprintk(fmt, ap2); - va_end(ap2); - } -#endif - ds_vamsg(fmt, ap); - va_end(ap); -} -EXPORT_SYMBOL(assert_print); -#endif -#endif diff --git a/src/kernel/debug/debug_stream/CMakeLists.txt b/src/kernel/debug/debug_stream/CMakeLists.txt index 4d353128a819..2ee1c81ea0fe 100644 --- a/src/kernel/debug/debug_stream/CMakeLists.txt +++ b/src/kernel/debug/debug_stream/CMakeLists.txt @@ -3,3 +3,6 @@ add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_SLOT sof debug_stream_slot.c) add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_THREAD_INFO sof debug_stream_thread_info.c) + +# The kernel part of src/debug/debug_stream/debug_stream_text_msg.c, built with it +add_local_sources_ifdef(CONFIG_SOF_DEBUG_STREAM_TEXT_MSG sof debug_stream_text_msg-kernel.c) diff --git a/src/kernel/debug/debug_stream/debug_stream_text_msg-kernel.c b/src/kernel/debug/debug_stream/debug_stream_text_msg-kernel.c new file mode 100644 index 000000000000..e8425f37df6f --- /dev/null +++ b/src/kernel/debug/debug_stream/debug_stream_text_msg-kernel.c @@ -0,0 +1,160 @@ +// SPDX-License-Identifier: BSD-3-Clause +// +// Copyright(c) 2024 Intel Corporation. + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include + +LOG_MODULE_DECLARE(debug_stream_text_msg); + +/* Kernel part of the debug stream text messages: the exception dump hook, which + * runs in the fatal error handler, and assert_print(), which shares its per-CPU + * state. ds_msg() and ds_vamsg() are in src/debug/debug_stream/debug_stream_text_msg.c + */ + +#if defined(CONFIG_EXCEPTION_DUMP_HOOK) +/* The debug stream debug window slot is 4k, and when it is split + * between the cores and the header/other overhead is removed, with 5 + * cores the size is 768 bytes. The dump record must be smaller than + * that to get through to the host side. + * + * Also, because of the limited circular buffer size, we should only + * send one exception record. On some situations the exceptions happen + * in bursts, and sending more than one record in short time makes the + * host-side decoder lose track of things. + */ + +/* Per-CPU state for exception dump and assert_print(). Static data is + * currently placed in .bss and its ATM uncached so the ds_cpu table + * elements do not need to be cache aligned, but if this changes we + * need __aligned(CONFIG_DCACHE_LINE_SIZE) here. + */ +static struct ds_cpu_state { + struct { + struct debug_stream_text_msg msg; + char text[640]; + } __packed buf; + int reports_sent; + size_t pos; +} ds_cpu[CONFIG_SOF_DEBUG_STREAM_SLOT_FORCE_MAX_CPUS]; + +static void ds_exception_drain(bool flush) +{ + unsigned int cpu = arch_proc_id(); + struct ds_cpu_state *cs = &ds_cpu[cpu]; + + if (flush) { + cs->pos = 0; + return; + } + + if (cs->pos == 0) + return; + + if (cs->reports_sent > 0) + return; + + cs->buf.msg.hdr.id = DEBUG_STREAM_RECORD_ID_TEXT_MSG; + cs->buf.msg.hdr.size_words = + SOF_DIV_ROUND_UP(sizeof(cs->buf.msg) + cs->pos, + sizeof(cs->buf.msg.hdr.data[0])); + + /* Make sure the possible up to 3 extra bytes at end of msg are '\0' */ + memset(cs->buf.text + cs->pos, 0, + cs->buf.msg.hdr.size_words * sizeof(cs->buf.msg.hdr.data[0]) - cs->pos); + debug_stream_slot_send_record(&cs->buf.msg.hdr); + cs->reports_sent = 1; + cs->pos = 0; +} + +static void ds_exception_dump(const char *format, va_list args) +{ + ssize_t len; + size_t avail; + size_t written; + unsigned int cpu = arch_proc_id(); + struct ds_cpu_state *cs = &ds_cpu[cpu]; + + if (cs->reports_sent > 0) + return; + + avail = sizeof(cs->buf.text) - cs->pos; + if (avail == 0) { + ds_exception_drain(false); + return; + } + + if (format[0] == '\0') + return; + + /* Skip useless " ** " prefix to save bytes */ + if (strlen(format) >= 4 && + format[0] == ' ' && format[1] == '*' && format[2] == '*' && format[3] == ' ') + format += 4; + + len = vsnprintf(cs->buf.text + cs->pos, avail, format, args); + if (len < 0) { + cs->pos = 0; + return; + } + + if (len == 0) + return; + + if ((size_t)len >= avail) + written = avail - 1; + else + written = (size_t)len; + + cs->pos += written; + + if (cs->pos >= sizeof(cs->buf.text)) + ds_exception_drain(false); +} + +static int init_exception_dump_hook(void) +{ + arch_exception_set_dump_hook(ds_exception_dump, ds_exception_drain); + LOG_DBG("exception_dump_hook set"); + return 0; +} + +SYS_INIT(init_exception_dump_hook, APPLICATION, CONFIG_KERNEL_INIT_PRIORITY_DEFAULT); + +#if defined(CONFIG_SOF_DEBUG_STREAM_TEXT_MSG_ASSERT_PRINT) +void assert_print(const char *fmt, ...) +{ + va_list ap; + + /* Do not print assert after exception has been dumped */ + if (ds_cpu[arch_proc_id()].reports_sent > 0) + return; + + va_start(ap, fmt); +#if !defined(CONFIG_EXCEPTION_DUMP_HOOK_ONLY) + { + va_list ap2; + + va_copy(ap2, ap); +#endif + ds_vamsg(fmt, ap); +#if !defined(CONFIG_EXCEPTION_DUMP_HOOK_ONLY) + vprintk(fmt, ap2); + va_end(ap2); + } +#endif + ds_vamsg(fmt, ap); + va_end(ap); +} +EXPORT_SYMBOL(assert_print); +#endif +#endif From 02fc4d7741689b84e105de1773bf8b52b3d94629 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Sun, 15 Nov 2026 13:34:52 +0000 Subject: [PATCH 5/5] docs: debug_stream: describe the kernel and user parts Add a "Runs in:" banner to the debug stream README: the text message clients can run in user threads and use the slot system call, and the slot, the thread info client and the exception dump hook are in src/kernel/debug/debug_stream. debug_stream was the last directory without a banner, so drop the note about such directories from the user-space README. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Liam Girdwood --- src/debug/debug_stream/README.md | 8 ++++++++ src/include/sof/userspace/README.md | 4 +--- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/src/debug/debug_stream/README.md b/src/debug/debug_stream/README.md index 592edef8a719..5d8f1ce8951e 100644 --- a/src/debug/debug_stream/README.md +++ b/src/debug/debug_stream/README.md @@ -1,5 +1,13 @@ # SOF Debug Stream +> **Runs in:** Boundary / bridge — the debug stream clients here (`ds_msg()` and `ds_vamsg()` +> in `debug_stream_text_msg.c`) can run in user threads and send their records through the +> `debug_stream_slot_send_record()` syscall. The kernel parts are in +> `src/kernel/debug/debug_stream`: the debug window slot with both halves of the syscall +> (`debug_stream_slot.c`), the thread info client (`debug_stream_thread_info.c`) and the +> exception dump hook with `assert_print()` (`debug_stream_text_msg-kernel.c`). See +> [User/kernel split](../../include/sof/userspace/README.md). + The `debug_stream` framework is an abstract logging and live-data streaming mechanism allowing the DSP to asynchronously push structured or freeform diagnostic records immediately out to the host. ## Feature Overview diff --git a/src/include/sof/userspace/README.md b/src/include/sof/userspace/README.md index a3ce19d38383..f73bc1b53e12 100644 --- a/src/include/sof/userspace/README.md +++ b/src/include/sof/userspace/README.md @@ -75,13 +75,11 @@ its subdirectories span all tiers. | Tier | Meaning | Directories | |------|---------|-------------| | **Kernel-only** | OS integration, HAL, boot, inter-core. Never executes in a user thread. Must not be reached directly from user code — only via a syscall. | `kernel/` (see [its README](../../../kernel/README.md)) | -| **Boundary / bridge** | Owns the syscalls and the thread / memory-domain setup. Split internally: some translation units run kernel-side, some user-side (e.g. `handler-kernel.c` vs `handler-user.c`). | `schedule/`, `ipc/`, `debug/debug_stream/` *, and (in the Zephyr integration tree) `zephyr/syscall/` | +| **Boundary / bridge** | Owns the syscalls and the thread / memory-domain setup. Split internally: some translation units run kernel-side, some user-side (e.g. `handler-kernel.c` vs `handler-user.c`). | `schedule/`, `ipc/`, `debug/debug_stream/`, and (in the Zephyr integration tree) `zephyr/syscall/` | | **Application** | Audio pipeline / component logic that runs in user threads under userspace configs. | `audio/` | | **Shared library** | Context-agnostic code linked into whichever context calls it. Must stay "user-safe": no privileged operations (no direct MMIO, no spinlocks held across syscalls, no raw kernel object access) so it is safe when pulled into a user build. | `math/`, `module/` | | **Mixed** | A directory whose files span more than one tier; see its own README for per-file classification. | `lib/` | -Directories marked * do not yet have a "Runs in:" README banner. - Kernel-only code lives under `src/kernel/`, which Zephyr builds into a library of its own, `sof_kernel`, instead of `modules_sof`. Source files that mix kernel and user code are split, and their kernel halves moved there, separately.