debug: debug_stream_slot: Debug slot transportation for debug_stream

Implementation for debug stream transportation over debug window
slot. The protocol details are documented in debug_stream_slot.h
header.

Signed-off-by: Jyri Sarha <jyri.sarha@linux.intel.com>

src/Kconfig

@@ -23,3 +23,5 @@ rsource "math/Kconfig"
 rsource "library_manager/Kconfig"
 
 rsource "debug/telemetry/Kconfig"
+
+rsource "debug/debug_stream/Kconfig"

src/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)

src/debug/debug_stream/Kconfig

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+config SOF_DEBUG_STREAM_SLOT
+ bool "Enable SOF debug stream debug window slot"
+ help
+ Debug stream is an abstract stream of records of debug
+ information from SOF system that are streamed from SOF DSP
+ to the host side for decoding and presentation. This option
+ enables transferring the records from DSP to host over a
+ debug window slot.
+
+if SOF_DEBUG_STREAM_SLOT
+
+config SOF_DEBUG_STREAM_SLOT_NUMBER
+ int "Debug window slot where to put debug stream slot"
+ default 3
+ range 0 14
+ help
+ Which debug slot to reserve for Debug Stream. Remember to map
+ the slot with MEMORY_WIN_2_SIZE in soc/intel/intel_adsp/Kconfig,
+ in Zephyr source tree. The slots are 4k in size and one slot is
+ used for descriptors, so for slot 3 to be mapped, the WIN_2_SIZE
+ must be (1 + 3) * 4k = 16k or greater.
+
+endif
+

