From 111b07e774fa0b0cf21f180e6e1e326c8d220593 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Wed, 14 Oct 2026 18:27:36 +0100 Subject: [PATCH] doc: telemetry: document telemetry, logging, probes, and debug streams Add comprehensive Doxygen documentation across all SOF telemetry, logging, probe, and debug stream subsystems, organizing them into four dedicated subgroups under probe_api: 1. trace_logging_api: DMA trace buffer management, circular host streaming, dictionary-based logger (.ldc), runtime log level filtering, and panic crash dumps. 2. audio_probe_api: Audio probe injection and extraction tap points, probe DMA frame format encoding (0xBABEBEBA), and IPC commands. 3. telemetry_perf_api: Hardware telemetry metrics, CPU cycle accounting, Memory Window 3 component performance tracking, and SRAM Window 0 firmware status registers. 4. debug_stream_api: Abstract debug stream packet protocol (0x1ED15EED), Memory Window 2 debug slots, early mailbox debug dumping macros, and GDB target debug stub. Signed-off-by: Liam Girdwood --- doc/groups.dox | 24 +++ doc/sof.doxygen.in | 3 + src/include/ipc/probe_dma_frame.h | 102 +++++-------- src/include/ipc/trace.h | 105 +++++++------ src/include/ipc3/probe.h | 74 +++++----- src/include/kernel/mailbox.h | 77 +++++----- src/include/sof/debug/debug.h | 24 ++- src/include/sof/debug/gdb/gdb.h | 25 ++++ .../sof/debug/telemetry/performance_monitor.h | 77 +++++----- src/include/sof/debug/telemetry/telemetry.h | 113 ++++++-------- src/include/sof/probe/probe.h | 113 +++++++------- src/include/sof/trace/dma-trace.h | 139 +++++++++++++++--- src/include/sof/trace/trace-boot.h | 102 +++++++------ src/include/sof/trace/trace-soflogger.h | 127 ++++++++++++++-- src/include/user/debug_stream.h | 64 ++++---- src/include/user/debug_stream_slot.h | 63 ++++---- src/include/user/debug_stream_text_msg.h | 38 ++++- src/include/user/trace.h | 58 +++++--- 18 files changed, 813 insertions(+), 515 deletions(-) diff --git a/doc/groups.dox b/doc/groups.dox index 509bfba5bafc..8871e068af3f 100644 --- a/doc/groups.dox +++ b/doc/groups.dox @@ -118,6 +118,30 @@ * @brief Real-time DSP trace logging, probe extraction/injection buffers, DMA telemetry, and panic dumps. */ +/** + * @defgroup trace_logging_api Trace DMA & Dictionary Logging + * @ingroup probe_api + * @brief Circular host DMA trace buffers, dictionary-based logger (.ldc), runtime log level filtering, and panic crash dumps. + */ + +/** + * @defgroup audio_probe_api Audio Probes & Stream Tap Points + * @ingroup probe_api + * @brief Dynamic pipeline buffer extraction and injection probes, probe DMA frames, and synchronization sync words. + */ + +/** + * @defgroup telemetry_perf_api Hardware Telemetry & Performance Monitoring + * @ingroup probe_api + * @brief Core system ticks, CPU cycle utilization, component performance tracking, and SRAM Window 0/3 telemetry status registers. + */ + +/** + * @defgroup debug_stream_api Debug Streams & Low-Level Debugging + * @ingroup probe_api + * @brief Structured debug stream records, Memory Window 2 debug slots, mailbox debug dumps, and GDB target stub. + */ + /** * @defgroup platform_drivers_api Platform & Hardware Drivers * @brief Digital Audio Interfaces (DAI), Direct Memory Access (DMA), and Power Management (PM) runtime. diff --git a/doc/sof.doxygen.in b/doc/sof.doxygen.in index bf9a507f2199..7aa4dc0dcc5e 100644 --- a/doc/sof.doxygen.in +++ b/doc/sof.doxygen.in @@ -60,6 +60,9 @@ PREDEFINED = "__attribute__(x)= " \ "CONFIG_SOF_USERSPACE_INTERFACE_ALLOC=1" \ "CONFIG_SOF_FULL_ZEPHYR_APPLICATION=1" \ "CONFIG_SOF_USERSPACE_USE_SHARED_HEAP=1" \ + "CONFIG_SOF_TELEMETRY_PERFORMANCE_MEASUREMENTS=1" \ + "CONFIG_INTEL_ADSP_DEBUG_SLOT_MANAGER=1" \ + "CONFIG_GDB_DEBUG=1" \ "__DOXYGEN__=1" \ "__coherent=" \ "__syscall=" \ diff --git a/src/include/ipc/probe_dma_frame.h b/src/include/ipc/probe_dma_frame.h index 0628704fdcef..4a9d562d59ab 100644 --- a/src/include/ipc/probe_dma_frame.h +++ b/src/include/ipc/probe_dma_frame.h @@ -3,81 +3,59 @@ * Copyright(c) 2022 Intel Corporation. All rights reserved. */ +/** + * \file include/ipc/probe_dma_frame.h + * \brief Audio probe extraction stream packet frame headers and format bitfield encoding. + * \ingroup audio_probe_api + */ + #ifndef __IPC_PROBE_DMA_FRAME_H__ #define __IPC_PROBE_DMA_FRAME_H__ #include /** - * Header for data packets sent via compressed PCM from extraction probes + * \brief Header for data packets sent via compressed PCM from extraction probes. + * \ingroup audio_probe_api */ struct probe_data_packet { - uint32_t sync_word; /**< PROBE_EXTRACT_SYNC_WORD */ + uint32_t sync_word; /**< Magic synchronization marker (PROBE_EXTRACT_SYNC_WORD) */ uint32_t buffer_id; /**< Buffer ID from which data was extracted */ - uint32_t format; /**< Encoded data format */ - uint32_t timestamp_low; /**< Low 32 bits of timestamp in us */ - uint32_t timestamp_high; /**< High 32 bits of timestamp in us */ - uint32_t data_size_bytes; /**< Size of following audio data */ - uint8_t data[]; /**< Audio data extracted from buffer */ + uint32_t format; /**< Encoded 32-bit audio data format */ + uint32_t timestamp_low; /**< Low 32 bits of hardware timestamp in microseconds */ + uint32_t timestamp_high; /**< High 32 bits of hardware timestamp in microseconds */ + uint32_t data_size_bytes; /**< Byte length of extracted payload in data[] */ + uint8_t data[]; /**< Extracted audio samples */ } __attribute__((packed, aligned(4))); +/** Extraction packet sync marker (0xBABEBEBA) */ #define PROBE_EXTRACT_SYNC_WORD 0xBABEBEBA -/** - * \brief Definitions of shifts and masks for format encoding in probe - * extraction stream - * - * Audio format from extraction probes is encoded as 32 bit value. Following - * graphic explains encoding. - * - * A|BBBB|CCCC|DDDD|EEEEE|FF|GG|H|I|J|XXXXXXX - * A - 1 bit - Specifies Type Encoding - 1 for Standard encoding - * B - 4 bits - Specify Standard Type - 0 for Audio - * C - 4 bits - Specify Audio format - 0 for PCM - * D - 4 bits - Specify Sample Rate - value enumerating standard sample rates: - * 8000 Hz = 0x0 - * 11025 Hz = 0x1 - * 12000 Hz = 0x2 - * 16000 Hz = 0x3 - * 22050 Hz = 0x4 - * 24000 Hz = 0x5 - * 32000 Hz = 0x6 - * 44100 Hz = 0x7 - * 48000 Hz = 0x8 - * 64000 Hz = 0x9 - * 88200 Hz = 0xA - * 96000 Hz = 0xB - * 128000 Hz = 0xC - * 176400 Hz = 0xD - * 192000 Hz = 0xE - * none of the above = 0xF - * E - 5 bits - Specify Number of Channels minus 1 - * F - 2 bits - Specify Sample Size, number of valid sample bytes minus 1 - * G - 2 bits - Specify Container Size, number of container bytes minus 1 - * H - 1 bit - Specifies Sample Format - 0 for Integer, 1 for Floating point - * I - 1 bit - Specifies Sample Endianness - 0 for LE - * J - 1 bit - Specifies Interleaving - 1 for Sample Interleaving +/** \name Probe Extraction Audio Format Bitfield Shifts & Masks + * Bitfield encoding for probe extraction stream audio formats. + * @{ */ -#define PROBE_SHIFT_FMT_TYPE 31 -#define PROBE_SHIFT_STANDARD_TYPE 27 -#define PROBE_SHIFT_AUDIO_FMT 23 -#define PROBE_SHIFT_SAMPLE_RATE 19 -#define PROBE_SHIFT_NB_CHANNELS 14 -#define PROBE_SHIFT_SAMPLE_SIZE 12 -#define PROBE_SHIFT_CONTAINER_SIZE 10 -#define PROBE_SHIFT_SAMPLE_FMT 9 -#define PROBE_SHIFT_SAMPLE_END 8 -#define PROBE_SHIFT_INTERLEAVING_ST 7 +#define PROBE_SHIFT_FMT_TYPE 31 /**< Type encoding shift (1 = standard) */ +#define PROBE_SHIFT_STANDARD_TYPE 27 /**< Standard type shift (0 = audio) */ +#define PROBE_SHIFT_AUDIO_FMT 23 /**< Audio format shift (0 = PCM) */ +#define PROBE_SHIFT_SAMPLE_RATE 19 /**< Sample rate enumeration index shift */ +#define PROBE_SHIFT_NB_CHANNELS 14 /**< Channel count minus 1 shift */ +#define PROBE_SHIFT_SAMPLE_SIZE 12 /**< Valid sample bytes minus 1 shift */ +#define PROBE_SHIFT_CONTAINER_SIZE 10 /**< Container bytes minus 1 shift */ +#define PROBE_SHIFT_SAMPLE_FMT 9 /**< Sample format (0 = integer, 1 = float) */ +#define PROBE_SHIFT_SAMPLE_END 8 /**< Endianness (0 = little-endian) */ +#define PROBE_SHIFT_INTERLEAVING_ST 7 /**< Interleaving (1 = sample interleaved) */ -#define PROBE_MASK_FMT_TYPE MASK(31, 31) -#define PROBE_MASK_STANDARD_TYPE MASK(30, 27) -#define PROBE_MASK_AUDIO_FMT MASK(26, 23) -#define PROBE_MASK_SAMPLE_RATE MASK(22, 19) -#define PROBE_MASK_NB_CHANNELS MASK(18, 14) -#define PROBE_MASK_SAMPLE_SIZE MASK(13, 12) -#define PROBE_MASK_CONTAINER_SIZE MASK(11, 10) -#define PROBE_MASK_SAMPLE_FMT MASK(9, 9) -#define PROBE_MASK_SAMPLE_END MASK(8, 8) -#define PROBE_MASK_INTERLEAVING_ST MASK(7, 7) +#define PROBE_MASK_FMT_TYPE MASK(31, 31) /**< Type encoding mask */ +#define PROBE_MASK_STANDARD_TYPE MASK(30, 27) /**< Standard type mask */ +#define PROBE_MASK_AUDIO_FMT MASK(26, 23) /**< Audio format mask */ +#define PROBE_MASK_SAMPLE_RATE MASK(22, 19) /**< Sample rate mask */ +#define PROBE_MASK_NB_CHANNELS MASK(18, 14) /**< Channel count mask */ +#define PROBE_MASK_SAMPLE_SIZE MASK(13, 12) /**< Sample size mask */ +#define PROBE_MASK_CONTAINER_SIZE MASK(11, 10) /**< Container size mask */ +#define PROBE_MASK_SAMPLE_FMT MASK(9, 9) /**< Sample format mask */ +#define PROBE_MASK_SAMPLE_END MASK(8, 8) /**< Endianness mask */ +#define PROBE_MASK_INTERLEAVING_ST MASK(7, 7) /**< Interleaving mask */ +/** @} */ -#endif +#endif /* __IPC_PROBE_DMA_FRAME_H__ */ diff --git a/src/include/ipc/trace.h b/src/include/ipc/trace.h index 3f79e025edd0..15e36688f865 100644 --- a/src/include/ipc/trace.h +++ b/src/include/ipc/trace.h @@ -8,10 +8,8 @@ /** * \file include/ipc/trace.h - * \brief IPC definitions - * \author Liam Girdwood - * \author Keyon Jie - * \author Karol Trzcinski + * \brief Host-DSP IPC trace DMA configuration, filtering, and panic descriptors. + * \ingroup trace_logging_api */ #ifndef __IPC_TRACE_H__ @@ -21,35 +19,41 @@ #include #include -/* - * DMA for Trace - */ - +/** Maximum filename string length embedded in panic reports */ #define SOF_TRACE_FILENAME_SIZE 32 -/* DMA for Trace params info - SOF_IPC_TRACE_DMA_PARAMS */ -/* Deprecated - use sof_ipc_dma_trace_params_ext */ +/** + * \brief Legacy host DMA trace parameters payload (SOF_IPC_TRACE_DMA_PARAMS). + * \ingroup trace_logging_api + * @deprecated Use sof_ipc_dma_trace_params_ext instead. + */ struct sof_ipc_dma_trace_params { - struct sof_ipc_cmd_hdr hdr; - struct sof_ipc_host_buffer buffer; - uint32_t stream_tag; + struct sof_ipc_cmd_hdr hdr; /**< IPC command header */ + struct sof_ipc_host_buffer buffer; /**< Host-allocated circular buffer descriptor */ + uint32_t stream_tag; /**< Assigned host DMA stream tag */ } __attribute__((packed, aligned(4))); -/* DMA for Trace params info - SOF_IPC_TRACE_DMA_PARAMS_EXT */ +/** + * \brief Extended host DMA trace parameters payload (SOF_IPC_TRACE_DMA_PARAMS_EXT). + * \ingroup trace_logging_api + */ struct sof_ipc_dma_trace_params_ext { - struct sof_ipc_cmd_hdr hdr; - struct sof_ipc_host_buffer buffer; - uint32_t stream_tag; - uint64_t timestamp_ns; /* in nanosecnd */ - uint32_t reserved[8]; + struct sof_ipc_cmd_hdr hdr; /**< IPC command header */ + struct sof_ipc_host_buffer buffer; /**< Host-allocated circular buffer descriptor */ + uint32_t stream_tag; /**< Assigned host DMA stream tag */ + uint64_t timestamp_ns; /**< Host wallclock timestamp at synchronization point in ns */ + uint32_t reserved[8]; /**< Reserved for future expansion */ } __attribute__((packed, aligned(4))); -/* DMA for Trace params info - SOF_IPC_TRACE_DMA_POSITION */ +/** + * \brief DMA trace circular buffer position report sent to host (SOF_IPC_TRACE_DMA_POSITION). + * \ingroup trace_logging_api + */ struct sof_ipc_dma_trace_posn { - struct sof_ipc_reply rhdr; - uint32_t host_offset; /* Offset of DMA host buffer */ - uint32_t overflow; /* overflow bytes if any */ - uint32_t messages; /* total trace messages */ + struct sof_ipc_reply rhdr; /**< IPC reply header */ + uint32_t host_offset; /**< Current write offset in host DMA buffer in bytes */ + uint32_t overflow; /**< Cumulative count of dropped bytes due to buffer overflow */ + uint32_t messages; /**< Total trace messages processed since boot */ } __attribute__((packed, aligned(4))); /* Values used in sof_ipc_trace_filter_elem */ @@ -85,34 +89,37 @@ struct sof_ipc_trace_filter { * Commom debug */ -/* - * SOF panic codes +/** \name SOF Panic Codes + * Firmware panic identifiers written to mailboxes or reported upon crash. + * @{ */ -#define SOF_IPC_PANIC_MAGIC 0x0dead000 -#define SOF_IPC_PANIC_MAGIC_MASK 0x0ffff000 -#define SOF_IPC_PANIC_CODE_MASK 0x00000fff - -#define SOF_IPC_PANIC_MEM (SOF_IPC_PANIC_MAGIC | 0x0) -#define SOF_IPC_PANIC_WORK (SOF_IPC_PANIC_MAGIC | 0x1) -#define SOF_IPC_PANIC_IPC (SOF_IPC_PANIC_MAGIC | 0x2) -#define SOF_IPC_PANIC_ARCH (SOF_IPC_PANIC_MAGIC | 0x3) -#define SOF_IPC_PANIC_PLATFORM (SOF_IPC_PANIC_MAGIC | 0x4) -#define SOF_IPC_PANIC_TASK (SOF_IPC_PANIC_MAGIC | 0x5) -#define SOF_IPC_PANIC_EXCEPTION (SOF_IPC_PANIC_MAGIC | 0x6) -#define SOF_IPC_PANIC_DEADLOCK (SOF_IPC_PANIC_MAGIC | 0x7) -#define SOF_IPC_PANIC_STACK (SOF_IPC_PANIC_MAGIC | 0x8) -#define SOF_IPC_PANIC_IDLE (SOF_IPC_PANIC_MAGIC | 0x9) -#define SOF_IPC_PANIC_WFI (SOF_IPC_PANIC_MAGIC | 0xa) -#define SOF_IPC_PANIC_ASSERT (SOF_IPC_PANIC_MAGIC | 0xb) - -/* panic info include filename and line number - * filename array will not include null terminator if fully filled +#define SOF_IPC_PANIC_MAGIC 0x0dead000 /**< Magic pattern identifying valid panic packet */ +#define SOF_IPC_PANIC_MAGIC_MASK 0x0ffff000 /**< Mask isolating panic magic pattern */ +#define SOF_IPC_PANIC_CODE_MASK 0x00000fff /**< Mask isolating specific panic category */ + +#define SOF_IPC_PANIC_MEM (SOF_IPC_PANIC_MAGIC | 0x0) /**< Memory allocation exhaustion panic */ +#define SOF_IPC_PANIC_WORK (SOF_IPC_PANIC_MAGIC | 0x1) /**< Scheduling task failure panic */ +#define SOF_IPC_PANIC_IPC (SOF_IPC_PANIC_MAGIC | 0x2) /**< Host IPC transport failure panic */ +#define SOF_IPC_PANIC_ARCH (SOF_IPC_PANIC_MAGIC | 0x3) /**< Architecture exception panic */ +#define SOF_IPC_PANIC_PLATFORM (SOF_IPC_PANIC_MAGIC | 0x4) /**< Platform device driver panic */ +#define SOF_IPC_PANIC_TASK (SOF_IPC_PANIC_MAGIC | 0x5) /**< Real-time task deadline panic */ +#define SOF_IPC_PANIC_EXCEPTION (SOF_IPC_PANIC_MAGIC | 0x6) /**< Unhandled CPU exception panic */ +#define SOF_IPC_PANIC_DEADLOCK (SOF_IPC_PANIC_MAGIC | 0x7) /**< Multicore spinlock deadlock panic */ +#define SOF_IPC_PANIC_STACK (SOF_IPC_PANIC_MAGIC | 0x8) /**< Stack guard overflow panic */ +#define SOF_IPC_PANIC_IDLE (SOF_IPC_PANIC_MAGIC | 0x9) /**< Idle power state transition panic */ +#define SOF_IPC_PANIC_WFI (SOF_IPC_PANIC_MAGIC | 0xa) /**< Wait-For-Interrupt lockup panic */ +#define SOF_IPC_PANIC_ASSERT (SOF_IPC_PANIC_MAGIC | 0xb) /**< Assertion failure panic */ +/** @} */ + +/** + * \brief DSP panic crash dump descriptor reported to host. + * \ingroup trace_logging_api */ struct sof_ipc_panic_info { - struct sof_ipc_hdr hdr; - uint32_t code; /* SOF_IPC_PANIC_ */ - char filename[SOF_TRACE_FILENAME_SIZE]; - uint32_t linenum; + struct sof_ipc_hdr hdr; /**< IPC base header */ + uint32_t code; /**< Panic classification code (SOF_IPC_PANIC_*) */ + char filename[SOF_TRACE_FILENAME_SIZE]; /**< Source filename where panic occurred */ + uint32_t linenum; /**< Source line number where panic occurred */ } __attribute__((packed, aligned(4))); #endif /* __IPC_TRACE_H__ */ diff --git a/src/include/ipc3/probe.h b/src/include/ipc3/probe.h index b603f77a9cdd..0c31ce78704b 100644 --- a/src/include/ipc3/probe.h +++ b/src/include/ipc3/probe.h @@ -7,10 +7,9 @@ */ /** - * \file include/ipc/probe.h - * \brief Probe IPC definitions - * \author Adrian Bonislawski - * \author Artur Kloniecki + * \file include/ipc3/probe.h + * \brief IPC3 Audio probe points, DMA descriptors, and configuration commands. + * \ingroup audio_probe_api */ #ifndef __IPC_PROBE_H__ @@ -20,48 +19,49 @@ #include #include -/* - * Buffer id used in the probe output stream headers for - * logging data packet. - */ +/** Buffer ID used in probe stream headers for extraction logging packets */ #define PROBE_LOGGING_BUFFER_ID 0 -#define PROBE_PURPOSE_EXTRACTION 0x1 -#define PROBE_PURPOSE_INJECTION 0x2 -#define PROBE_PURPOSE_LOGGING 0x3 -#define PROBE_PURPOSE_TRACING 0x4 +/** \name Probe Tap Point Purpose + * Intended direction and role of the probe connection. + * @{ + */ +#define PROBE_PURPOSE_EXTRACTION 0x1 /**< Extract audio stream from buffer to host */ +#define PROBE_PURPOSE_INJECTION 0x2 /**< Inject host audio stream into buffer */ +#define PROBE_PURPOSE_LOGGING 0x3 /**< Route probe packets to logging backend */ +#define PROBE_PURPOSE_TRACING 0x4 /**< Real-time pipeline trace capture */ +/** @} */ /** - * Description of probe dma + * \brief Host DMA channel descriptor allocated for audio probes. + * \ingroup audio_probe_api */ struct probe_dma { - uint32_t stream_tag; /**< Stream tag associated with this DMA */ - uint32_t dma_buffer_size; /**< Size of buffer associated with this DMA */ + uint32_t stream_tag; /**< Stream tag associated with this DMA channel */ + uint32_t dma_buffer_size; /**< Size of host DMA buffer in bytes */ } __attribute__((packed, aligned(4))); /** - * Description of probe point id + * \brief Packed identifier identifying target audio buffer for probe attachment. + * \ingroup audio_probe_api */ typedef struct probe_point_id { - uint32_t full_id; + uint32_t full_id; /**< Packed buffer identifier */ } __attribute__((packed, aligned(4))) probe_point_id_t; /** - * Description of probe point + * \brief Probe tap point descriptor binding a pipeline buffer to a probe purpose. + * \ingroup audio_probe_api */ struct probe_point { - probe_point_id_t buffer_id; /**< ID of buffer to which probe is attached */ - uint32_t purpose; /**< PROBE_PURPOSE_xxx */ - uint32_t stream_tag; /**< Stream tag of DMA via which data will be provided for injection. - * For extraction purposes, stream tag is ignored when received, - * but returned actual extraction stream tag via INFO function. - */ + probe_point_id_t buffer_id; /**< ID of pipeline buffer to which probe is attached */ + uint32_t purpose; /**< Probe role (PROBE_PURPOSE_*) */ + uint32_t stream_tag; /**< Stream tag of DMA for injection; ignored on extraction request and populated on reply */ } __attribute__((packed, aligned(4))); /** - * \brief DMA ADD for probes. - * - * Used as payload for IPCs: SOF_IPC_PROBE_INIT, SOF_IPC_PROBE_DMA_ADD. + * \brief DMA ADD for probes payload (SOF_IPC_PROBE_INIT, SOF_IPC_PROBE_DMA_ADD). + * \ingroup audio_probe_api */ struct sof_ipc_probe_dma_add_params { struct sof_ipc_cmd_hdr hdr; /**< Header */ @@ -70,9 +70,8 @@ struct sof_ipc_probe_dma_add_params { } __attribute__((packed, aligned(4))); /** - * \brief Reply to INFO functions. - * - * Used as payload for IPCs: SOF_IPC_PROBE_DMA_INFO, SOF_IPC_PROBE_POINT_INFO. + * \brief Reply to INFO queries (SOF_IPC_PROBE_DMA_INFO, SOF_IPC_PROBE_POINT_INFO). + * \ingroup audio_probe_api */ struct sof_ipc_probe_info_params { struct sof_ipc_reply rhdr; /**< Header */ @@ -84,9 +83,8 @@ struct sof_ipc_probe_info_params { } __attribute__((packed, aligned(4))); /** - * \brief Probe DMA remove. - * - * Used as payload for IPC: SOF_IPC_PROBE_DMA_REMOVE + * \brief Probe DMA remove payload (SOF_IPC_PROBE_DMA_REMOVE). + * \ingroup audio_probe_api */ struct sof_ipc_probe_dma_remove_params { struct sof_ipc_cmd_hdr hdr; /**< Header */ @@ -95,9 +93,8 @@ struct sof_ipc_probe_dma_remove_params { } __attribute__((packed, aligned(4))); /** - * \brief Add probe points. - * - * Used as payload for IPC: SOF_IPC_PROBE_POINT_ADD + * \brief Add probe points payload (SOF_IPC_PROBE_POINT_ADD). + * \ingroup audio_probe_api */ struct sof_ipc_probe_point_add_params { struct sof_ipc_cmd_hdr hdr; /**< Header */ @@ -106,9 +103,8 @@ struct sof_ipc_probe_point_add_params { } __attribute__((packed, aligned(4))); /** - * \brief Remove probe point. - * - * Used as payload for IPC: SOF_IPC_PROBE_POINT_REMOVE + * \brief Remove probe points payload (SOF_IPC_PROBE_POINT_REMOVE). + * \ingroup audio_probe_api */ struct sof_ipc_probe_point_remove_params { struct sof_ipc_cmd_hdr hdr; /**< Header */ diff --git a/src/include/kernel/mailbox.h b/src/include/kernel/mailbox.h index f41be84fb3b9..4b7d7e110ec2 100644 --- a/src/include/kernel/mailbox.h +++ b/src/include/kernel/mailbox.h @@ -6,10 +6,10 @@ */ /** - * \file include/kernel/mailbox.h - * \brief FW Regs API definition - * \author Adrian Bonislawski - */ + * \file include/kernel/mailbox.h + * \brief SRAM Window 0 firmware status registers and telemetry offset definitions. + * \ingroup telemetry_perf_api + */ #ifndef __KERNEL_MAILBOX_H__ #define __KERNEL_MAILBOX_H__ @@ -18,45 +18,44 @@ #include #endif -/** \addtogroup probe_api - * This is a common SRAM window 0 FW "registers" layout - * used in the platfrom-defined SRAM window 0 region +/** \addtogroup telemetry_perf_api + * Common SRAM Window 0 firmware status and telemetry register offsets. * @{ */ #if CONFIG_IPC_MAJOR_4 -#define SRAM_REG_FW_STATUS offsetof(struct ipc4_fw_registers, fsr) -#define SRAM_REG_LAST_ERROR_CODE offsetof(struct ipc4_fw_registers, lec) -#define SRAM_REG_FW_PWR_STATUS offsetof(struct ipc4_fw_registers, fps) -#define SRAM_REG_LNEC offsetof(struct ipc4_fw_registers, lnec) -#define SRAM_REG_LTR offsetof(struct ipc4_fw_registers, ltr) -#define SRAM_REG_ROM_INFO offsetof(struct ipc4_fw_registers, rom_info) -#define SRAM_REG_ABI_VER offsetof(struct ipc4_fw_registers, abi_ver) -#define SRAM_REG_SLAVE_CORE_STS offsetof(struct ipc4_fw_registers, slave_core_sts) -#define SRAM_REG_PIPELINE_REGS offsetof(struct ipc4_fw_registers, pipeline_regs) -#define SRAM_REG_PEAK_VOL_REGS offsetof(struct ipc4_fw_registers, peak_vol_regs) -#define SRAM_REG_LLP_GPDMA_READING_SLOTS offsetof(struct ipc4_fw_registers, llp_gpdma_reading_slots) -#define SRAM_REG_LLP_SNDW_READING_SLOTS offsetof(struct ipc4_fw_registers, llp_sndw_reading_slots) -#define SRAM_REG_LLP_EVAD_SLOTS offsetof(struct ipc4_fw_registers, llp_evad_reading_slot) -#define SRAM_REG_FW_END sizeof(struct ipc4_fw_registers) +#define SRAM_REG_FW_STATUS offsetof(struct ipc4_fw_registers, fsr) /**< Offset to Firmware Status Register (FSR) */ +#define SRAM_REG_LAST_ERROR_CODE offsetof(struct ipc4_fw_registers, lec) /**< Offset to Last Error Code (LEC) */ +#define SRAM_REG_FW_PWR_STATUS offsetof(struct ipc4_fw_registers, fps) /**< Offset to Firmware Power Status (FPS) */ +#define SRAM_REG_LNEC offsetof(struct ipc4_fw_registers, lnec) /**< Offset to Last Native Error Code (LNEC) */ +#define SRAM_REG_LTR offsetof(struct ipc4_fw_registers, ltr) /**< Offset to Latency Tolerance Reporting (LTR) */ +#define SRAM_REG_ROM_INFO offsetof(struct ipc4_fw_registers, rom_info) /**< Offset to ROM bootstrap information */ +#define SRAM_REG_ABI_VER offsetof(struct ipc4_fw_registers, abi_ver) /**< Offset to ABI version field */ +#define SRAM_REG_SLAVE_CORE_STS offsetof(struct ipc4_fw_registers, slave_core_sts) /**< Offset to Secondary core power/run status */ +#define SRAM_REG_PIPELINE_REGS offsetof(struct ipc4_fw_registers, pipeline_regs) /**< Offset to pipeline state register array */ +#define SRAM_REG_PEAK_VOL_REGS offsetof(struct ipc4_fw_registers, peak_vol_regs) /**< Offset to peak volume meter register array */ +#define SRAM_REG_LLP_GPDMA_READING_SLOTS offsetof(struct ipc4_fw_registers, llp_gpdma_reading_slots) /**< Offset to GPDMA linear link position reading slots */ +#define SRAM_REG_LLP_SNDW_READING_SLOTS offsetof(struct ipc4_fw_registers, llp_sndw_reading_slots) /**< Offset to SoundWire link position reading slots */ +#define SRAM_REG_LLP_EVAD_SLOTS offsetof(struct ipc4_fw_registers, llp_evad_reading_slot) /**< Offset to EVAD position reading slot */ +#define SRAM_REG_FW_END sizeof(struct ipc4_fw_registers) /**< Total size boundary of Window 0 firmware register block */ #else /* CONFIG_IPC_MAJOR_4 */ -#define SRAM_REG_ROM_STATUS 0x0 -#define SRAM_REG_FW_STATUS 0x4 -#define SRAM_REG_FW_TRACEP 0x8 -#define SRAM_REG_FW_IPC_RECEIVED_COUNT 0xc -#define SRAM_REG_FW_IPC_PROCESSED_COUNT 0x10 -#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_BASE 0x14 -#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_1 SRAM_REG_FW_TRACEP_SECONDARY_CORE_BASE -#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_2 0x18 -#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_3 0x1C -#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_4 0x20 -#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_5 0x24 -#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_6 0x28 -#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_7 0x2C -#define SRAM_REG_R_STATE_TRACE_BASE 0x30 -#define SRAM_REG_R0_STATE_TRACE SRAM_REG_R_STATE_TRACE_BASE -#define SRAM_REG_R1_STATE_TRACE 0x38 -#define SRAM_REG_R2_STATE_TRACE 0x40 -#define SRAM_REG_FW_END (SRAM_REG_R2_STATE_TRACE + 0x8) +#define SRAM_REG_ROM_STATUS 0x0 /**< ROM bootstrap status */ +#define SRAM_REG_FW_STATUS 0x4 /**< Firmware run status */ +#define SRAM_REG_FW_TRACEP 0x8 /**< Primary core trace buffer pointer */ +#define SRAM_REG_FW_IPC_RECEIVED_COUNT 0xc /**< Total IPC messages received from host */ +#define SRAM_REG_FW_IPC_PROCESSED_COUNT 0x10 /**< Total IPC messages dispatched */ +#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_BASE 0x14 /**< Base offset for secondary core trace pointers */ +#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_1 SRAM_REG_FW_TRACEP_SECONDARY_CORE_BASE /**< Core 1 trace pointer */ +#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_2 0x18 /**< Core 2 trace pointer */ +#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_3 0x1C /**< Core 3 trace pointer */ +#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_4 0x20 /**< Core 4 trace pointer */ +#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_5 0x24 /**< Core 5 trace pointer */ +#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_6 0x28 /**< Core 6 trace pointer */ +#define SRAM_REG_FW_TRACEP_SECONDARY_CORE_7 0x2C /**< Core 7 trace pointer */ +#define SRAM_REG_R_STATE_TRACE_BASE 0x30 /**< Base offset for power state trace */ +#define SRAM_REG_R0_STATE_TRACE SRAM_REG_R_STATE_TRACE_BASE /**< Core 0 power state trace */ +#define SRAM_REG_R1_STATE_TRACE 0x38 /**< Core 1 power state trace */ +#define SRAM_REG_R2_STATE_TRACE 0x40 /**< Core 2 power state trace */ +#define SRAM_REG_FW_END (SRAM_REG_R2_STATE_TRACE + 0x8) /**< End of register block */ #endif /** @}*/ diff --git a/src/include/sof/debug/debug.h b/src/include/sof/debug/debug.h index 76eec7062de3..3cc14416acca 100644 --- a/src/include/sof/debug/debug.h +++ b/src/include/sof/debug/debug.h @@ -6,6 +6,12 @@ * Keyon Jie */ +/** + * \file include/sof/debug/debug.h + * \brief Early firmware bootstrap debug dumps, mailbox peek/poke, and diagnostic helpers. + * \ingroup debug_stream_api + */ + #ifndef __SOF_DEBUG_DEBUG_H__ #define __SOF_DEBUG_DEBUG_H__ @@ -30,13 +36,14 @@ #include +/** Firmware ready flags describing debug capabilities (GDB, build flags) */ #define DEBUG_SET_FW_READY_FLAGS \ ( \ SOF_IPC_INFO_BUILD | \ (IS_ENABLED(CONFIG_GDB_DEBUG) ? SOF_IPC_INFO_GDB : 0) \ ) -/* dump file and line to start of mailbox or shared memory */ +/** \brief Dump current file name, function name, and line number to base of debug mailbox */ #define dbg() \ do { \ volatile uint32_t *__m = (uint32_t *)mailbox_get_debug_base(); \ @@ -48,7 +55,7 @@ *__m = __LINE__; \ } while (0) -/* dump file and line to offset in mailbox or shared memory */ +/** \brief Dump current file, function, and line to specific 32-bit word offset in debug mailbox */ #define dbg_at(__x) \ do { \ volatile uint32_t *__m = \ @@ -61,7 +68,7 @@ *__m = __LINE__; \ } while (0) -/* dump value to start of mailbox or shared memory */ +/** \brief Dump a 32-bit integer value directly to start of debug mailbox */ #define dbg_val(__v) \ do { \ volatile uint32_t *__m = \ @@ -69,7 +76,7 @@ *__m = __v; \ } while (0) -/* dump value to offset in mailbox or shared memory */ +/** \brief Dump a 32-bit integer value to specific word offset in debug mailbox */ #define dbg_val_at(__v, __x) \ do { \ volatile uint32_t *__m = \ @@ -77,7 +84,7 @@ *__m = __v; \ } while (0) -/* dump data area at addr and size count to start of mailbox or shared memory */ +/** \brief Dump raw memory buffer of given 32-bit word count to start of debug mailbox */ #define dump(addr, count) \ do { \ volatile uint32_t *__m = (uint32_t *)mailbox_get_debug_base(); \ @@ -87,7 +94,7 @@ *(__m++) = *(__a++); \ } while (0) -/* dump data area at addr and size count at mailbox offset or shared memory */ +/** \brief Dump memory buffer of given 32-bit word count to mailbox offset */ #define dump_at(addr, count, offset) \ do { \ volatile uint32_t *__m = \ @@ -98,20 +105,21 @@ *(__m++) = *(__a++); \ } while (0) -/* dump object to start of mailbox */ +/** \brief Dump a stack/global object and source location to start of debug mailbox */ #define dump_object(__o) \ do { \ dbg(); \ dump(&__o, sizeof(__o) >> 2); \ } while (0) -/* dump object from pointer at start of mailbox */ +/** \brief Dump an object from pointer and source location to start of debug mailbox */ #define dump_object_ptr(__o) \ do { \ dbg(); \ dump(__o, sizeof(*(__o)) >> 2); \ } while (0) +/** \brief Dump an object from pointer to specific offset in debug mailbox */ #define dump_object_ptr_at(__o, __at) \ do { \ dbg(); \ diff --git a/src/include/sof/debug/gdb/gdb.h b/src/include/sof/debug/gdb/gdb.h index 338b97b27541..5cf3d78fde50 100644 --- a/src/include/sof/debug/gdb/gdb.h +++ b/src/include/sof/debug/gdb/gdb.h @@ -5,6 +5,12 @@ * Author: Marcin Rajwa */ +/** + * \file include/sof/debug/gdb/gdb.h + * \brief GDB target debug stub, exception traps, and register accessors. + * \ingroup debug_stream_api + */ + #ifndef __SOF_DEBUG_GDB_GDB_H__ #define __SOF_DEBUG_GDB_GDB_H__ @@ -35,12 +41,31 @@ #define GDB_SPEC_REG_RANGE_END 0x300 /**< identifies spec registers range */ #define GDB_REG_RANGE_END 0x400 /**< identifies spec registers range */ +/** + * \brief Exception handler hook triggered on GDB breakpoint or watchpoint trap. + * \ingroup debug_stream_api + */ void gdb_handle_exception(void); + +/** + * \brief Output diagnostic debug string to connected GDB client. + * \ingroup debug_stream_api + * @param[in] str Null-terminated string to transmit. + */ void gdb_debug_info(unsigned char *str); + +/** + * \brief Initialize debug exception vectors and trap handlers. + * \ingroup debug_stream_api + */ void gdb_init_debug_exception(void); #endif /* CONFIG_GDB_DEBUG */ +/** + * \brief Initialize the GDB target debugging stub and register listeners. + * \ingroup debug_stream_api + */ void gdb_init(void); #endif /* __SOF_DEBUG_GDB_GDB_H__ */ diff --git a/src/include/sof/debug/telemetry/performance_monitor.h b/src/include/sof/debug/telemetry/performance_monitor.h index 337e353dafc4..68a1592ff40f 100644 --- a/src/include/sof/debug/telemetry/performance_monitor.h +++ b/src/include/sof/debug/telemetry/performance_monitor.h @@ -5,88 +5,97 @@ * Author: Tobiasz Dryjanski */ +/** + * \file include/sof/debug/telemetry/performance_monitor.h + * \brief Component performance measurement, cycle accounting, and Memory Window 3 slots. + * \ingroup telemetry_perf_api + */ + #ifndef __SOF_PERFORMANCE_MONITOR_H__ #define __SOF_PERFORMANCE_MONITOR_H__ #include -/* to be moved to Zephyr */ +/** Base address of Memory Window 3 memory node from device tree */ #define WIN3_MBASE DT_REG_ADDR(DT_PHANDLE(DT_NODELABEL(mem_window3), memory)) +/** Uncached pointer to ADSP Performance Measurement Window (PMW) in Window 3 */ #define ADSP_PMW ((volatile uint32_t *) \ (sys_cache_uncached_ptr_get((__sparse_force void __sparse_cache *) \ (WIN3_MBASE + WIN3_OFFSET)))) -#if IS_ENABLED(CONFIG_SOF_TELEMETRY_PERFORMANCE_MEASUREMENTS) +#if IS_ENABLED(CONFIG_SOF_TELEMETRY_PERFORMANCE_MEASUREMENTS) || defined(__DOXYGEN__) /** - * Initializer for struct perf_data_item_comp - * - * @param[out] perf Struct to be initialized - * @param[in] resource_id - * @param[in] power_mode + * \brief Initializer for component performance data record. + * \ingroup telemetry_perf_api + * @param[out] perf Structure to be initialized. + * @param[in] resource_id Unique resource/component identifier. + * @param[in] power_mode Active power mode. */ void perf_data_item_comp_init(struct perf_data_item_comp *perf, uint32_t resource_id, uint32_t power_mode); /** - * Get next free performance data slot from Memory Window 3 - * - * @return performance data record + * \brief Allocate next free performance data slot from Memory Window 3. + * \ingroup telemetry_perf_api + * @return Pointer to allocated performance data record, or NULL if window is full. */ struct perf_data_item_comp *perf_data_getnext(void); /** - * Free a performance data slot in Memory Window 3 - * - * @return 0 if succeeded, in other case the slot is already free + * \brief Release an allocated performance data slot in Memory Window 3. + * \ingroup telemetry_perf_api + * @param[in,out] item Pointer to performance data item to release. + * @return 0 on success, or negative error code if slot was already free. */ int free_performance_data(struct perf_data_item_comp *item); /** - * Set performance measurements state - * - * @param[in] state Value to be set. + * \brief Set global performance measurement state machine. + * \ingroup telemetry_perf_api + * @param[in] state Target measurement state (disabled, paused, enabled). */ void perf_meas_set_state(enum ipc4_perf_measurements_state_set state); /** - * Get performance measurements state - * - * @return performance measurements state + * \brief Query current global performance measurement state. + * \ingroup telemetry_perf_api + * @return Current measurement state enumeration value. */ enum ipc4_perf_measurements_state_set perf_meas_get_state(void); /** - * Get global performance data entries. - * - * @param[out] global_perf_data Struct to be filled with data - * @return 0 if succeeded, error code otherwise. + * \brief Retrieve global aggregated performance telemetry data. + * \ingroup telemetry_perf_api + * @param[out] global_perf_data Destination structure to populate. + * @return 0 on success, or negative error code on failure. */ int get_performance_data(struct global_perf_data * const global_perf_data); /** - * Get extended global performance data entries. - * - * @param[out] ext_global_perf_data Struct to be filled with data - * @return 0 if succeeded, error code otherwise. + * \brief Retrieve extended global performance telemetry data with per-core breakdown. + * \ingroup telemetry_perf_api + * @param[out] ext_global_perf_data Destination structure to populate. + * @return 0 on success, or negative error code on failure. */ int get_extended_performance_data(struct extended_global_perf_data * const ext_global_perf_data); /** - * Reset performance data values for all records. - * - * @return 0 if succeeded, error code otherwise. + * \brief Reset all performance measurement counters across all components. + * \ingroup telemetry_perf_api + * @return 0 on success, or negative error code on failure. */ int reset_performance_counters(void); /** - * Reinitialize performance data values for all created components; - * - * @return 0 if succeeded, error code otherwise. + * \brief Reinitialize and activate performance counters for all created components. + * \ingroup telemetry_perf_api + * @return 0 on success, or negative error code on failure. */ int enable_performance_counters(void); /** - * Unregister performance data records marked for removal. + * \brief Disable performance counters and unregister records marked for removal. + * \ingroup telemetry_perf_api */ void disable_performance_counters(void); diff --git a/src/include/sof/debug/telemetry/telemetry.h b/src/include/sof/debug/telemetry/telemetry.h index ce1aef588f2d..a3694735cb4f 100644 --- a/src/include/sof/debug/telemetry/telemetry.h +++ b/src/include/sof/debug/telemetry/telemetry.h @@ -3,6 +3,12 @@ * Copyright(c) 2024 Intel Corporation. All rights reserved. */ +/** + * \file include/sof/debug/telemetry/telemetry.h + * \brief Hardware telemetry metrics, CPU cycle accounting, and Memory Window telemetry slots. + * \ingroup telemetry_perf_api + */ + #ifndef __SOF_TELEMETRY_H__ #define __SOF_TELEMETRY_H__ @@ -12,102 +18,79 @@ #endif #ifndef CONFIG_INTEL_ADSP_DEBUG_SLOT_MANAGER -/* Slot in memory window 2 (Debug Window) to be used as telemetry slot */ +/** Slot index in memory window 2 (Debug Window) allocated for telemetry structures */ #define SOF_DW_TELEMETRY_SLOT 1 #endif -/* Memory of average algorithm of performance queue */ +/** Number of historic entries in circular performance measurement queue */ #define SOF_AVG_PERF_MEAS_DEPTH 64 -/* Number of runs taken to calculate average (algorithm resolution) */ +/** Measurement period in runs over which rolling average is computed */ #define SOF_AVG_PERF_MEAS_PERIOD 16 -/* Systick here is not to be confused with neither Zephyr tick nor SOF scheduler tick, - * it's a legacy name for counting execution time +/** + * \brief Per-core system tick and cycle execution metrics. + * \ingroup telemetry_perf_api + * + * @note In this context, "systick" is a legacy terminology for counting DSP execution + * time intervals. It is neither related to the Zephyr RTOS system tick nor the SOF + * scheduler tick. */ struct system_tick_info { - uint32_t count; - uint32_t last_time_elapsed; - uint32_t max_time_elapsed; - uint32_t last_ccount; - uint32_t avg_utilization; - uint32_t peak_utilization; - uint32_t peak_utilization_4k; - uint32_t peak_utilization_8k; - uint32_t rsvd[2]; + uint32_t count; /**< Total tick / measurement iteration count */ + uint32_t last_time_elapsed; /**< Cycles consumed during previous tick interval */ + uint32_t max_time_elapsed; /**< Peak cycle consumption observed across all intervals */ + uint32_t last_ccount; /**< Cycle counter snapshot at end of previous tick */ + uint32_t avg_utilization; /**< Rolling average CPU utilization percentage (0-100) */ + uint32_t peak_utilization; /**< Peak CPU utilization percentage observed */ + uint32_t peak_utilization_4k; /**< Peak utilization over 4K sample rolling window */ + uint32_t peak_utilization_8k; /**< Peak utilization over 8K sample rolling window */ + uint32_t rsvd[2]; /**< Reserved for padding and future metrics */ } __packed; -/* - * This is the structure of telemetry data in memory window. - * If you need to define a field, you should also define the fields before it to - * keep the internal structures aligned with each other. +/** + * \brief Layout of telemetry data published in shared Memory Window. + * \ingroup telemetry_perf_api */ struct telemetry_wnd_data { - uint32_t separator_1; - struct system_tick_info system_tick_info[CONFIG_MAX_CORE_COUNT]; - /* - * uint32_t separator_2; - * deadlock_info_s deadlock_info[FW_REPORTED_MAX_CORES_COUNT]; - * uint32_t separator_3; - * assert_info_s assert_info; - * uint32_t separator_4; - * xxxruns_info_s xxxruns_info; - * uint32_t separator_5; - * performance_info_s performance_info; - * uint32_t separator_6; - * mem_pools_info_s mem_pools_info; - * uint32_t separator_7; - * timeout_info_s timeout_info; - * uint32_t separator_8; - * ulp_telemetry_s ulp_telemetry; - * uint32_t separator_9; - * transition_info_s evad_transition_info; - * uint32_t separator_10; - * task_info_s task_info[FW_MAX_REPORTED_TASKS]; - * uint32_t separator_11; - * transition_info_s d0i3_info[FW_REPORTED_MAX_CORES_COUNT]; - * uint32_t separator_12; - * interrupt_stats_info_s interrupt_stats; - * uint32_t separator_13; - * loaded_libraries_s loaded_libraries; - * //uint32_t __pad_for_exception_record; - * uint32_t separator_exception; - * CoreExceptionRecord core_exception_record[FW_REPORTED_MAX_CORES_COUNT]; - */ + uint32_t separator_1; /**< Header boundary delimiter */ + struct system_tick_info system_tick_info[CONFIG_MAX_CORE_COUNT]; /**< Per-core execution metrics */ } __packed; -/* Reference FW used a normal Queue here. - * Implementing simplified queue just for avg calculation. - * Queue is circular, oldest element replaced by latest +/** + * \brief Circular queue tracking execution cycle history for rolling averages. + * \ingroup telemetry_perf_api */ struct telemetry_perf_queue { - size_t elements[SOF_AVG_PERF_MEAS_DEPTH]; - /* next empty element, head if queue is full, else tail */ - size_t index; - uint8_t full; - /* number of items AND index of next empty box */ - size_t size; - size_t sum; + size_t elements[SOF_AVG_PERF_MEAS_DEPTH]; /**< Historic cycle measurements */ + size_t index; /**< Current head index in circular queue */ + uint8_t full; /**< 1 if queue has wrapped, 0 otherwise */ + size_t size; /**< Number of valid measurements stored */ + size_t sum; /**< Running cumulative sum of valid measurements */ }; /** - * @brief Update periodic telemetry metrics with elapsed core clock cycles. - * @param begin_ccount Cycle count at start of measurement window. - * @param current_ccount Cycle count at current measurement point. + * \brief Update periodic telemetry metrics with elapsed core clock cycles. + * \ingroup telemetry_perf_api + * @param begin_ccount Cycle count snapshot at start of measurement interval. + * @param current_ccount Cycle count snapshot at end of measurement interval. */ void telemetry_update(uint32_t begin_ccount, uint32_t current_ccount); #ifdef CONFIG_INTEL_ADSP_DEBUG_SLOT_MANAGER /** - * @brief Get pointer to system tick telemetry information structure. - * @return Pointer to struct system_tick_info. + * \brief Retrieve pointer to system tick telemetry structure for current core. + * \ingroup telemetry_perf_api + * @return Pointer to struct system_tick_info in shared memory. */ struct system_tick_info *telemetry_get_systick_info_ptr(void); #endif #ifdef CONFIG_TIMING_FUNCTIONS +/** Timestamp counter accessor using Zephyr timing functions */ #define telemetry_timestamp timing_counter_get #else +/** Timestamp counter accessor using hardware cycle counter */ #define telemetry_timestamp sof_cycle_get_64 #endif -#endif /*__SOF_TELEMETRY_H__ */ +#endif /* __SOF_TELEMETRY_H__ */ diff --git a/src/include/sof/probe/probe.h b/src/include/sof/probe/probe.h index de8873ad0a67..41aff007c8f9 100644 --- a/src/include/sof/probe/probe.h +++ b/src/include/sof/probe/probe.h @@ -5,6 +5,12 @@ * Author: Artur Kloniecki */ +/** + * \file include/sof/probe/probe.h + * \brief Audio probe injection and extraction tap points and DMA manager. + * \ingroup audio_probe_api + */ + #ifndef __SOF_PROBE_PROBE_H__ #define __SOF_PROBE_PROBE_H__ @@ -12,7 +18,11 @@ #include /** - * A buffer of logging data is available for processing. + * \brief Callback hook invoked when a chunk of probe logging data is ready. + * \ingroup audio_probe_api + * @param buffer Pointer to raw probe buffer payload. + * @param length Byte length of data available. + * @return Number of bytes processed, or negative error code. */ typedef ssize_t(*probe_logging_hook_t)(uint8_t *buffer, size_t length); @@ -22,83 +32,86 @@ bool probe_is_backend_configured(void); #endif /** - * @brief Initialize the probe logging backend. - * - * @param hook Function is called when new logging data is written - * out by the logger. + * \brief Initialize the probe logging backend. + * \ingroup audio_probe_api + * @param hook Callback invoked when new logging data is written out. */ void probe_logging_init(probe_logging_hook_t hook); -/* - * \brief Initialize probes subsystem - * - * param[in,optional] extraction_probe_dma - DMA associated with extraction - * In case extraction_probe_dma is NULL, extraction probes - * are unavailable. +/** + * \brief Initialize the audio probes subsystem. + * \ingroup audio_probe_api + * @param[in] extraction_probe_dma Host DMA channel configured for data extraction, + * or NULL if extraction probes are not used. + * @return 0 on success, or negative error code on failure. */ int probe_init(const struct probe_dma *extraction_probe_dma); -/* - * \brief Deinitialize probes subsystem. - * - * Detach extraction DMA if was enabled. Return -EINVAL in case some probes - * are still in use. +/** + * \brief Deinitialize the probes subsystem and detach extraction DMA. + * \ingroup audio_probe_api + * @return 0 on success, or -EINVAL if active probe points remain connected. */ int probe_deinit(void); -/* - * \brief Setup injection DMAs for probes. - * - * param[in] count - number of DMAs configured during this call - * param[in] probe_dma - Array of size 'count' with configuration data for DMAs +/** + * \brief Configure injection DMA channels for inserting audio streams into pipelines. + * \ingroup audio_probe_api + * @param[in] count Number of DMA descriptors provided in array. + * @param[in] probe_dma Array of probe DMA descriptors specifying stream tags and buffer sizes. + * @return 0 on success, or negative error code on failure. */ int probe_dma_add(uint32_t count, const struct probe_dma *probe_dma); -/* - * \brief Get info about connected injection DMAs - * - * param[in,out] data - reply to write data to - * param[in] max_size - maximum number of bytes available in data +/** + * \brief Query configuration information for active injection DMAs. + * \ingroup audio_probe_api + * @param[out] data Reply payload structure populated with connected DMA details. + * @param[in] max_size Maximum available capacity in data buffer in bytes. + * @return 0 on success, or negative error code on failure. */ int probe_dma_info(struct sof_ipc_probe_info_params *data, uint32_t max_size); -/* - * \brief Remove injection DMAs - * - * param[in] count - number of DMAs removed during this call - * param[in] stream_tag - array for size 'count' with stream tags associated - * with DMAs to be removed +/** + * \brief Disconnect and remove active injection DMA channels. + * \ingroup audio_probe_api + * @param[in] count Number of stream tags in array. + * @param[in] stream_tag Array of host DMA stream tags to remove. + * @return 0 on success, or negative error code on failure. */ int probe_dma_remove(uint32_t count, const uint32_t *stream_tag); -/* - * \brief Set probe points - * - * param[in] count - number of probe points configured this call - * param[in] probe - array of size 'count' with configuration of probe points +/** + * \brief Attach probe points to audio pipeline buffers for stream tap/injection. + * \ingroup audio_probe_api + * @param[in] count Number of probe points in array. + * @param[in] probe Array of probe point descriptors specifying buffer IDs and purpose. + * @return 0 on success, or negative error code on failure. */ int probe_point_add(uint32_t count, const struct probe_point *probe); -/* - * \brief Get info about connected probe points - * - * param[in,out] data - reply to write data to - * param[in] max_size - maximum number of bytes available in data +/** + * \brief Query configuration of currently active probe points. + * \ingroup audio_probe_api + * @param[out] data Reply payload structure populated with connected probe points. + * @param[in] max_size Maximum available capacity in data buffer in bytes. + * @return 0 on success, or negative error code on failure. */ int probe_point_info(struct sof_ipc_probe_info_params *data, uint32_t max_size); -/* - * \brief Remove probe points - * - * param[in] count - number of probe points removed this call - * param[in] buffer_id - array of size 'count' with IDs of buffers to which - * probes were attached +/** + * \brief Detach and remove probe points from pipeline buffers. + * \ingroup audio_probe_api + * @param[in] count Number of buffer IDs in array. + * @param[in] buffer_id Array of buffer IDs from which probe points should be detached. + * @return 0 on success, or negative error code on failure. */ int probe_point_remove(uint32_t count, const uint32_t *buffer_id); /** - * \brief Retrieves probes structure. - * \return Pointer to probes structure. + * \brief Retrieve global probes private data context from SOF runtime. + * \ingroup audio_probe_api + * \return Pointer to struct probe_pdata. */ static inline struct probe_pdata *probe_get(void) { diff --git a/src/include/sof/trace/dma-trace.h b/src/include/sof/trace/dma-trace.h index dbc9e666da47..018576cd7ca2 100644 --- a/src/include/sof/trace/dma-trace.h +++ b/src/include/sof/trace/dma-trace.h @@ -5,6 +5,12 @@ * Author: Yan Wang */ +/** + * \file include/sof/trace/dma-trace.h + * \brief Direct Memory Access (DMA) trace buffer management and host streaming. + * \ingroup trace_logging_api + */ + #ifndef __SOF_TRACE_DMA_TRACE_H__ #define __SOF_TRACE_DMA_TRACE_H__ @@ -18,59 +24,146 @@ struct ipc_msg; struct sof; +/** + * \brief Internal ring buffer descriptor for DSP trace packets. + * \ingroup trace_logging_api + */ struct dma_trace_buf { - void *w_ptr; /* buffer write pointer */ - void *r_ptr; /* buffer read position */ - void *addr; /* buffer base address */ - void *end_addr; /* buffer end address */ - uint32_t size; /* size of buffer in bytes */ - uint32_t avail; /* bytes available to read */ + void *w_ptr; /**< Buffer write pointer where new trace packets are appended */ + void *r_ptr; /**< Buffer read pointer tracking data transferred by DMA */ + void *addr; /**< Base address of the circular trace buffer */ + void *end_addr; /**< Upper boundary address of the trace buffer */ + uint32_t size; /**< Total size of the buffer in bytes */ + uint32_t avail; /**< Number of readable bytes currently available */ }; +/** + * \brief Main DMA trace context and state machine descriptor. + * \ingroup trace_logging_api + */ struct dma_trace_data { - struct dma_sg_config config; - struct dma_trace_buf dmatb; - struct dma_copy dc; - struct sof_ipc_dma_trace_posn posn; - struct ipc_msg *msg; - uint32_t host_size; - struct task dmat_work; - uint32_t enabled; - uint32_t copy_in_progress; - uint32_t stream_tag; - uint32_t active_stream_tag; - uint32_t dma_copy_align; /* Minimal chunk of data possible to be - * copied by dma connected to host - */ - uint32_t dropped_entries; /* amount of dropped entries */ - struct k_spinlock lock; /* dma trace lock */ - uint64_t time_delta; /* difference between the host time */ + struct dma_sg_config config; /**< Scatter-gather configuration for host DMA */ + struct dma_trace_buf dmatb; /**< Internal circular buffer tracking read/write pointers */ + struct dma_copy dc; /**< DMA copy engine instance */ + struct sof_ipc_dma_trace_posn posn; /**< Position report payload sent to host */ + struct ipc_msg *msg; /**< IPC message used to report buffer position */ + uint32_t host_size; /**< Total size of host-allocated trace buffer */ + struct task dmat_work; /**< Periodic scheduling task driving DMA transfers */ + uint32_t enabled; /**< 1 if DMA trace streaming is active, 0 otherwise */ + uint32_t copy_in_progress; /**< 1 if a DMA copy operation is currently underway */ + uint32_t stream_tag; /**< Assigned host DMA stream tag */ + uint32_t active_stream_tag; /**< Current active stream tag */ + uint32_t dma_copy_align; /**< Minimal byte alignment required for DMA transfer chunks */ + uint32_t dropped_entries; /**< Cumulative counter of dropped entries due to buffer overflow */ + struct k_spinlock lock; /**< Spinlock synchronizing buffer writes and DMA triggers */ + uint64_t time_delta; /**< Offset between host wallclock and DSP hardware timer */ }; +/** + * \brief Early initialization of the DMA trace subsystem during bootstrap. + * \ingroup trace_logging_api + * @param[in,out] sof Global SOF system context. + * @return 0 on success, or negative error code on failure. + */ int dma_trace_init_early(struct sof *sof); + +/** + * \brief Complete initialization of DMA trace once host channel is negotiated. + * \ingroup trace_logging_api + * @param[in,out] d DMA trace data context. + * @return 0 on success, or negative error code on failure. + */ int dma_trace_init_complete(struct dma_trace_data *d); + +/** + * \brief Configure the host-side destination scatter-gather buffer for DMA trace. + * \ingroup trace_logging_api + * @param[in,out] d DMA trace data context. + * @param[in] elem_array Array of scatter-gather buffer page elements. + * @param[in] host_size Total size in bytes of the host buffer. + * @return 0 on success, or negative error code on failure. + */ int dma_trace_host_buffer(struct dma_trace_data *d, struct dma_sg_elem_array *elem_array, uint32_t host_size); + +/** + * \brief Enable DMA trace streaming to the host. + * \ingroup trace_logging_api + * @param[in,out] d DMA trace data context. + * @return 0 on success, or negative error code on failure. + */ int dma_trace_enable(struct dma_trace_data *d); + +/** + * \brief Disable DMA trace streaming and cancel pending periodic tasks. + * \ingroup trace_logging_api + * @param[in,out] d DMA trace data context. + */ void dma_trace_disable(struct dma_trace_data *d); + +/** + * \brief Flush residual trace data from local DSP buffer to destination memory or mailbox. + * \ingroup trace_logging_api + * @param[out] destination Pointer to destination memory buffer, or NULL for default mailbox. + */ void dma_trace_flush(void *destination); + +/** + * \brief Globally unpause and resume trace event logging. + * \ingroup trace_logging_api + */ void dma_trace_on(void); + +/** + * \brief Globally pause trace event logging. + * \ingroup trace_logging_api + */ void dma_trace_off(void); +/** + * \brief Append a binary trace event to the circular buffer. + * \ingroup trace_logging_api + * @param[in] e Pointer to binary event packet. + * @param[in] size Packet size in bytes. + */ void dtrace_event(const char *e, uint32_t size); + +/** + * \brief Append a binary trace event to the buffer from atomic or interrupt context. + * \ingroup trace_logging_api + * @param[in] e Pointer to binary event packet. + * @param[in] length Size of packet in bytes. + */ void dtrace_event_atomic(const char *e, uint32_t length); +/** + * \brief Check whether DMA trace subsystem has been initialized. + * \ingroup trace_logging_api + * @param[in] d DMA trace context. + * @return True if initialized with valid buffer memory, false otherwise. + */ static inline bool dma_trace_initialized(const struct dma_trace_data *d) { return d && d->dmatb.addr; } +/** + * \brief Retrieve global DMA trace data context from system runtime. + * \ingroup trace_logging_api + * @return Pointer to struct dma_trace_data. + */ static inline struct dma_trace_data *dma_trace_data_get(void) { return sof_get()->dmat; } +/** + * \brief Calculate contiguous bytes remaining until the end of the circular buffer. + * \ingroup trace_logging_api + * @param[in] buffer Pointer to circular trace buffer descriptor. + * @return Contiguous byte margin before write wrap-around. + */ static inline uint32_t dtrace_calc_buf_margin(struct dma_trace_buf *buffer) { return (char *)buffer->end_addr - (char *)buffer->w_ptr; diff --git a/src/include/sof/trace/trace-boot.h b/src/include/sof/trace/trace-boot.h index abb2e9e4ddb3..c4ff333a4a01 100644 --- a/src/include/sof/trace/trace-boot.h +++ b/src/include/sof/trace/trace-boot.h @@ -3,52 +3,72 @@ * Copyright(c) 2016,2024 Intel Corporation. */ +/** + * \file include/sof/trace/trace-boot.h + * \brief Early bootloader, architecture, and peripheral initialization trace checkpoint codes. + * \ingroup trace_logging_api + */ + #ifndef __SOF_TRACE_TRACE_BOOT_H__ #define __SOF_TRACE_TRACE_BOOT_H__ -/* bootloader trace values */ -#define TRACE_BOOT_LDR_ENTRY 0x100 -#define TRACE_BOOT_LDR_HPSRAM 0x110 -#define TRACE_BOOT_LDR_MANIFEST 0x120 -#define TRACE_BOOT_LDR_LPSRAM 0x130 -#define TRACE_BOOT_LDR_L1DRAM 0x140 -#define TRACE_BOOT_LDR_JUMP 0x150 +/** \name Bootloader Phase Trace Codes + * Checkpoint values written during bootloader stage before OS handoff. + * @{ + */ +#define TRACE_BOOT_LDR_ENTRY 0x100 /**< Bootloader entry point reached */ +#define TRACE_BOOT_LDR_HPSRAM 0x110 /**< High-Performance SRAM powered and configured */ +#define TRACE_BOOT_LDR_MANIFEST 0x120 /**< Firmware manifest signature verified */ +#define TRACE_BOOT_LDR_LPSRAM 0x130 /**< Low-Power SRAM initialized */ +#define TRACE_BOOT_LDR_L1DRAM 0x140 /**< L1 data RAM configured */ +#define TRACE_BOOT_LDR_JUMP 0x150 /**< Branch to main firmware image entry */ + +#define TRACE_BOOT_LDR_PARSE_MODULE 0x210 /**< Parsing firmware module header */ +#define TRACE_BOOT_LDR_PARSE_SEGMENT 0x220 /**< Loading firmware code/data segment */ +/** @} */ -#define TRACE_BOOT_LDR_PARSE_MODULE 0x210 -#define TRACE_BOOT_LDR_PARSE_SEGMENT 0x220 +/** \name General Subsystem Boot Trace Codes + * Major stage markers written to hardware registers during early bootstrap. + * @{ + */ +#define TRACE_BOOT_START 0x1000 /**< SOF firmware execution started */ +#define TRACE_BOOT_ARCH 0x2000 /**< Architecture-level setup started */ +#define TRACE_BOOT_SYS 0x3000 /**< Core system services initialization */ +#define TRACE_BOOT_PLATFORM 0x4000 /**< Platform and peripheral device setup */ +/** @} */ + +/** \name System Services Boot Codes + * Checkpoint codes for core OS and runtime services. + * @{ + */ +#define TRACE_BOOT_SYS_HEAP (TRACE_BOOT_SYS + 0x100) /**< Memory heaps initialized */ +#define TRACE_BOOT_SYS_TRACES (TRACE_BOOT_SYS + 0x200) /**< Early trace subsystem ready */ +#define TRACE_BOOT_SYS_NOTIFIER (TRACE_BOOT_SYS + 0x300) /**< System notification dispatcher initialized */ +#define TRACE_BOOT_SYS_POWER (TRACE_BOOT_SYS + 0x400) /**< Power management framework initialized */ +/** @} */ -/* general trace init codes - only used at boot - * when main trace is not available +/** \name Platform & Hardware Driver Boot Codes + * Detailed peripheral driver checkpoint codes. + * @{ */ -#define TRACE_BOOT_START 0x1000 -#define TRACE_BOOT_ARCH 0x2000 -#define TRACE_BOOT_SYS 0x3000 -#define TRACE_BOOT_PLATFORM 0x4000 - -/* system specific codes */ -#define TRACE_BOOT_SYS_HEAP (TRACE_BOOT_SYS + 0x100) -#define TRACE_BOOT_SYS_TRACES (TRACE_BOOT_SYS + 0x200) -#define TRACE_BOOT_SYS_NOTIFIER (TRACE_BOOT_SYS + 0x300) -#define TRACE_BOOT_SYS_POWER (TRACE_BOOT_SYS + 0x400) - -/* platform/device specific codes */ -#define TRACE_BOOT_PLATFORM_ENTRY (TRACE_BOOT_PLATFORM + 0x100) -#define TRACE_BOOT_PLATFORM_IRQ (TRACE_BOOT_PLATFORM + 0x110) -#define TRACE_BOOT_PLATFORM_MBOX (TRACE_BOOT_PLATFORM + 0x120) -#define TRACE_BOOT_PLATFORM_SHIM (TRACE_BOOT_PLATFORM + 0x130) -#define TRACE_BOOT_PLATFORM_PMC (TRACE_BOOT_PLATFORM + 0x140) -#define TRACE_BOOT_PLATFORM_TIMER (TRACE_BOOT_PLATFORM + 0x150) -#define TRACE_BOOT_PLATFORM_CLOCK (TRACE_BOOT_PLATFORM + 0x160) -#define TRACE_BOOT_PLATFORM_SCHED (TRACE_BOOT_PLATFORM + 0x170) -#define TRACE_BOOT_PLATFORM_AGENT (TRACE_BOOT_PLATFORM + 0x180) -#define TRACE_BOOT_PLATFORM_CPU_FREQ (TRACE_BOOT_PLATFORM + 0x190) -#define TRACE_BOOT_PLATFORM_SSP_FREQ (TRACE_BOOT_PLATFORM + 0x1A0) -#define TRACE_BOOT_PLATFORM_DMA (TRACE_BOOT_PLATFORM + 0x1B0) -#define TRACE_BOOT_PLATFORM_IPC (TRACE_BOOT_PLATFORM + 0x1C0) -#define TRACE_BOOT_PLATFORM_IDC (TRACE_BOOT_PLATFORM + 0x1D0) -#define TRACE_BOOT_PLATFORM_DAI (TRACE_BOOT_PLATFORM + 0x1E0) -#define TRACE_BOOT_PLATFORM_SSP (TRACE_BOOT_PLATFORM + 0x1F0) -#define TRACE_BOOT_PLATFORM_SPI (TRACE_BOOT_PLATFORM + 0x200) -#define TRACE_BOOT_PLATFORM_DMA_TRACE (TRACE_BOOT_PLATFORM + 0x210) +#define TRACE_BOOT_PLATFORM_ENTRY (TRACE_BOOT_PLATFORM + 0x100) /**< Entering platform hardware init */ +#define TRACE_BOOT_PLATFORM_IRQ (TRACE_BOOT_PLATFORM + 0x110) /**< Interrupt controller configured */ +#define TRACE_BOOT_PLATFORM_MBOX (TRACE_BOOT_PLATFORM + 0x120) /**< Shared SRAM mailboxes mapped */ +#define TRACE_BOOT_PLATFORM_SHIM (TRACE_BOOT_PLATFORM + 0x130) /**< Hardware SHIM registers initialized */ +#define TRACE_BOOT_PLATFORM_PMC (TRACE_BOOT_PLATFORM + 0x140) /**< Power Management Controller linked */ +#define TRACE_BOOT_PLATFORM_TIMER (TRACE_BOOT_PLATFORM + 0x150) /**< Hardware timers and sys ticks initialized */ +#define TRACE_BOOT_PLATFORM_CLOCK (TRACE_BOOT_PLATFORM + 0x160) /**< DSP clocks and PLL configured */ +#define TRACE_BOOT_PLATFORM_SCHED (TRACE_BOOT_PLATFORM + 0x170) /**< Real-time scheduler registered */ +#define TRACE_BOOT_PLATFORM_AGENT (TRACE_BOOT_PLATFORM + 0x180) /**< System agent watchdog active */ +#define TRACE_BOOT_PLATFORM_CPU_FREQ (TRACE_BOOT_PLATFORM + 0x190) /**< CPU frequency scaling configured */ +#define TRACE_BOOT_PLATFORM_SSP_FREQ (TRACE_BOOT_PLATFORM + 0x1A0) /**< SSP serial port clocks configured */ +#define TRACE_BOOT_PLATFORM_DMA (TRACE_BOOT_PLATFORM + 0x1B0) /**< DMA controllers probed */ +#define TRACE_BOOT_PLATFORM_IPC (TRACE_BOOT_PLATFORM + 0x1C0) /**< Host IPC transport initialized */ +#define TRACE_BOOT_PLATFORM_IDC (TRACE_BOOT_PLATFORM + 0x1D0) /**< Inter-DSP Communication initialized */ +#define TRACE_BOOT_PLATFORM_DAI (TRACE_BOOT_PLATFORM + 0x1E0) /**< Digital audio interfaces initialized */ +#define TRACE_BOOT_PLATFORM_SSP (TRACE_BOOT_PLATFORM + 0x1F0) /**< SSP/I2S hardware ready */ +#define TRACE_BOOT_PLATFORM_SPI (TRACE_BOOT_PLATFORM + 0x200) /**< SPI hardware ready */ +#define TRACE_BOOT_PLATFORM_DMA_TRACE (TRACE_BOOT_PLATFORM + 0x210) /**< Host DMA trace worker active */ +/** @} */ #endif /* __SOF_TRACE_TRACE_BOOT_H__ */ diff --git a/src/include/sof/trace/trace-soflogger.h b/src/include/sof/trace/trace-soflogger.h index c357239555ef..b8b46a0f4dab 100644 --- a/src/include/sof/trace/trace-soflogger.h +++ b/src/include/sof/trace/trace-soflogger.h @@ -3,6 +3,12 @@ * Copyright(c) 2016,2024 Intel Corporation. */ +/** + * \file include/sof/trace/trace-soflogger.h + * \brief Dictionary-based trace logging engine, log filtering, and mailbox trace fallback. + * \ingroup trace_logging_api + */ + #ifndef __SOF_TRACE_TRACE_SOFLOGGER_H__ #define __SOF_TRACE_TRACE_SOFLOGGER_H__ @@ -18,11 +24,15 @@ struct sof; struct trace; struct tr_ctx; +/** + * \brief Runtime trace filter criteria for components and pipelines. + * \ingroup trace_logging_api + */ struct trace_filter { - uint32_t uuid_id; /**< type id, or 0 when not important */ - int32_t comp_id; /**< component id or -1 when not important */ - int32_t pipe_id; /**< pipeline id or -1 when not important */ - int32_t log_level; /**< new log level value */ + uint32_t uuid_id; /**< Component UUID type identifier, or 0 for wildcard */ + int32_t comp_id; /**< Component ID, or -1 for wildcard */ + int32_t pipe_id; /**< Pipeline ID, or -1 for wildcard */ + int32_t log_level; /**< Target log level threshold (LOG_LEVEL_*) */ }; /** The start of this linker output MUST match the 'ldc_entry_header' @@ -52,6 +62,11 @@ struct trace_filter { #define _TRACE_EVENT_MAX_ARGUMENT_COUNT 4 +/** + * \brief Retrieve global trace subsystem context from SOF runtime. + * \ingroup trace_logging_api + * @return Pointer to struct trace. + */ static inline struct trace *trace_get(void) { return sof_get()->trace; @@ -101,22 +116,94 @@ static inline struct trace *trace_get(void) ctx, id_1, id_2, \ format, ##__VA_ARGS__) +/** + * \brief Flush buffered trace data from DMA buffer to Mailbox Window. + * \ingroup trace_logging_api + */ void trace_flush_dma_to_mbox(void); + +/** + * \brief Globally resume trace event logging. + * \ingroup trace_logging_api + */ void trace_on(void); + +/** + * \brief Globally pause trace event logging. + * \ingroup trace_logging_api + */ void trace_off(void); + +/** + * \brief Initialize the trace subsystem and allocate global trace buffers. + * \ingroup trace_logging_api + * @param[in,out] sof Global SOF runtime context. + */ void trace_init(struct sof *sof); -/* All tracing macros in this file end up calling these functions in the end. */ +/** + * \brief Function pointer type for formatted trace logger backends. + * \ingroup trace_logging_api + * @param[in] send_atomic True if logging from atomic or interrupt context. + * @param[in] log_entry Pointer to static log entry descriptor. + * @param[in] ctx Pointer to caller trace context. + * @param[in] lvl Severity log level (LOG_LEVEL_*). + * @param[in] id_1 Primary component/pipe identifier. + * @param[in] id_2 Secondary component/subid identifier. + * @param[in] arg_count Number of variable arguments. + * @param[in] args Variable arguments list. + */ typedef void (*log_func_t)(bool send_atomic, const void *log_entry, const struct tr_ctx *ctx, uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, va_list args); +/** + * \brief Emit a filtered dictionary trace message. + * \ingroup trace_logging_api + * @param[in] send_atomic True if logging from atomic context. + * @param[in] log_entry Pointer to static log entry. + * @param[in] ctx Trace context. + * @param[in] lvl Log level. + * @param[in] id_1 Primary identifier. + * @param[in] id_2 Secondary identifier. + * @param[in] arg_count Argument count. + * @param[in] args Argument list. + */ void trace_log_filtered(bool send_atomic, const void *log_entry, const struct tr_ctx *ctx, uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, va_list args); + +/** + * \brief Emit an unfiltered dictionary trace message directly to buffers. + * \ingroup trace_logging_api + * @param[in] send_atomic True if logging from atomic context. + * @param[in] log_entry Pointer to static log entry. + * @param[in] ctx Trace context. + * @param[in] lvl Log level. + * @param[in] id_1 Primary identifier. + * @param[in] id_2 Secondary identifier. + * @param[in] arg_count Argument count. + * @param[in] args Argument list. + */ void trace_log_unfiltered(bool send_atomic, const void *log_entry, const struct tr_ctx *ctx, uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, va_list args); + +/** + * \brief Populate an IPC trace filter element array. + * \ingroup trace_logging_api + * @param[in,out] elem Pointer to current output filter element. + * @param[in] end Boundary pointer of element array. + * @param[in] filter Source trace filter configuration. + * @return Pointer to next available filter element slot. + */ struct sof_ipc_trace_filter_elem *trace_filter_fill(struct sof_ipc_trace_filter_elem *elem, struct sof_ipc_trace_filter_elem *end, struct trace_filter *filter); + +/** + * \brief Update runtime trace filtering configuration from IPC payload. + * \ingroup trace_logging_api + * @param[in] elem Trace filter descriptor to apply. + * @return 0 on success, or negative error code on failure. + */ int trace_filter_update(const struct trace_filter *elem); #define _trace_event_with_ids(lvl, class, ctx, id_1, id_2, format, ...) \ @@ -126,17 +213,20 @@ int trace_filter_update(const struct trace_filter *elem); _log_message(trace_log_filtered, true, lvl, class, ctx, id_1, id_2, format, ##__VA_ARGS__) /** - * Appends one SOF dictionary entry and log statement to the ring buffer - * implementing the 'etrace' in shared memory. - * + * \brief Appends one SOF dictionary entry and log statement to shared memory mtrace. + * \ingroup trace_logging_api * @param atomic_context Take the trace->lock if false. - * @param log_entry_pointer dictionary index produced by the - * _DECLARE_LOG_ENTRY macro. - * @param n_args number of va_args + * @param log_entry_pointer Dictionary index produced by _DECLARE_LOG_ENTRY macro. + * @param n_args Number of variable arguments. */ void mtrace_dict_entry(bool atomic_context, uint32_t log_entry_pointer, int n_args, ...); -/** Posts a fully prepared log header + log entry */ +/** + * \brief Posts a fully prepared log header and log entry packet to mtrace buffer. + * \ingroup trace_logging_api + * @param complete_packet Pointer to prepared log packet buffer. + * @param length Packet size in bytes. + */ void mtrace_event(const char *complete_packet, uint32_t length); #ifdef CONFIG_TRACEM /* Send everything to shared memory too */ @@ -152,7 +242,18 @@ void mtrace_event(const char *complete_packet, uint32_t length); # define MTRACE_DUPLICATION_LEVEL LOG_LEVEL_ERROR #endif /* CONFIG_TRACEM */ -/* This function is _not_ passed the format string to save space */ +/** + * \brief Internal dictionary logger formatting and dispatch helper. + * \ingroup trace_logging_api + * @param sofdict_logf Backend log emission callback function. + * @param atomic True if executed in atomic context. + * @param log_entry Pointer to static log entry. + * @param ctx Trace context. + * @param lvl Log severity level. + * @param id_1 Primary identifier. + * @param id_2 Secondary identifier. + * @param arg_count Number of format arguments. + */ void _log_sofdict(log_func_t sofdict_logf, bool atomic, const void *log_entry, const struct tr_ctx *ctx, const uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, ...); diff --git a/src/include/user/debug_stream.h b/src/include/user/debug_stream.h index b6d8c08cf43a..6f350fbf9ea5 100644 --- a/src/include/user/debug_stream.h +++ b/src/include/user/debug_stream.h @@ -3,51 +3,45 @@ * Copyright(c) 2024 Intel Corporation. */ +/** + * \file include/user/debug_stream.h + * \brief User-space ABI stream protocol for passing abstract debug data objects to host. + * \ingroup debug_stream_api + */ + #ifndef __SOC_DEBUG_STREAM_H__ #define __SOC_DEBUG_STREAM_H__ -/* - * Debug Stream is a stream protocol for passing real-time debug - * information from SOF system. It provides the framework for - * passing pieces of abstract data objects from DSP side to host side - * debugging tools. - * - * The details of Debug Stream protocol varies depending on transfer - * method, but the stream should always start with a header that - * consists of DEBUG_STREAM_IDENTIFIER and header size. - */ - -#define DEBUG_STREAM_IDENTIFIER 0x1ED15EED /* value for 'magic' */ +/** Magic identifier at start of Debug Stream header (0x1ED15EED) */ +#define DEBUG_STREAM_IDENTIFIER 0x1ED15EED +/** + * \brief Stream preamble header recognized by host debug tools. + * \ingroup debug_stream_api + */ struct debug_stream_hdr { - uint32_t magic; /* Magic number to recognize stream start */ - uint32_t hdr_size; /* Header size */ + uint32_t magic; /**< Magic identifier (DEBUG_STREAM_IDENTIFIER) */ + uint32_t hdr_size; /**< Total size of stream header in bytes */ } __packed; -/* - * After the header ('hdr_size' bytes from beginning of 'magic') a - * stream of Debug Stream records should follow. Each record will - * start with a record identifier and record size, after which the - * record payload will follow. - * - * The abstract data is application specific and is passed from DSP - * debug entity to user space debug tool for decoding and - * presentation. The data is recognized by the 'id' and the 'size_words' - * describes the amount of data. The 'seqno' is a running number of sent - * record, increased by one after each record. The protocol is - * agnostic about the contents of the records. +/** + * \brief Abstract debug record envelope carrying application-specific payloads. + * \ingroup debug_stream_api */ - struct debug_stream_record { - uint32_t id; /* Record id of abstract data record */ - uint32_t seqno; /* Increments after each record */ - uint32_t size_words; /* Size of the whole record in words */ - uint32_t data[]; + uint32_t id; /**< Record identifier (DEBUG_STREAM_RECORD_ID_*) */ + uint32_t seqno; /**< Monotonically increasing sequence number */ + uint32_t size_words; /**< Total size of the record including header in 32-bit words */ + uint32_t data[]; /**< Application-specific record payload */ } __packed; -/* Debug Stream record identifiers */ -#define DEBUG_STREAM_RECORD_ID_UNINITIALIZED 0 /* invalid record marker */ -#define DEBUG_STREAM_RECORD_ID_THREAD_INFO 1 /* Thread info record */ -#define DEBUG_STREAM_RECORD_ID_TEXT_MSG 2 /* Text message */ +/** \name Debug Stream Record Identifiers + * Payload classification types for abstract debug stream records. + * @{ + */ +#define DEBUG_STREAM_RECORD_ID_UNINITIALIZED 0 /**< Invalid or uninitialized record marker */ +#define DEBUG_STREAM_RECORD_ID_THREAD_INFO 1 /**< DSP RTOS thread state snapshot record */ +#define DEBUG_STREAM_RECORD_ID_TEXT_MSG 2 /**< Formatted ASCII/UTF-8 debug text message record */ +/** @} */ #endif /* __SOC_DEBUG_STREAM_H__ */ diff --git a/src/include/user/debug_stream_slot.h b/src/include/user/debug_stream_slot.h index 926b7f9634c8..5eaae22115b5 100644 --- a/src/include/user/debug_stream_slot.h +++ b/src/include/user/debug_stream_slot.h @@ -3,6 +3,12 @@ * Copyright(c) 2024 Intel Corporation. */ +/** + * \file include/user/debug_stream_slot.h + * \brief SRAM Memory Window 2 Debug Slot mapping and per-core circular buffers. + * \ingroup debug_stream_api + */ + #ifndef __SOC_DEBUG_WINDOW_SLOT_H__ #define __SOC_DEBUG_WINDOW_SLOT_H__ @@ -85,47 +91,50 @@ #include -/* Core specific section descriptor +/** + * \brief Core-specific section descriptor within the debug window slot. + * \ingroup debug_stream_api * - * Section descriptor defines core ID, offset and size of the circular - * buffer in the debug window slot. + * Each descriptor maps a core-specific circular buffer inside Memory Window 2. + * The `offset` field defines the byte offset from the start of `debug_stream_slot_hdr` + * to the core's `debug_stream_circular_buf` structure (aligned to cache line and 4-byte + * word boundaries). The `buf_words` field defines the capacity of the circular buffer + * `data[]` array in 32-bit words. */ 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 */ + uint32_t core_id; /**< Reporting DSP core identifier */ + uint32_t buf_words; /**< Circular buffer data capacity in 32-bit words */ + uint32_t offset; /**< Byte offset from slot base (4-byte aligned) */ } __packed; -/* Debug window slot header for Debug Stream. - * - * The header should be written in the beginning of the slot. +/** + * \brief Preamble header placed at the beginning of Memory Window 2 Debug Slot. + * \ingroup debug_stream_api */ 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[]; + struct debug_stream_hdr hdr; /**< Base stream identifier and size */ + uint32_t total_size; /**< Total size of payload across all core sections */ + uint32_t num_sections; /**< Number of active core-specific sections */ + struct debug_stream_section_descriptor section_desc[]; /**< Array of per-core section descriptors */ } __packed; +/** + * \brief Per-core circular buffer layout within a debug stream slot. + * \ingroup debug_stream_api + */ struct debug_stream_circular_buf { - uint32_t next_seqno; - uint32_t w_ptr; - uint32_t data[]; + uint32_t next_seqno; /**< Sequence counter of next record to write */ + uint32_t w_ptr; /**< Current write position in 32-bit words */ + uint32_t data[]; /**< Circular data buffer holding stream records */ } __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 + * \brief Send a debug stream record over the memory window debug slot. + * \ingroup debug_stream_api + * @param[in] rec Pointer to abstract debug stream record to transmit. + * @return 0 on success, -ENODEV if debug slot is unconfigured, or -ENOMEM if record exceeds capacity. */ __syscall int debug_stream_slot_send_record(struct debug_stream_record *rec); diff --git a/src/include/user/debug_stream_text_msg.h b/src/include/user/debug_stream_text_msg.h index debfaad7042e..cd6341fa865e 100644 --- a/src/include/user/debug_stream_text_msg.h +++ b/src/include/user/debug_stream_text_msg.h @@ -3,25 +3,47 @@ * Copyright(c) 2024 Intel Corporation. */ +/** + * \file include/user/debug_stream_text_msg.h + * \brief Text message records transmitted over the debug stream. + * \ingroup debug_stream_api + */ + #ifndef __SOC_DEBUG_STREAM_TEXT_MSG_H__ #define __SOC_DEBUG_STREAM_TEXT_MSG_H__ #include #include -/* - * Debug Stream text message. +/** + * \brief Formatted text message record within a debug stream. + * \ingroup debug_stream_api + * + * The record payload is length-delimited by `hdr.size_words`. The text data in `msg[]` + * is ASCII/UTF-8 encoded and padded with trailing NUL bytes to a 32-bit word boundary. + * Receivers should calculate maximum payload capacity as + * `(hdr.size_words * sizeof(uint32_t) - sizeof(struct debug_stream_record))` and stop + * parsing at either the capacity limit or the first internal NUL terminator. */ struct debug_stream_text_msg { - struct debug_stream_record hdr; - char msg[]; + struct debug_stream_record hdr; /**< Stream record header specifying size_words */ + char msg[]; /**< Length-delimited text message, padded to 32-bit boundary */ } __packed; -/* - * To send debug messages over debug stream. Enable - * CONFIG_SOF_DEBUG_STREAM_TEXT_MSG to enable this function. +/** + * \brief Format and transmit a text message record over the active debug stream slot. + * \ingroup debug_stream_api + * @param[in] format Printf-style format string. + * @param[in] ... Variable arguments matching format. */ void ds_msg(const char *format, ...); + +/** + * \brief Transmit a text message record over debug stream using va_list arguments. + * \ingroup debug_stream_api + * @param[in] format Printf-style format string. + * @param[in] ap Variable arguments list. + */ void ds_vamsg(const char *format, va_list ap); -#endif /* __SOC_DEBUG_STREAM_TEXT_MSG_H__ */ +#endif /* __SOC_DEBUG_STREAM_TEXT_MSG_H__ */ diff --git a/src/include/user/trace.h b/src/include/user/trace.h index 6550a91ba6ee..a097976bdba3 100644 --- a/src/include/user/trace.h +++ b/src/include/user/trace.h @@ -6,40 +6,54 @@ * Artur Kloniecki */ +/** + * \file include/user/trace.h + * \brief User-space ABI log levels and binary trace packet header definitions. + * \ingroup trace_logging_api + */ + #ifndef __USER_TRACE_H__ #define __USER_TRACE_H__ #include -/* trace event classes - high 8 bits*/ +/** Legacy trace event class (deprecated) */ #define TRACE_CLASS_DEPRECATED (0) -#define LOG_ENABLE 1 /* Enable logging */ -#define LOG_DISABLE 0 /* Disable logging */ - -#define LOG_LEVEL_CRITICAL 1 /* (FDK fatal) */ -#define LOG_LEVEL_ERROR LOG_LEVEL_CRITICAL -#define LOG_LEVEL_WARNING 2 -#define LOG_LEVEL_INFO 3 -#define LOG_LEVEL_DEBUG 4 -#define LOG_LEVEL_VERBOSE LOG_LEVEL_DEBUG +#define LOG_ENABLE 1 /**< Enable active logging */ +#define LOG_DISABLE 0 /**< Disable logging */ -#define TRACE_ID_LENGTH 12 /* bit field length */ - -/* - * Log entry protocol header. +/** \name Logging Severity Levels + * Severity ranking for runtime message filtering. + * @{ + */ +#define LOG_LEVEL_CRITICAL 1 /**< Critical failure or unrecoverable error (fatal) */ +#define LOG_LEVEL_ERROR LOG_LEVEL_CRITICAL /**< Alias for critical errors */ +#define LOG_LEVEL_WARNING 2 /**< Warning conditions requiring attention */ +#define LOG_LEVEL_INFO 3 /**< Normal informational operational messages */ +#define LOG_LEVEL_DEBUG 4 /**< Detailed debug logging */ +#define LOG_LEVEL_VERBOSE LOG_LEVEL_DEBUG /**< Verbose debug logging */ +/** @} */ + +/** Bitfield width of component and pipeline trace identifiers */ +#define TRACE_ID_LENGTH 12 + +/** + * \brief Binary log packet header preceding variable arguments in DMA trace stream. + * \ingroup trace_logging_api * - * The header is followed by an array of arguments (uint32_t[]). - * Number of arguments is specified by the params_num field of log_entry + * Each dictionary log packet in the DMA buffer begins with this header, followed + * by up to 4 parameters (uint32_t values) matching the format string referenced + * by log_entry_address in the ELF dictionary (.ldc). */ struct log_entry_header { - uint32_t uid; - uint32_t id_0 : TRACE_ID_LENGTH; /* e.g. Pipeline ID */ - uint32_t id_1 : TRACE_ID_LENGTH; /* e.g. Component ID */ - uint32_t core_id : 8; /* Reporting core's id */ + uint32_t uid; /**< Unique log entry sequence number */ + uint32_t id_0 : TRACE_ID_LENGTH; /**< Primary identifier (e.g. Pipeline ID) */ + uint32_t id_1 : TRACE_ID_LENGTH; /**< Secondary identifier (e.g. Component ID) */ + uint32_t core_id : 8; /**< Reporting DSP core identifier */ - uint64_t timestamp; /* Timestamp (in dsp ticks) */ - uint32_t log_entry_address; /* Address of log entry in ELF */ + uint64_t timestamp; /**< High-resolution hardware clock timestamp in DSP ticks */ + uint32_t log_entry_address; /**< Linker address of static log entry descriptor in firmware ELF */ } __attribute__((packed)); #endif /* __USER_TRACE_H__ */