src/debug/debug_stream/debug_stream_slot.c

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// Copyright(c) 2024 Intel Corporation.
+
+#include <zephyr/logging/log.h>
+#include <zephyr/spinlock.h>
+#include <adsp_debug_window.h>
+#include <adsp_memory.h>
+#include <sof/common.h>
+#include <rtos/string.h>
+#include <user/debug_stream.h>
+#include <user/debug_stream_slot.h>
+
+LOG_MODULE_REGISTER(debug_strem_slot);
+
+struct cpu_mutex {
+ struct k_mutex m;
+} __aligned(CONFIG_DCACHE_LINE_SIZE);
+
+/* CPU specific mutexes for each circular buffer */
+static struct cpu_mutex cpu_mutex[CONFIG_MP_MAX_NUM_CPUS];
+
+static const int debug_stream_slot = CONFIG_SOF_DEBUG_STREAM_SLOT_NUMBER;
+
+static struct debug_stream_slot_hdr *debug_stream_get_slot(void)
+{
+ return (struct debug_stream_slot_hdr *)ADSP_DW->slots[debug_stream_slot];
+}
+
+static
+struct debug_stream_circular_buf *
+debug_stream_get_circular_buffer(struct debug_stream_section_descriptor *desc, unsigned int core)
+{
+ struct debug_stream_slot_hdr *hdr = debug_stream_get_slot();
+ void *ptr;
+
+ if (hdr->hdr.magic != DEBUG_STREAM_IDENTIFIER) {
+ LOG_ERR("Debug stream slot not initialized.");
+ return NULL;
+ }
+
+ *desc = hdr->section_desc[core];
+ LOG_DBG("Section %u (desc %u %u %u)", core, desc->core_id, desc->buf_words, desc->offset);
+
+ return (struct debug_stream_circular_buf *) (((uint8_t *)hdr) + desc->offset);
+}
+
+int debug_stream_slot_send_record(struct debug_stream_record *rec)
+{
+ struct debug_stream_section_descriptor desc;
+ struct debug_stream_circular_buf *buf =
+ debug_stream_get_circular_buffer(&desc, arch_proc_id());
+ uint32_t record_size = rec->size_words;
+ uint32_t record_start, buf_remain;
+
+ LOG_DBG("Sending record %u id %u len %u\n", rec->seqno, rec->id, rec->size_words);
+
+ if (!buf)
+ return -ENODEV;
+
+ if (rec->size_words >= desc.buf_words) {
+ LOG_ERR("Record too big %u >= %u (desc %u %u %u)", rec->size_words,
+ desc.buf_words, desc.core_id, desc.buf_words, desc.offset);
+ return -ENOMEM;
+ }
+ k_mutex_lock(&cpu_mutex[arch_proc_id()].m, K_FOREVER);
+
+ rec->seqno = buf->next_seqno++;
+ rec->size_words = record_size + 1; /* +1 for size at the end of record */
+ record_start = buf->w_ptr;
+ buf->w_ptr = (record_start + record_size) % desc.buf_words;
+ buf_remain = desc.buf_words - record_start;
+ if (buf_remain < record_size) {
+ uint32_t rec_remain = record_size - buf_remain;
+ int ret;
+
+ ret = memcpy_s(&buf->data[record_start], buf_remain * sizeof(uint32_t),
+ rec, buf_remain * sizeof(uint32_t));
+ assert(!ret);
+ ret = memcpy_s(&buf->data[0], desc.buf_words * sizeof(uint32_t),
+ ((uint32_t *) rec) + buf_remain, rec_remain * sizeof(uint32_t));
+ assert(!ret);
+ } else {
+ int ret;
+
+ ret = memcpy_s(&buf->data[record_start], buf_remain * sizeof(uint32_t),
+ rec, record_size * sizeof(uint32_t));
+ assert(!ret);
+ }
+ /* Write record size again after the record */
+ buf->data[buf->w_ptr] = record_size + 1;
+ buf->w_ptr = (buf->w_ptr + 1) % desc.buf_words;
+
+ k_mutex_unlock(&cpu_mutex[arch_proc_id()].m);
+
+ LOG_DBG("Record %u id %u len %u sent\n", rec->seqno, rec->id, record_size);
+ return 0;
+}
+
+static int debug_stream_slot_init(void)
+{
+ struct debug_stream_slot_hdr *hdr = debug_stream_get_slot();
+ size_t hdr_size = offsetof(struct debug_stream_slot_hdr,
+ section_desc[CONFIG_MP_MAX_NUM_CPUS]);
+ size_t section_area_size = ADSP_DW_SLOT_SIZE - hdr_size;
+ size_t section_size = ALIGN_DOWN(section_area_size /
+ CONFIG_MP_MAX_NUM_CPUS,
+ CONFIG_DCACHE_LINE_SIZE);
+ size_t offset = hdr_size;
+ int i;
+
+ LOG_INF("%u sections of %u bytes, hdr %u, secton area %u\n",
+ CONFIG_MP_MAX_NUM_CPUS, section_size, hdr_size,
+ section_area_size);
+
+ if (ADSP_DW->descs[debug_stream_slot].type != 0)
+ LOG_WRN("Slot %d was not free: %u", debug_stream_slot,
+ ADSP_DW->descs[debug_stream_slot].type);
+ ADSP_DW->descs[debug_stream_slot].type = ADSP_DW_SLOT_DEBUG_STREAM;
+
+ hdr->hdr.magic = DEBUG_STREAM_IDENTIFIER;
+ hdr->hdr.hdr_size = hdr_size;
+ hdr->total_size = hdr_size + CONFIG_MP_MAX_NUM_CPUS * section_size;
+ hdr->num_sections = CONFIG_MP_MAX_NUM_CPUS;
+ for (i = 0; i < CONFIG_MP_MAX_NUM_CPUS; i++) {
+ hdr->section_desc[i].core_id = i;
+ hdr->section_desc[i].buf_words =
+ (section_size - offsetof(struct debug_stream_circular_buf, data[0]))/
+ sizeof(uint32_t);
+ hdr->section_desc[i].offset = offset;
+ LOG_INF("sections %u, size %u, offset %u\n",
+ i, section_size, offset);
+ offset += section_size;
+ }
+ for (i = 0; i < CONFIG_MP_MAX_NUM_CPUS; i++) {
+ struct debug_stream_section_descriptor desc;
+ struct debug_stream_circular_buf *buf =
+ debug_stream_get_circular_buffer(&desc, i);
+
+ buf->next_seqno = 0;
+ buf->w_ptr = 0;
+ k_mutex_init(&cpu_mutex[i].m);
+ /* The core specific mutexes are now .dss which is uncached so the
+ * following line is commented out. However, since the mutexes are
+ * core specific there should be nothing preventing from having them
+ * in cached memory.
+ *
+ * sys_cache_data_flush_range(&cpu_mutex[i], sizeof(cpu_mutex[i]));
+ */
+ }
+ LOG_INF("Debug stream slot initialized\n");
+
+ return 0;
+}
+
+SYS_INIT(debug_stream_slot_init, APPLICATION, CONFIG_KERNEL_INIT_PRIORITY_DEFAULT);

src/include/user/debug_stream_slot.h

@@ -0,0 +1,138 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ *
+ * Copyright(c) 2024 Intel Corporation.
+ */
+
+#ifndef __SOC_DEBUG_WINDOW_SLOT_H__
+#define __SOC_DEBUG_WINDOW_SLOT_H__
+
+#include <user/debug_stream.h>
+
+/*
+ * This file describes how Debug Stream can be transported over debug
+ * window memory slot. The debug stream is an abstract media API for
+ * passing debug data records from SOF DSP to the host system for
+ * presentation. The debug stream records are described in debug_stream.h.
+ *
+ * This example describes how Debug Stream data is transferred from
+ * DSP to host side using a debug memory window slot. To learn more
+ * see soc/intel/intel_adsp/common/include/adsp_debug_window.h
+ * under Zephyr source tree.
+ *
+ * DEBUG_STREAM slot is reserved from SRAM window and a header is
+ * written in the beginning of the slot. The header is a static data
+ * structure that is initialized once at DSP boot time. All elements
+ * in bellow example are 32-bit unsigned integers:
+ *
+ * -------------------------------------------------- ---
+ * | id = DEBUG_STREAM_IDENTIFIER | |
+ * | total_size = 4096 | 64 bytes
+ * | num_sections = CONFIG_MP_MAX_NUM_CPUS * | |
+ * | <padding> | |
+ * -------------------------------------------------- ---
+ * | section_descriptor [] = { | |
+ * | { | |
+ * | core_id = 0 | |
+ * | size = 1344 | 64 bytes
+ * | offset = 64 | |
+ * | } | |
+ * | <padding> | |
+ * -------------------------------------------------- ---
+ * | { | |
+ * | core_id = 1 | |
+ * | size = 1344 | 64 bytes
+ * | offset = 1344+64 | |
+ * | } | |
+ * | <padding> | |
+ * -------------------------------------------------- ---
+ * | { | |
+ * | core_id = 2 | |
+ * | size = 1344 | 64 bytes
+ * | offset = 2*1344+64 | |
+ * | } | |
+ * | } | |
+ * | <padding> | |
+ * -------------------------------------------------- ---
+ * * CONFIG_MP_MAX_NUM_CPUS is 3 in this example
+ *
+ * The header contains generic information like identifier, total
+ * size, and number of sections. After the generic fields there is an
+ * array of section descriptors. Each array element is cacheline
+ * aligned. The array has 'num_sections' number of elements. Each
+ * element in the array describes a circular buffer, one for each DSP
+ * core.
+ *
+ * The remaining memory in the debug window slot is divided between
+ * those sections. The buffers are not necessarily of equal size, like
+ * in this example. The circular buffers are all cache line aligned,
+ * 64 in this example. One section looks like this:
+ *
+ * -------------------------------------------------- ---
+ * | next_seqno = <counter for written objects> | |
+ * | w_ptr = <write position in 32-bit words> | 1344 bytes
+ * | buffer_data[1344/4-2] = { | |
+ * | <debug data records> | |
+ * | } | |
+ * -------------------------------------------------- ---
+ *
+ * The data records are described in debug_strem.h. In the case of
+ * debug window memory slot the next record should always be aligned
+ * to word (4-byte) boundary.
+ *
+ * The debug stream writes the records of abstract data to the
+ * circular buffer, and updates the w_ptr when the record is
+ * completely written. The host side receiver tries to keep up with the
+ * w_ptr and keeps track of its read position. The size of the record
+ * is written - again - after each record and before the next. This is
+ * to allow parsing the stream backwards in an overrun recovery
+ * situation. The w_ptr value is updated last, when the record is
+ * completely written.
+ */
+
+#include <stdint.h>
+
+/* Core specific section descriptor
+ *
+ * Section descriptor defines core ID, offset and size of the circular
+ * buffer in the debug window slot.
+ */
+struct debug_stream_section_descriptor {
+ uint32_t core_id; /* Core ID */
+ uint32_t buf_words; /* Circular buffer size in 32-bit words */
+ uint32_t offset; /* Core section offset */
+} __packed;
+
+/* Debug window slot header for Debug Stream.
+ *
+ * The header should be written in the beginning of the slot.
+ */
+struct debug_stream_slot_hdr {
+ struct debug_stream_hdr hdr;
+ uint32_t total_size; /* total size of payload including all sections */
+ uint32_t num_sections; /* number of core specific sections */
+ struct debug_stream_section_descriptor section_desc[];
+} __packed;
+
+struct debug_stream_circular_buf {
+ uint32_t next_seqno;
+ uint32_t w_ptr;
+ uint32_t data[];
+} __aligned(CONFIG_DCACHE_LINE_SIZE);
+
+struct debug_stream_record;
+/**
+ * \brief Send debug stream records over debug window slot
+ *
+ * \param[in] rec the record to be written to circular buffer
+ *
+ * The debug window slot is initialized automatically at DSP boot
+ * time, and the core specific circular buffer is selected
+ * automatically.
+ *
+ * \return 0 on success
+ * -ENODEV if debug stream slot is not configured
+ * -ENOMEM if the record is too big
+ */
+int debug_stream_slot_send_record(struct debug_stream_record *rec);
+
+#endif /* __SOC_DEBUG_WINDOW_SLOT_H__ */

zephyr/CMakeLists.txt

@@ -188,6 +188,7 @@ endmacro()
 add_subdirectory(../src/init/ init_unused_install/)
 add_subdirectory(../src/ipc/ ipc_unused_install/)
 add_subdirectory(../src/debug/telemetry/ telemetry_unused_install/)
+add_subdirectory(../src/debug/debug_stream/ debug_stream_unused_install/)
 add_subdirectory(test/)