From e004d79ae3421183775f4156ff6ab252c56d9c5f Mon Sep 17 00:00:00 2001 From: Seppo Ingalsuo Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 01/31] audio: buffers/ipc4: add DP-to-DP component binding Add CONFIG_DP_TO_DP_BIND to allow connecting two Data Processing (DP) scheduled modules directly via a shared ring_buffer attached on both sides of the intermediate comp_buffer without LL-cycle copying. - Retain a vregion reference on the shared ring_buffer in ipc4_comp_connect() and drop it on ring_buffer_free(). - Guard NULL module_data pointers in ipc4_comp_connect() for non-module components such as copiers. - Include explicitly in zephyr/lib/vregion.c for non-LLEXT static builds. Signed-off-by: Seppo Ingalsuo Co-authored-by: Liam Girdwood Signed-off-by: Liam Girdwood --- src/audio/buffers/audio_buffer.c | 44 +++++++++++++----- src/audio/buffers/ring_buffer.c | 14 +++++- src/include/sof/audio/audio_buffer.h | 7 +++ src/ipc/ipc4/helper.c | 67 ++++++++++++++++++++-------- zephyr/Kconfig | 9 ++++ zephyr/lib/vregion.c | 1 + 6 files changed, 112 insertions(+), 30 deletions(-) diff --git a/src/audio/buffers/audio_buffer.c b/src/audio/buffers/audio_buffer.c index 1ecf8472dd65..0b0b22a191fe 100644 --- a/src/audio/buffers/audio_buffer.c +++ b/src/audio/buffers/audio_buffer.c @@ -24,8 +24,16 @@ int audio_buffer_attach_secondary_buffer(struct sof_audio_buffer *buffer, bool at_input, struct sof_audio_buffer *secondary_buffer) { +#ifdef CONFIG_DP_TO_DP_BIND + /* check per-side: allow attaching on both sides (needed for DP-to-DP) */ + if (at_input && buffer->secondary_buffer_sink) + return -EINVAL; + if (!at_input && buffer->secondary_buffer_source) + return -EINVAL; +#else if (buffer->secondary_buffer_sink || buffer->secondary_buffer_source) return -EINVAL; +#endif /* secondary buffer must share audio params with the primary buffer */ secondary_buffer->audio_stream_params = buffer->audio_stream_params; @@ -48,6 +56,19 @@ int audio_buffer_sync_secondary_buffer(struct sof_audio_buffer *buffer, size_t l struct sof_source *data_src; struct sof_sink *data_dst; +#ifdef CONFIG_DP_TO_DP_BIND + if (buffer->secondary_buffer_sink && + buffer->secondary_buffer_sink == buffer->secondary_buffer_source) { + /* + * DP-to-DP case: a single shared ring_buffer is attached on both sides. + * The source DP writes directly to the ring_buffer sink API, and the + * sink DP reads directly from the ring_buffer source API. + * No copying is needed during the LL cycle. + */ + return 0; + } +#endif + if (buffer->secondary_buffer_sink) { /* * audio_buffer sink API is shadowed, that means there's a secondary_buffer @@ -95,7 +116,12 @@ void audio_buffer_free(struct sof_audio_buffer *buffer) CORE_CHECK_STRUCT(buffer); #if CONFIG_PIPELINE_2_0 audio_buffer_free(buffer->secondary_buffer_sink); +#ifdef CONFIG_DP_TO_DP_BIND + if (buffer->secondary_buffer_source != buffer->secondary_buffer_sink) + audio_buffer_free(buffer->secondary_buffer_source); +#else audio_buffer_free(buffer->secondary_buffer_source); +#endif #endif /* CONFIG_PIPELINE_2_0 */ /* "virtual destructor": free the buffer internals and buffer memory */ buffer->ops->free(buffer); @@ -203,18 +229,14 @@ uint32_t audio_buffer_sink_get_lft(struct sof_sink *sink) return us_in_buffer; /* - * TODO, Currently there's no DP to DP connection - * >>> the code below is never accessible and won't work because of cache incoherence <<< - * - * to make DP to DP connection possible: + * NOTE: DP-to-DP connections are now supported via a single shared ring_buffer + * attached as secondary buffer on both sides of a comp_buffer. * - * 1) module data must be ALWAYS located in non cached memory alias, allowing - * cross core access to params like period (needed below) and calling - * module_get_deadline for the next module, regardless of cores the modules are - * running on - * 2) comp_buffer must be removed from all pipeline code, replaced with a generic abstract - * class audio_buffer - allowing using comp_buffer and ring_buffer without current - * "hybrid buffer" solution + * Future improvements: + * 1) module data should be in non-cached memory alias for reliable + * cross-core access to params like period and deadlines + * 2) comp_buffer should be replaced with generic audio_buffer + * throughout pipeline code (Pipeline 2.0) */ } diff --git a/src/audio/buffers/ring_buffer.c b/src/audio/buffers/ring_buffer.c index fde594d32424..7803d6d42e96 100644 --- a/src/audio/buffers/ring_buffer.c +++ b/src/audio/buffers/ring_buffer.c @@ -88,7 +88,6 @@ static inline void ring_buffer_writeback_shared(struct ring_buffer *ring_buffer, dcache_writeback_region(ptr, size); } - /** * @brief remove the queue from the list, free memory */ @@ -105,6 +104,19 @@ __cold static void ring_buffer_free(struct sof_audio_buffer *audio_buffer) sof_ctx_free(alloc, (__sparse_force void *)ring_buffer->_data_buffer); sof_ctx_free(alloc, ring_buffer); + +#ifdef CONFIG_DP_TO_DP_BIND + /* + * When CONFIG_DP_TO_DP_BIND is enabled, ipc_comp_connect() takes an extra vregion + * reference for each ring_buffer created from a module vregion. Drop that + * reference here and free the allocation context only when the vregion refcount + * reaches zero. + */ + if (alloc && alloc->vreg) { + if (!vregion_put(alloc->vreg)) + sof_heap_free(alloc->heap, alloc); + } +#endif } static void ring_buffer_reset(struct sof_audio_buffer *audio_buffer) diff --git a/src/include/sof/audio/audio_buffer.h b/src/include/sof/audio/audio_buffer.h index f16a50ccd43d..3f9bca2be124 100644 --- a/src/include/sof/audio/audio_buffer.h +++ b/src/include/sof/audio/audio_buffer.h @@ -368,9 +368,16 @@ void audio_buffer_reset(struct sof_audio_buffer *buffer) if (buffer->secondary_buffer_sink && buffer->secondary_buffer_sink->ops->reset) buffer->secondary_buffer_sink->ops->reset(buffer->secondary_buffer_sink); +#ifdef CONFIG_DP_TO_DP_BIND + if (buffer->secondary_buffer_source && + buffer->secondary_buffer_source != buffer->secondary_buffer_sink && + buffer->secondary_buffer_source->ops->reset) + buffer->secondary_buffer_source->ops->reset(buffer->secondary_buffer_source); +#else if (buffer->secondary_buffer_source && buffer->secondary_buffer_source->ops->reset) buffer->secondary_buffer_source->ops->reset(buffer->secondary_buffer_source); #endif +#endif } /* Audio-buffer wrappers for the source-sink API */ diff --git a/src/ipc/ipc4/helper.c b/src/ipc/ipc4/helper.c index 7932050a7707..063f2e68da80 100644 --- a/src/ipc/ipc4/helper.c +++ b/src/ipc/ipc4/helper.c @@ -772,18 +772,22 @@ __cold int ipc4_comp_connect(struct ipc *ipc, const struct ipc4_module_bind_unbi struct mod_alloc_ctx *alloc; #if CONFIG_ZEPHYR_DP_SCHEDULER - if (source->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_DP && - sink->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_DP) { + bool src_is_dp = source->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_DP; + bool sink_is_dp = sink->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_DP; +#ifdef CONFIG_DP_TO_DP_BIND + bool dp_to_dp = src_is_dp && sink_is_dp; +#else + if (src_is_dp && sink_is_dp) { tr_err(&ipc_tr, "DP to DP binding is not supported: can't bind %x to %x", src_id, sink_id); return IPC4_INVALID_REQUEST; } - +#endif struct comp_dev *dp; - if (sink->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_DP) + if (sink_is_dp) dp = sink; - else if (source->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_DP) + else if (src_is_dp) dp = source; else dp = NULL; @@ -874,8 +878,8 @@ __cold int ipc4_comp_connect(struct ipc *ipc, const struct ipc4_module_bind_unbi * * size = 2*max(obs of source module, ibs of destination module) * (obs and ibs is single buffer size) - * in case of DP -> LL - * size = 2*ibs of destination (LL) module. DP queue will handle obs of DP module + * in case of DP -> LL or DP -> DP + * size = 2*ibs of destination module. DP queue will handle obs of DP module */ if (source->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_LL) buf_size = MAX(ibs, obs) * 2; @@ -910,12 +914,15 @@ __cold int ipc4_comp_connect(struct ipc *ipc, const struct ipc4_module_bind_unbi #if CONFIG_ZEPHYR_DP_SCHEDULER struct ring_buffer *ring_buffer = NULL; - if (sink->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_DP || - source->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_DP) { + if (src_is_dp || sink_is_dp) { struct processing_module *srcmod = comp_mod(source); - struct module_data *src_module_data = &srcmod->priv; + struct module_data *src_module_data = srcmod ? &srcmod->priv : NULL; struct processing_module *dstmod = comp_mod(sink); - struct module_data *dst_module_data = &dstmod->priv; + struct module_data *dst_module_data = dstmod ? &dstmod->priv : NULL; + uint32_t dst_in_buff_size = dst_module_data ? dst_module_data->mpd.in_buff_size : 0; + uint32_t src_out_buff_size = src_module_data ? src_module_data->mpd.out_buff_size : 0; + bool is_shared = audio_buffer_is_shared(&buffer->audio_buffer); + uint32_t buf_id = buf_get_id(buffer); /* * Handle cases where the size of the ring buffer depends on the @@ -925,18 +932,42 @@ __cold int ipc4_comp_connect(struct ipc *ipc, const struct ipc4_module_bind_unbi * is only for the ring buffer. The size of intermediate buffer created above is * unchanged. */ - ring_buffer = ring_buffer_create(dp, MAX(ibs, dst_module_data->mpd.in_buff_size), - MAX(obs, src_module_data->mpd.out_buff_size), - audio_buffer_is_shared(&buffer->audio_buffer), - buf_get_id(buffer)); + ring_buffer = ring_buffer_create(dp, MAX(ibs, dst_in_buff_size), + MAX(obs, src_out_buff_size), + is_shared, buf_id); if (!ring_buffer) { buffer_free(buffer); return IPC4_OUT_OF_MEMORY; } - /* data destination module needs to use ring_buffer */ - audio_buffer_attach_secondary_buffer(&buffer->audio_buffer, dp == source, - &ring_buffer->audio_buffer); +#ifdef CONFIG_DP_TO_DP_BIND + /* + * When CONFIG_DP_TO_DP_BIND is enabled, keep the DP module vregion + * alive for the lifetime of this ring_buffer (dropped in ring_buffer_free()). + */ + if (ring_buffer->audio_buffer.alloc) + vregion_get(ring_buffer->audio_buffer.alloc->vreg); +#endif + +#ifdef CONFIG_DP_TO_DP_BIND + if (dp_to_dp) { + /* + * DP-to-DP binding: both source and sink are DP modules. + * A single shared ring_buffer is attached on both sides + * of the comp_buffer, so source DP writes directly to it + * and sink DP reads directly from it without copying. + */ + audio_buffer_attach_secondary_buffer(&buffer->audio_buffer, true, + &ring_buffer->audio_buffer); + audio_buffer_attach_secondary_buffer(&buffer->audio_buffer, false, + &ring_buffer->audio_buffer); + } else +#endif + { + /* data destination module needs to use ring_buffer */ + audio_buffer_attach_secondary_buffer(&buffer->audio_buffer, dp == source, + &ring_buffer->audio_buffer); + } } #endif /* CONFIG_ZEPHYR_DP_SCHEDULER */ diff --git a/zephyr/Kconfig b/zephyr/Kconfig index d8aa70793b56..999c71c05473 100644 --- a/zephyr/Kconfig +++ b/zephyr/Kconfig @@ -319,6 +319,15 @@ config ZEPHYR_DP_SCHEDULER_MIN_STACK_SIZE ext_init payload. If the stack size requested in the IPC is smaller than this, then the value defined here takes over. +config DP_TO_DP_BIND + bool "Support DP to DP component binding" + default y + depends on ZEPHYR_DP_SCHEDULER + help + Enable binding between two Data Processing (DP) scheduled components. + This allows connecting DP modules together (e.g. DP source to DP sink) + via intermediate buffering. + config CROSS_CORE_STREAM bool "Enable cross-core connected pipelines" default y if IPC_MAJOR_4 diff --git a/zephyr/lib/vregion.c b/zephyr/lib/vregion.c index f245af699d35..bb00b0ac9204 100644 --- a/zephyr/lib/vregion.c +++ b/zephyr/lib/vregion.c @@ -13,6 +13,7 @@ #include #include #include +#include #include #include #include From 1cc2b7c9c01992adc192f2ff3743dadfeba9a0d6 Mon Sep 17 00:00:00 2001 From: Peter Ujfalusi Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 02/31] schedule, platform: use k_mutex for DP lock and init DP scheduler on cAVS Use a k_mutex instead of a k_sem for the per-core DP scheduler lock so priority inheritance prevents a preempted DP lock holder from stalling LL. Initialize the DP scheduler in cAVS platform_init() when CONFIG_ZEPHYR_DP_SCHEDULER is enabled. Signed-off-by: Peter Ujfalusi --- src/include/sof/schedule/zephyr_dp_schedule.h | 2 +- src/kernel/schedule/zephyr_dp_schedule-kernel.c | 5 +++-- src/schedule/zephyr_dp_schedule.c | 4 ++-- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/src/include/sof/schedule/zephyr_dp_schedule.h b/src/include/sof/schedule/zephyr_dp_schedule.h index 582193a6a816..9dd39ede16f7 100644 --- a/src/include/sof/schedule/zephyr_dp_schedule.h +++ b/src/include/sof/schedule/zephyr_dp_schedule.h @@ -130,7 +130,7 @@ struct scheduler_dp_task_memory { #endif /* CONFIG_SOF_USERSPACE_APPLICATION */ /** @brief Per-core DP scheduler locks, see scheduler_dp_lock(). */ -extern struct k_sem dp_lock[CONFIG_MP_MAX_NUM_CPUS]; +extern struct k_mutex dp_lock[CONFIG_MP_MAX_NUM_CPUS]; /** * @brief DP scheduler ops, see struct scheduler_ops. diff --git a/src/kernel/schedule/zephyr_dp_schedule-kernel.c b/src/kernel/schedule/zephyr_dp_schedule-kernel.c index 7f0d7c285d62..da87c3f73ee0 100644 --- a/src/kernel/schedule/zephyr_dp_schedule-kernel.c +++ b/src/kernel/schedule/zephyr_dp_schedule-kernel.c @@ -43,14 +43,15 @@ DECLARE_TR_CTX(dp_tr, SOF_UUID(dp_sched_uuid), LOG_LEVEL_INFO); * src/schedule/zephyr_dp_schedule.c */ -#define DP_LOCK_INIT(i, _) Z_SEM_INITIALIZER(dp_lock[i], 1, 1) +/* k_mutex, not k_sem: priority inheritance keeps a preempted DP holder from stalling LL */ +#define DP_LOCK_INIT(i, _) Z_MUTEX_INITIALIZER(dp_lock[i]) #define DP_LOCK_INIT_LIST LISTIFY(CONFIG_MP_MAX_NUM_CPUS, DP_LOCK_INIT, (,)) /* User threads don't need access to this array. Access is performed from * the kernel space via a syscall. Array must be placed in special section * to be qualified as initialized by the gen_kobject_list.py script. */ -STRUCT_SECTION_ITERABLE_ARRAY(k_sem, dp_lock, CONFIG_MP_MAX_NUM_CPUS) = { DP_LOCK_INIT_LIST }; +STRUCT_SECTION_ITERABLE_ARRAY(k_mutex, dp_lock, CONFIG_MP_MAX_NUM_CPUS) = { DP_LOCK_INIT_LIST }; void scheduler_dp_grant(k_tid_t thread_id, uint16_t core) { diff --git a/src/schedule/zephyr_dp_schedule.c b/src/schedule/zephyr_dp_schedule.c index da34fdadae48..5a00cd2d32c3 100644 --- a/src/schedule/zephyr_dp_schedule.c +++ b/src/schedule/zephyr_dp_schedule.c @@ -41,13 +41,13 @@ extern struct tr_ctx dp_tr; */ unsigned int scheduler_dp_lock(uint16_t core) { - k_sem_take(&dp_lock[core], K_FOREVER); + k_mutex_lock(&dp_lock[core], K_FOREVER); return core; } void scheduler_dp_unlock(unsigned int key) { - k_sem_give(&dp_lock[key]); + k_mutex_unlock(&dp_lock[key]); } #if CONFIG_SOF_USERSPACE_APPLICATION From 8f5b24b486704153b47b0b091f505ce9d9b86b9a Mon Sep 17 00:00:00 2001 From: Seppo Ingalsuo Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 03/31] audio: module_adapter: support virtual detect sink and unset legacy sink params Update module_adapter_prepare() and period calculation for DP WoV modules: - Skip sinks that do not produce audio streams (frame_bytes == 0 or rate == 0, such as phrase-detect event sinks) when calculating DP period. - Propagate mod->stream_params to legacy comp_driver consumers that do not set input buffer parameters at bind time. - Guard sink==NULL period_bytes computation when max_sinks == 0 (single- producer fallback). - Pass SIZE_MAX to audio_buffer_sync_secondary_buffer(). Signed-off-by: Seppo Ingalsuo Co-authored-by: Peter Ujfalusi Signed-off-by: Peter Ujfalusi Co-authored-by: Liam Girdwood Signed-off-by: Liam Girdwood --- src/audio/module_adapter/module_adapter.c | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/src/audio/module_adapter/module_adapter.c b/src/audio/module_adapter/module_adapter.c index b0075453e434..914a13bc9fcb 100644 --- a/src/audio/module_adapter/module_adapter.c +++ b/src/audio/module_adapter/module_adapter.c @@ -413,12 +413,21 @@ static void module_adapter_calculate_dp_period(struct comp_dev *dev) unsigned int period = UINT32_MAX; for (int i = 0; i < mod->num_of_sinks; i++) { + unsigned int frame_bytes = sink_get_frame_bytes(mod->sinks[i]); + unsigned int rate = sink_get_rate(mod->sinks[i]); + + /* Skip sinks that don't produce audio data (e.g. phrase detect + * modules emit events, no rate/frame bytes) to avoid divide by + * zero. The module is expected to set dev->period itself. + */ + if (!frame_bytes || !rate) + continue; + /* calculate time required the module to provide OBS data portion - a period * use 64bit integers to avoid overflows */ unsigned int sink_period = 1000000ULL * sink_get_min_free_space(mod->sinks[i]) / - (sink_get_frame_bytes(mod->sinks[i]) * - sink_get_rate(mod->sinks[i])); + (frame_bytes * rate); /* note the minimal period for the module */ if (period > sink_period) period = sink_period; @@ -484,6 +493,12 @@ int module_adapter_prepare(struct comp_dev *dev) * Second example is a module with variable data rate on output (like MPEG encoder) */ if (mod->dev->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_DP) { + /* legacy comp_driver consumers don't set their input buffer params at bind */ + comp_dev_for_each_consumer(dev, sink) { + if (!audio_stream_get_rate(&sink->stream) && mod->stream_params) + buffer_set_params(sink, mod->stream_params, BUFFER_UPDATE_FORCE); + } + /* calculate DP period if a module didn't */ if (!dev->period) module_adapter_calculate_dp_period(dev); @@ -527,7 +542,6 @@ int module_adapter_prepare(struct comp_dev *dev) * Hence check for NULL. */ sink = comp_dev_get_first_data_consumer(dev); - /* A sinkless module still needs at least one source. */ if (!sink && !comp_dev_get_first_data_producer(dev)) { comp_err(dev, "no source or sink buffer connected"); @@ -595,7 +609,7 @@ static int module_adapter_copy_ring_buffers(struct comp_dev *dev) /* input - we need to copy data from audio_stream (as source) * to ring_buffer (as sink) */ - err = audio_buffer_sync_secondary_buffer(&buffer->audio_buffer, UINT_MAX); + err = audio_buffer_sync_secondary_buffer(&buffer->audio_buffer, SIZE_MAX); if (err) { comp_err(dev, "LL to DP copy error status: %d", err); From 8edfa67474f2d673ad8b72d3e75faa2f0679b3af Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 04/31] pipeline, ipc4: support hostless pipelines and dynamic WOV routing Support hostless pipelines, dynamic WOV routing, and clean EDF task teardown: - Cancel delayed work in schedule_edf_task_free(). - Export pipeline_schedule_cancel() and guard NULL pipe_task checks. - Log failing component ID when pipeline_comp_prepare() fails. - Support hostless pipelines and COMP_STATE_PREPARE handling in IPC4 user-space handler. Signed-off-by: Liam Girdwood --- src/audio/pipeline/pipeline-params.c | 7 +- src/audio/pipeline/pipeline-schedule.c | 7 +- src/include/sof/audio/pipeline.h | 1 + src/ipc/ipc4/handler-user.c | 160 ++++++++++++++++++++++--- zephyr/edf_schedule.c | 1 + 5 files changed, 154 insertions(+), 22 deletions(-) diff --git a/src/audio/pipeline/pipeline-params.c b/src/audio/pipeline/pipeline-params.c index 8a2166b19769..1e40a16174a3 100644 --- a/src/audio/pipeline/pipeline-params.c +++ b/src/audio/pipeline/pipeline-params.c @@ -285,8 +285,13 @@ static int pipeline_comp_prepare(struct comp_dev *current, return err; err = comp_prepare(current); - if (err < 0 || err == PPL_STATUS_PATH_STOP) + if (err < 0 || err == PPL_STATUS_PATH_STOP) { + if (err < 0) { + pipe_err(current->pipeline, "comp_prepare for comp 0x%x failed %d", + dev_comp_id(current), err); + } return err; + } return pipeline_for_each_comp(current, ctx, dir); } diff --git a/src/audio/pipeline/pipeline-schedule.c b/src/audio/pipeline/pipeline-schedule.c index 63b9fd979088..f4d60bbe2a42 100644 --- a/src/audio/pipeline/pipeline-schedule.c +++ b/src/audio/pipeline/pipeline-schedule.c @@ -56,9 +56,10 @@ SOF_DEFINE_REG_UUID(dp_task); #endif /* CONFIG_ZEPHYR_DP_SCHEDULER */ -static void pipeline_schedule_cancel(struct pipeline *p) +void pipeline_schedule_cancel(struct pipeline *p) { - schedule_task_cancel(p->pipe_task); + if (p->pipe_task) + schedule_task_cancel(p->pipe_task); /* enable system agent panic, when there are no longer * DMA driven pipelines @@ -655,7 +656,7 @@ void pipeline_schedule_copy(struct pipeline *p, uint64_t start) * when we attempt to start B, we don't need to schedule pipeline C - * it's already running. */ - if (task_is_active(p->pipe_task)) + if (!p->pipe_task || task_is_active(p->pipe_task)) return; if (p->sched_next && task_is_active(p->sched_next->pipe_task)) diff --git a/src/include/sof/audio/pipeline.h b/src/include/sof/audio/pipeline.h index 9409eaec0236..4068845b61e7 100644 --- a/src/include/sof/audio/pipeline.h +++ b/src/include/sof/audio/pipeline.h @@ -421,6 +421,7 @@ int pipeline_comp_dp_task_init(struct comp_dev *comp); * \param[in] start Pipeline start time in microseconds. */ void pipeline_schedule_copy(struct pipeline *p, uint64_t start); +void pipeline_schedule_cancel(struct pipeline *p); /** * \brief Triggers pipeline's scheduling component. diff --git a/src/ipc/ipc4/handler-user.c b/src/ipc/ipc4/handler-user.c index 232e81800201..40e414299a2d 100644 --- a/src/ipc/ipc4/handler-user.c +++ b/src/ipc/ipc4/handler-user.c @@ -115,16 +115,41 @@ static int ipc4_pcm_params(struct ipc_comp_dev *pcm_dev) return err; } +static struct comp_dev *pipeline_get_endpoint_comp(struct ipc_comp_dev *ppl_icd) +{ + if (!ppl_icd || !ppl_icd->pipeline) + return NULL; + + struct pipeline *p = ppl_icd->pipeline; + + if (p->source_comp && p->source_comp->direction == SOF_IPC_STREAM_PLAYBACK) + return p->source_comp; + + if (p->sink_comp) + return p->sink_comp; + + return p->source_comp; +} + +static bool pipeline_is_endpoint(struct pipeline *p) +{ + return (p->source_comp && (dev_comp_type(p->source_comp) == SOF_COMP_HOST || + dev_comp_type(p->source_comp) == SOF_COMP_DAI)) || + (p->sink_comp && (dev_comp_type(p->sink_comp) == SOF_COMP_HOST || + dev_comp_type(p->sink_comp) == SOF_COMP_DAI)); +} + static struct ipc_comp_dev *pipeline_get_host_dev(struct ipc_comp_dev *ppl_icd) { struct ipc_comp_dev *host_dev; struct ipc *ipc = ipc_get(); int host_id; - if (!ppl_icd->pipeline->source_comp || !ppl_icd->pipeline->sink_comp) { - ipc_cmd_err(&ipc_tr, "pipeline %d: source/sink comp freed", ppl_icd->id); + if (!ppl_icd || !ppl_icd->pipeline) + return NULL; + + if (!ppl_icd->pipeline->source_comp || !ppl_icd->pipeline->sink_comp) return NULL; - } /* If the source component's direction is not set but the sink's direction is, * this block will copy the direction from the sink to the source component and @@ -154,8 +179,8 @@ static struct ipc_comp_dev *pipeline_get_host_dev(struct ipc_comp_dev *ppl_icd) host_id = ppl_icd->pipeline->sink_comp->ipc_config.id; host_dev = ipc_get_comp_by_id(ipc, host_id); - if (!host_dev) - ipc_cmd_err(&ipc_tr, "comp host with ID %d not found", host_id); + if (!host_dev || dev_comp_type(host_dev->cd) != SOF_COMP_HOST) + return NULL; return host_dev; } @@ -210,20 +235,57 @@ int ipc4_pipeline_prepare(struct ipc_comp_dev *ppl_icd, uint32_t cmd) /* init params when pipeline is complete or reset */ switch (status) { + case COMP_STATE_INIT: + tr_dbg(&ipc_tr, "pipeline %d: running from init", ppl_icd->id); + ret = ipc4_pipeline_complete(ipc, ppl_icd->id, cmd); + if (ret < 0) + return IPC4_INVALID_REQUEST; + host = pipeline_get_host_dev(ppl_icd); + if (host) { + ret = ipc4_pcm_params(host); + if (ret < 0) + tr_err(&ipc_tr, "pipeline %d: ipc4_pcm_params failed %d", ppl_icd->id, ret); + } else { + struct comp_dev *cd = pipeline_get_endpoint_comp(ppl_icd); + + if (cd && cd->pipeline) { + ret = pipeline_prepare(cd->pipeline, cd); + if (ret < 0) + tr_err(&ipc_tr, "pipeline %d: prepare failed %d", ppl_icd->id, ret); + else + ret = 0; + } + } + break; case COMP_STATE_ACTIVE: case COMP_STATE_PAUSED: + case COMP_STATE_PREPARE: + case COMP_STATE_PRE_ACTIVE: + case COMP_STATE_SUSPEND: /* No action needed */ break; case COMP_STATE_READY: host = pipeline_get_host_dev(ppl_icd); - if (!host) - return IPC4_INVALID_RESOURCE_ID; - - tr_dbg(&ipc_tr, "pipeline %d: set params", ppl_icd->id); - ret = ipc4_pcm_params(host); + if (host) { + tr_info(&ipc_tr, "pipeline %d: set params host comp 0x%x", ppl_icd->id, host->id); + ret = ipc4_pcm_params(host); + if (ret < 0) { + tr_err(&ipc_tr, "pipeline %d: ipc4_pcm_params failed %d", ppl_icd->id, ret); + } + } else { + struct comp_dev *cd = pipeline_get_endpoint_comp(ppl_icd); + + if (cd && cd->pipeline) { + ret = pipeline_prepare(cd->pipeline, cd); + if (ret < 0) + tr_err(&ipc_tr, "pipeline %d: prepare failed %d", ppl_icd->id, ret); + else + ret = 0; + } + } break; default: - ipc_cmd_err(&ipc_tr, + tr_err(&ipc_tr, "pipeline %d: Invalid state for RUNNING: %d", ppl_icd->id, status); return IPC4_INVALID_REQUEST; @@ -238,6 +300,9 @@ int ipc4_pipeline_prepare(struct ipc_comp_dev *ppl_icd, uint32_t cmd) case COMP_STATE_READY: case COMP_STATE_ACTIVE: case COMP_STATE_PAUSED: + case COMP_STATE_PREPARE: + case COMP_STATE_PRE_ACTIVE: + case COMP_STATE_SUSPEND: /* No action needed */ break; default: @@ -282,12 +347,13 @@ int ipc4_pipeline_prepare(struct ipc_comp_dev *ppl_icd, uint32_t cmd) pipeline_set_eos(ppl_icd->pipeline, false); - return ret; + return 0; } int ipc4_pipeline_trigger(struct ipc_comp_dev *ppl_icd, uint32_t cmd, bool *delayed) { struct ipc_comp_dev *host; + struct comp_dev *trigger_cd = NULL; int status; int ret; @@ -298,19 +364,24 @@ int ipc4_pipeline_trigger(struct ipc_comp_dev *ppl_icd, uint32_t cmd, bool *dela if (status == COMP_STATE_INIT) return 0; - host = pipeline_get_host_dev(ppl_icd); - if (!host) + trigger_cd = pipeline_get_endpoint_comp(ppl_icd); + if (!trigger_cd) return IPC4_INVALID_RESOURCE_ID; + host = pipeline_get_host_dev(ppl_icd); + switch (cmd) { case SOF_IPC4_PIPELINE_STATE_RUNNING: /* init params when pipeline is complete or reset */ switch (status) { case COMP_STATE_ACTIVE: + case COMP_STATE_PRE_ACTIVE: /* nothing to do if the pipeline is already running */ return 0; + case COMP_STATE_INIT: case COMP_STATE_READY: case COMP_STATE_PREPARE: + case COMP_STATE_SUSPEND: cmd = COMP_TRIGGER_PRE_START; break; case COMP_STATE_PAUSED: @@ -327,6 +398,9 @@ int ipc4_pipeline_trigger(struct ipc_comp_dev *ppl_icd, uint32_t cmd, bool *dela switch (status) { case COMP_STATE_ACTIVE: case COMP_STATE_PAUSED: + case COMP_STATE_PREPARE: + case COMP_STATE_PRE_ACTIVE: + case COMP_STATE_SUSPEND: cmd = COMP_TRIGGER_STOP; break; default: @@ -338,6 +412,7 @@ int ipc4_pipeline_trigger(struct ipc_comp_dev *ppl_icd, uint32_t cmd, bool *dela case COMP_STATE_INIT: case COMP_STATE_READY: case COMP_STATE_PAUSED: + case COMP_STATE_SUSPEND: return 0; default: cmd = COMP_TRIGGER_PAUSE; @@ -363,8 +438,51 @@ int ipc4_pipeline_trigger(struct ipc_comp_dev *ppl_icd, uint32_t cmd, bool *dela */ dbg_path_hot_confirm(); - /* trigger the component */ - ret = pipeline_trigger(host->cd->pipeline, host->cd, cmd); + bool is_endpoint = pipeline_is_endpoint(trigger_cd->pipeline); + + if (!is_endpoint) { + /* + * Hostless internal pipelines (e.g. background keyword detection or internal + * processing chains feeding arbiters or modules without a host or DAI copier) + * have no host DMA or DAI hardware to delay IPC replies. + * Execute the trigger and reset synchronously inline. + */ + ret = pipeline_trigger_run(trigger_cd->pipeline, trigger_cd, cmd); + if (ret < 0) { + ipc_cmd_err(&ipc_tr, "pipeline %d: trigger cmd %d failed with: %d", + ppl_icd->id, cmd, ret); + return IPC4_PIPELINE_STATE_NOT_SET; + } + + switch (cmd) { + case COMP_TRIGGER_PRE_START: + case COMP_TRIGGER_START: + case COMP_TRIGGER_PRE_RELEASE: + case COMP_TRIGGER_RELEASE: + trigger_cd->pipeline->status = COMP_STATE_ACTIVE; + pipeline_schedule_copy(trigger_cd->pipeline, 0); + break; + case COMP_TRIGGER_PAUSE: + pipeline_schedule_cancel(trigger_cd->pipeline); + trigger_cd->pipeline->status = COMP_STATE_PAUSED; + break; + case COMP_TRIGGER_STOP: + pipeline_schedule_cancel(trigger_cd->pipeline); + trigger_cd->pipeline->status = COMP_STATE_READY; + ret = pipeline_reset(trigger_cd->pipeline, trigger_cd); + if (ret < 0 && ret != PPL_STATUS_PATH_STOP) + return IPC4_INVALID_REQUEST; + break; + default: + break; + } + + *delayed = false; + return 0; + } + + /* trigger the endpoint component (host or DAI) */ + ret = pipeline_trigger(trigger_cd->pipeline, trigger_cd, cmd); if (ret < 0) { ipc_cmd_err(&ipc_tr, "pipeline %d: trigger cmd %d failed with: %d", ppl_icd->id, cmd, ret); @@ -381,9 +499,15 @@ int ipc4_pipeline_trigger(struct ipc_comp_dev *ppl_icd, uint32_t cmd, bool *dela * Otherwise, the pipeline will be reset after the STOP trigger * has finished executing in the pipeline task. */ - ret = pipeline_reset(host->cd->pipeline, host->cd); - if (ret < 0) + struct comp_dev *reset_cd = host ? host->cd : trigger_cd; + + ret = pipeline_reset(reset_cd->pipeline, reset_cd); + if (ret < 0 && ret != PPL_STATUS_PATH_STOP) ret = IPC4_INVALID_REQUEST; + else + ret = 0; + } else { + ret = 0; } return ret; diff --git a/zephyr/edf_schedule.c b/zephyr/edf_schedule.c index 3578b3dd6c7d..005c70196832 100644 --- a/zephyr/edf_schedule.c +++ b/zephyr/edf_schedule.c @@ -87,6 +87,7 @@ static int schedule_edf_task_running(void *data, struct task *task) static int schedule_edf_task_free(void *data, struct task *task) { + k_work_cancel_delayable(&task->z_delayed_work); task->state = SOF_TASK_STATE_FREE; task->ops.run = NULL; task->data = NULL; From 4028d626758d8bf6842472338f16dc9a93a912d7 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 05/31] lib, audio, ipc: add teardown NULL guards, blocking IDC notify, and log throttling Harden resource teardown, cross-core notifications, and host XRUN logs: - Guard NULL pointers in dai_put(), sof_dma_put(), dai_common_free(), dai_free(), and copier_dai_free(). - Stop and reset active/paused components before freeing in ipc_comp_free(). - Use IDC_BLOCKING in notifier_event() to avoid overwriting queued notify_data on back-to-back cross-core notifications. - Guard NULL system agent in sa_set_panic_on_delay(). - Increase SOF_MIN_NO_BYTES_INTERVAL_MS to 1000 ms in host-zephyr.c. Signed-off-by: Liam Girdwood Co-authored-by: Seppo Ingalsuo Signed-off-by: Seppo Ingalsuo --- src/audio/copier/copier_dai.c | 16 ++++++++++++---- src/audio/dai-zephyr.c | 27 +++++++++++++++++++++++---- src/audio/host-zephyr.c | 2 +- src/include/sof/lib/agent.h | 3 +++ src/ipc/ipc-helper.c | 9 ++++++++- src/kernel/lib/dai-kernel.c | 6 ++++++ src/kernel/lib/dma-kernel.c | 3 +++ src/lib/notifier.c | 5 ++++- 8 files changed, 60 insertions(+), 11 deletions(-) diff --git a/src/audio/copier/copier_dai.c b/src/audio/copier/copier_dai.c index 508972b4773c..a4c88554c4a6 100644 --- a/src/audio/copier/copier_dai.c +++ b/src/audio/copier/copier_dai.c @@ -424,13 +424,21 @@ __cold void copier_dai_free(struct processing_module *mod) assert_can_be_cold(); for (int i = 0; i < cd->endpoint_num; i++) { - dai_common_free(cd->dd[i]); - mod_free(mod, cd->dd[i]->gain_data); - mod_free(mod, cd->dd[i]); + if (cd->dd[i]) { + if (cd->dd[i]->gain_data) { + mod_free(mod, cd->dd[i]->gain_data); + cd->dd[i]->gain_data = NULL; + } + dai_common_free(cd->dd[i]); + mod_free(mod, cd->dd[i]); + cd->dd[i] = NULL; + } } /* only dai have multi endpoint case */ - if (cd->multi_endpoint_buffer) + if (cd->multi_endpoint_buffer) { buffer_free(cd->multi_endpoint_buffer); + cd->multi_endpoint_buffer = NULL; + } } int copier_dai_prepare(struct comp_dev *dev, struct copier_data *cd) diff --git a/src/audio/dai-zephyr.c b/src/audio/dai-zephyr.c index 40d0a9f4902a..679606e321cd 100644 --- a/src/audio/dai-zephyr.c +++ b/src/audio/dai-zephyr.c @@ -793,22 +793,36 @@ __cold void dai_common_free(struct dai_data *dd) { assert_can_be_cold(); + if (!dd) + return; + #ifdef CONFIG_SOF_TELEMETRY_IO_PERFORMANCE_MEASUREMENTS io_perf_monitor_release_slot(dd->io_perf_dai_byte_count); #endif telemetry_unregister_dai(dd); - if (dd->group) + if (dd->group) { dai_group_put(dd->group); + dd->group = NULL; + } dai_dma_release_channel(dd); - sof_dma_put(dd->dma); + if (dd->dma) { + sof_dma_put(dd->dma); + dd->dma = NULL; + } dai_release_llp_slot(dd); - dai_put(dd->dai); + if (dd->dai) { + dai_put(dd->dai); + dd->dai = NULL; + } - sof_heap_free(dd->alloc_ctx.heap, dd->dai_spec_config); + if (dd->dai_spec_config) { + sof_heap_free(dd->alloc_ctx.heap, dd->dai_spec_config); + dd->dai_spec_config = NULL; + } #if CONFIG_UAOL_INTEL_ADSP uaol_free(dd); @@ -821,6 +835,11 @@ __cold static void dai_free(struct comp_dev *dev) assert_can_be_cold(); + if (!dd) { + comp_free_device(dev); + return; + } + if (dd->group) notifier_unregister(dev, dd->group, NOTIFIER_ID_DAI_TRIGGER); diff --git a/src/audio/host-zephyr.c b/src/audio/host-zephyr.c index 30449f3c0edf..a9e825cfa7f6 100644 --- a/src/audio/host-zephyr.c +++ b/src/audio/host-zephyr.c @@ -415,7 +415,7 @@ static int host_get_status(struct comp_dev *dev, struct host_data *hd, struct dm } /* Minimum time between 2 consecutive "no bytes to copy" messages in milliseconds */ -#define SOF_MIN_NO_BYTES_INTERVAL_MS 20 +#define SOF_MIN_NO_BYTES_INTERVAL_MS 1000 static inline bool host_handle_eos(struct host_data *hd, struct comp_dev *dev, uint32_t avail_samples) diff --git a/src/include/sof/lib/agent.h b/src/include/sof/lib/agent.h index 6aaa740761f2..793181eaf624 100644 --- a/src/include/sof/lib/agent.h +++ b/src/include/sof/lib/agent.h @@ -42,6 +42,9 @@ static inline void sa_set_panic_on_delay(bool enabled) { struct sa *sa = sof_get()->sa; + if (!sa) + return; + if (enabled) atomic_add(&sa->panic_cnt, 1); else diff --git a/src/ipc/ipc-helper.c b/src/ipc/ipc-helper.c index c8e82587edf7..9e0514c6d651 100644 --- a/src/ipc/ipc-helper.c +++ b/src/ipc/ipc-helper.c @@ -316,7 +316,14 @@ __cold int ipc_comp_free(struct ipc *ipc, uint32_t comp_id) if (!cpu_is_me(icd->core)) return ipc_process_on_core(icd->core, false); - /* check state */ + /* check state: if not ready, stop and reset to release resources before freeing */ + if (icd->cd->state != COMP_STATE_READY) { + if (icd->cd->state == COMP_STATE_ACTIVE) + comp_trigger(icd->cd, COMP_TRIGGER_STOP); + comp_reset(icd->cd); + comp_set_state(icd->cd, COMP_TRIGGER_RESET); + } + if (icd->cd->state != COMP_STATE_READY) { tr_err(&ipc_tr, "comp id: 0x%x state is %d cannot be freed", comp_id, icd->cd->state); diff --git a/src/kernel/lib/dai-kernel.c b/src/kernel/lib/dai-kernel.c index c12bfeafa24e..88b2d5580587 100644 --- a/src/kernel/lib/dai-kernel.c +++ b/src/kernel/lib/dai-kernel.c @@ -260,6 +260,9 @@ __cold void dai_put(struct dai *dai) assert_can_be_cold(); + if (!dai) + return; + #ifdef CONFIG_SOF_USERSPACE_LL heap = zephyr_ll_user_heap(); #endif @@ -332,6 +335,9 @@ __cold void dai_put(struct dai *dai) assert_can_be_cold(); + if (!dai) + return; + key = k_spin_lock(&dai->lock); if (--dai->sref == 0) { ret = dai_remove(dai); diff --git a/src/kernel/lib/dma-kernel.c b/src/kernel/lib/dma-kernel.c index 422c89f20d2c..3a9aba06e797 100644 --- a/src/kernel/lib/dma-kernel.c +++ b/src/kernel/lib/dma-kernel.c @@ -178,6 +178,9 @@ __cold void z_impl_sof_dma_put(struct sof_dma *dma) assert_can_be_cold(); + if (!dma) + return; + key = k_spin_lock(dma_lock(dma)); if (*dma_sref(dma) <= 0) { tr_err(&dma_tr, "dma_put(), dma = %p not in use", dma); diff --git a/src/lib/notifier.c b/src/lib/notifier.c index cbc9ff5cd7f8..c6e5a08b45cb 100644 --- a/src/lib/notifier.c +++ b/src/lib/notifier.c @@ -172,7 +172,10 @@ void notifier_event(const void *caller, enum notify_id type, uint32_t core_mask, dcache_writeback_region((__sparse_force void __sparse_cache *) notify_data->data, data_size); - idc_send_msg(¬ify_msg, IDC_NON_BLOCKING); + /* Wait for completion: back-to-back events to the same core would + * otherwise reuse a queued IDC work item and overwrite notify_data. + */ + idc_send_msg(¬ify_msg, IDC_BLOCKING); } } } From 9067b2229996469f34fede73b3da4c7f76269cd6 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 06/31] notifier, ipc4: add WOV and D0iX power state notifier events Add NOTIFIER_ID_WOV_DETECT, NOTIFIER_ID_WOV_CTRL, and NOTIFIER_ID_D0IX_STATE notifier IDs along with the D0iX state payload and WOV arbiter notifier/control ABI header. Dispatch NOTIFIER_ID_D0IX_STATE from ipc4_module_process_d0ix() so components such as microWakeWord can switch to low-power D0i3 operation. Signed-off-by: Liam Girdwood --- src/include/sof/audio/wov_arbiter.h | 56 ++++++++++++++++++++++++++++ src/include/sof/lib/notifier.h | 15 ++++++++ src/kernel/ipc/ipc4/handler-kernel.c | 12 ++++++ 3 files changed, 83 insertions(+) create mode 100644 src/include/sof/audio/wov_arbiter.h diff --git a/src/include/sof/audio/wov_arbiter.h b/src/include/sof/audio/wov_arbiter.h new file mode 100644 index 000000000000..0dff468fd275 --- /dev/null +++ b/src/include/sof/audio/wov_arbiter.h @@ -0,0 +1,56 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * + * Copyright(c) 2024 Intel Corporation. All rights reserved. + */ + +#ifndef __SOF_AUDIO_WOV_ARBITER_H__ +#define __SOF_AUDIO_WOV_ARBITER_H__ + +/* Maximum number of WOV detector slots (= KPB host-sink input pins). */ +#define WOV_ARB_MAX_SLOTS 8 + +/* Sentinel: no slot is currently draining. */ +#define WOV_ARB_NO_ACTIVE 0xff + +/** Host enum control IDs exposed by the WoV arbiter topology. */ +#define WOV_ARB_ACTIVE_SLOT_CONTROL_ID 1 +#define WOV_ARB_CALL_STATE_CONTROL_ID 2 + +/** Values of the host WoV call-state enum control. */ +#define WOV_ARB_CALL_STATE_LISTENING 0 +#define WOV_ARB_CALL_STATE_ACTIVE 1 + +/* + * IPC4 SET_LARGE_CONFIG param ID used to set the arbiter's active input + * explicitly from the host (testing / override). + */ +#define IPC4_WOV_ARB_SET_ACTIVE_SLOT 1 + +/* + * IPC4 GET_LARGE_CONFIG param ID: read the currently active slot. + * Host uses this for the volatile RO kcontrol; returns WOV_ARB_NO_ACTIVE + * when no drain is in progress. + */ +#define IPC4_WOV_ARB_GET_ACTIVE_SLOT 2 + +/* Command codes for WOV_CTRL notifier payload (arbiter → detectors). */ +#define WOV_ARB_CMD_PAUSE 0 +#define WOV_ARB_CMD_RESUME 1 + +/* WOV detect notifier payload (detector → arbiter). */ +struct wov_detect_notif { + uint8_t slot_id; /* 0-based detector slot that fired */ +}; + +/* WOV ctrl notifier payload (arbiter → detectors). */ +struct wov_ctrl_notif { + uint8_t cmd; /* WOV_ARB_CMD_PAUSE or WOV_ARB_CMD_RESUME */ + uint8_t slot_id; /* winning slot; receivers skip if this is their own slot */ +}; + +/* Sentinel value matching WOV_SLOT_INVALID in ams_msg.h */ +#define WOV_SLOT_INVALID 0xff + +void sys_comp_wov_arbiter_init(void); + +#endif /* __SOF_AUDIO_WOV_ARBITER_H__ */ diff --git a/src/include/sof/lib/notifier.h b/src/include/sof/lib/notifier.h index e5413a512cb4..c0b07113bb10 100644 --- a/src/include/sof/lib/notifier.h +++ b/src/include/sof/lib/notifier.h @@ -12,6 +12,7 @@ #include #include #include +#include #include /* notifier target core masks */ @@ -19,6 +20,17 @@ #define NOTIFIER_TARGET_CORE_LOCAL NOTIFIER_TARGET_CORE_MASK(cpu_get_id()) #define NOTIFIER_TARGET_CORE_ALL_MASK 0xFFFFFFFF +/** + * \brief NOTIFIER_ID_D0IX_STATE payload. + * + * Raised when the host changes the DSP D0 substate via SOF_IPC4_MOD_SET_D0IX. + * Components that must keep working while the host is in S0iX can use this to + * tell "host asleep, DSP still running" from normal operation. + */ +struct d0ix_state_notif { + bool entering; /**< true: entering D0i3, false: returning to D0i0 */ +}; + enum notify_id { NOTIFIER_ID_CPU_FREQ = 0, /* struct clock_notify_data * */ NOTIFIER_ID_SSP_FREQ, /* struct clock_notify_data * */ @@ -29,6 +41,9 @@ enum notify_id { NOTIFIER_ID_DAI_TRIGGER, /* struct dai_group * */ NOTIFIER_ID_MIC_PRIVACY_STATE_CHANGE, /* struct mic_privacy_settings * */ NOTIFIER_ID_VAD, /* int * (WEBRTC_VAD_SPEECH / WEBRTC_VAD_SILENCE) */ + NOTIFIER_ID_WOV_DETECT, /* struct wov_detect_notif *: keyword detected */ + NOTIFIER_ID_WOV_CTRL, /* struct wov_ctrl_notif *: pause/resume detectors */ + NOTIFIER_ID_D0IX_STATE, /* struct d0ix_state_notif *: host D0i3 entry/exit */ NOTIFIER_ID_COUNT }; diff --git a/src/kernel/ipc/ipc4/handler-kernel.c b/src/kernel/ipc/ipc4/handler-kernel.c index 29b25bdf5d7d..d202ed4261d7 100644 --- a/src/kernel/ipc/ipc4/handler-kernel.c +++ b/src/kernel/ipc/ipc4/handler-kernel.c @@ -21,6 +21,7 @@ #include #include #include +#include #include #include #include @@ -332,6 +333,17 @@ __cold static int ipc4_module_process_d0ix(struct ipc4_message_request *ipc4) else pm_runtime_enable(PM_RUNTIME_DSP, PLATFORM_PRIMARY_CORE_ID); + /* Tell interested components that the host is entering or leaving S0iX. + * prevent_power_gating is set on the way back to D0i0 and clear when the + * host allows the DSP to power gate, i.e. when the host is going to sleep. + */ + struct d0ix_state_notif notif = { + .entering = !d0ix.extension.r.prevent_power_gating, + }; + + notifier_event(NULL, NOTIFIER_ID_D0IX_STATE, NOTIFIER_TARGET_CORE_ALL_MASK, + ¬if, sizeof(notif)); + return 0; } From 9c6b45968a078c5c93ffc1866f305500b6d25ecd Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 07/31] audio: intel_uaol: only advertise UAOL links that answered Count only UAOL links whose uaol_get_capabilities() call succeeded, pack link_caps[] from index 0, and size the returned TLV accordingly instead of reporting unresponsive links with zeroed capabilities. Signed-off-by: Liam Girdwood --- src/kernel/audio/intel_uaol-kernel.c | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/src/kernel/audio/intel_uaol-kernel.c b/src/kernel/audio/intel_uaol-kernel.c index 788bf49893ec..99aa2942d93d 100644 --- a/src/kernel/audio/intel_uaol-kernel.c +++ b/src/kernel/audio/intel_uaol-kernel.c @@ -37,6 +37,7 @@ __cold void tlv_value_set_uaol_caps(struct sof_tlv *tuple, uint32_t type) struct uaol_capabilities dev_cap; struct ipc4_uaol_capabilities *caps = (struct ipc4_uaol_capabilities *)tuple->value; size_t caps_size = offsetof(struct ipc4_uaol_capabilities, link_caps[dev_count]); + size_t link_count = 0; size_t i; int ret; @@ -44,19 +45,27 @@ __cold void tlv_value_set_uaol_caps(struct sof_tlv *tuple, uint32_t type) memset(caps, 0, caps_size); - caps->link_count = dev_count; + /* Only advertise links that answered. uaol_get_capabilities() fails when + * the host has not offloaded link control to the DSP (UAOLCTL.OFLEN), in + * which case the link's segment registers are not readable here. + */ for (i = 0; i < dev_count; i++) { ret = uaol_get_capabilities(uaol_devs[i], &dev_cap); if (ret) continue; - caps->link_caps[i].input_streams_supported = dev_cap.input_streams; - caps->link_caps[i].output_streams_supported = dev_cap.output_streams; - caps->link_caps[i].bidirectional_streams_supported = dev_cap.bidirectional_streams; - caps->link_caps[i].max_tx_fifo_size = dev_cap.max_tx_fifo_size; - caps->link_caps[i].max_rx_fifo_size = dev_cap.max_rx_fifo_size; + caps->link_caps[link_count].input_streams_supported = dev_cap.input_streams; + caps->link_caps[link_count].output_streams_supported = dev_cap.output_streams; + caps->link_caps[link_count].bidirectional_streams_supported = + dev_cap.bidirectional_streams; + caps->link_caps[link_count].max_tx_fifo_size = dev_cap.max_tx_fifo_size; + caps->link_caps[link_count].max_rx_fifo_size = dev_cap.max_rx_fifo_size; + link_count++; } + caps->link_count = link_count; + caps_size = offsetof(struct ipc4_uaol_capabilities, link_caps[link_count]); + tlv_value_set(tuple, type, caps_size, caps); } #endif /* !CONFIG_SOF_OS_LINUX_COMPAT_PRIORITY */ From e0b3a314b03a2de5d63c4a10936f15332bf7e60f Mon Sep 17 00:00:00 2001 From: Seppo Ingalsuo Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 08/31] math: add PCAN (Per-Channel AGC Normalization) and ztest suite Add fixed-point Per-Channel AGC Normalization (PCAN) math library under src/math/pcan/ with Octave reference scripts and a Zephyr ztest unit test suite. Extend mel_filterbank_32.c and auditory.h for 32-bit Mel output scaling needed by PCAN. Signed-off-by: Seppo Ingalsuo --- src/include/sof/math/auditory.h | 4 + src/include/sof/math/pcan.h | 148 +++++++++++ src/math/CMakeLists.txt | 4 + src/math/Kconfig | 11 + src/math/auditory/mel_filterbank_32.c | 77 ++++-- src/math/numbers.c | 1 + src/math/pcan/CMakeLists.txt | 39 +++ src/math/pcan/README.md | 105 ++++++++ src/math/pcan/pcan.c | 234 ++++++++++++++++++ test/cmocka/src/math/auditory/CMakeLists.txt | 1 + .../unit/math/advanced/pcan/CMakeLists.txt | 61 +++++ .../math/advanced/pcan/pcan_gain_lookup.m | 77 ++++++ .../math/advanced/pcan/pcan_noise_estimate.m | 37 +++ .../unit/math/advanced/pcan/pcan_process.m | 55 ++++ .../unit/math/advanced/pcan/pcan_shrink.m | 41 +++ .../ztest/unit/math/advanced/pcan/pcan_test.c | 173 +++++++++++++ .../advanced/pcan/pcan_wide_dynamic_func.m | 56 +++++ test/ztest/unit/math/advanced/pcan/prj.conf | 2 + test/ztest/unit/math/advanced/pcan/ref_pcan.m | 212 ++++++++++++++++ .../math/advanced/pcan/ref_pcan_corners.h | 28 +++ .../unit/math/advanced/pcan/ref_pcan_func.h | 47 ++++ .../unit/math/advanced/pcan/ref_pcan_lut.h | 45 ++++ .../unit/math/advanced/pcan/ref_pcan_stream.h | 132 ++++++++++ .../unit/math/advanced/pcan/testcase.yaml | 16 ++ 24 files changed, 1592 insertions(+), 14 deletions(-) create mode 100644 src/include/sof/math/pcan.h create mode 100644 src/math/pcan/CMakeLists.txt create mode 100644 src/math/pcan/README.md create mode 100644 src/math/pcan/pcan.c create mode 100644 test/ztest/unit/math/advanced/pcan/CMakeLists.txt create mode 100644 test/ztest/unit/math/advanced/pcan/pcan_gain_lookup.m create mode 100644 test/ztest/unit/math/advanced/pcan/pcan_noise_estimate.m create mode 100644 test/ztest/unit/math/advanced/pcan/pcan_process.m create mode 100644 test/ztest/unit/math/advanced/pcan/pcan_shrink.m create mode 100644 test/ztest/unit/math/advanced/pcan/pcan_test.c create mode 100644 test/ztest/unit/math/advanced/pcan/pcan_wide_dynamic_func.m create mode 100644 test/ztest/unit/math/advanced/pcan/prj.conf create mode 100644 test/ztest/unit/math/advanced/pcan/ref_pcan.m create mode 100644 test/ztest/unit/math/advanced/pcan/ref_pcan_corners.h create mode 100644 test/ztest/unit/math/advanced/pcan/ref_pcan_func.h create mode 100644 test/ztest/unit/math/advanced/pcan/ref_pcan_lut.h create mode 100644 test/ztest/unit/math/advanced/pcan/ref_pcan_stream.h create mode 100644 test/ztest/unit/math/advanced/pcan/testcase.yaml diff --git a/src/include/sof/math/auditory.h b/src/include/sof/math/auditory.h index 4a612372ea3b..919736f02655 100644 --- a/src/include/sof/math/auditory.h +++ b/src/include/sof/math/auditory.h @@ -120,4 +120,8 @@ void psy_apply_mel_filterbank_16(struct psy_mel_filterbank *mel_fb, struct icomp void psy_apply_mel_filterbank_32(struct psy_mel_filterbank *mel_fb, struct icomplex32 *fft_out, int32_t *power_spectra, int32_t *mel_log, int bitshift); +void psy_apply_mel_filterbank_with_linear_32(struct psy_mel_filterbank *mel_fb, struct icomplex32 *fft_out, + int32_t *power_spectra, int32_t *mel_log, + uint32_t *mel_linear, int bitshift); + #endif /* __SOF_MATH_AUDITORY_H__ */ diff --git a/src/include/sof/math/pcan.h b/src/include/sof/math/pcan.h new file mode 100644 index 000000000000..4320210da89a --- /dev/null +++ b/src/include/sof/math/pcan.h @@ -0,0 +1,148 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * + * Copyright(c) 2026 Intel Corporation. All rights reserved. + * + * Author: Antigravity AI & SOF Team + */ + +/** + * \file include/sof/math/pcan.h + * \brief Per-Channel AGC Normalization (PCAN) library interface + * + * Wraps and integrates Google's upstream TFLite Micro microfrontend + * library (under Apache-2.0 with patent grant protection). + */ + +#ifndef __SOF_MATH_PCAN_H__ +#define __SOF_MATH_PCAN_H__ + +#include +#include +#include + +#include "tensorflow/lite/experimental/microfrontend/lib/bits.h" +#include "tensorflow/lite/experimental/microfrontend/lib/pcan_gain_control.h" +#include "tensorflow/lite/experimental/microfrontend/lib/pcan_gain_control_util.h" +#include "tensorflow/lite/experimental/microfrontend/lib/noise_reduction.h" +#include "tensorflow/lite/experimental/microfrontend/lib/noise_reduction_util.h" +#include "tensorflow/lite/experimental/microfrontend/lib/log_scale.h" + +#define PCAN_SNR_BITS kPcanSnrBits /* 12 */ +#define PCAN_OUTPUT_BITS kPcanOutputBits /* 6 */ +#define PCAN_SMOOTHING_COEF_BITS kNoiseReductionBits /* 14 */ +#define PCAN_WIDE_DYNAMIC_BITS kWideDynamicFunctionBits /* 32 */ +#define PCAN_LUT_SIZE kWideDynamicFunctionLUTSize /* 125 */ + +/* Google derives this as log2(fft_size) - 1 - kFilterbankBits / 2 because its + * fixed-point FFT keeps a 1/N scale. SOF compensates the FFT length in the Mel + * filter bank and scales mel_linear to Google's 512-point range, so it is 3 for + * every FFT size. + */ +#define PCAN_INPUT_CORRECTION_BITS 3 + +/** + * \brief SOF PCAN configuration structure. + */ +struct pcan_config { + int32_t strength; /**< Exponent alpha in Q1.15 (e.g. 31130 for 0.95) */ + int32_t offset; /**< Additive offset delta in Q8.7 (e.g. 10240 for 80.0) */ + int32_t gain_bits; /**< Gain bit shift (e.g. 21) */ + uint16_t smoothing_coef; /**< IIR smoothing coefficient in Q14 (e.g. 819 for 0.05) */ + uint16_t smoothing_bits; /**< Bit shift for noise estimate (e.g. 10) */ + int32_t input_correction_bits; /**< Input correction bits shift (e.g. 0) */ + bool enable_pcan; /**< Enable flag */ +}; + +/** + * \brief SOF PCAN runtime state wrapper. + */ +struct pcan_state { + struct PcanGainControlState g_pcan; /**< Google upstream PCAN state */ + struct NoiseReductionState g_noise; /**< Google upstream Noise Reduction state */ + struct LogScaleState g_log_scale; /**< Google upstream LogScale state */ + uint32_t *noise_estimate; /**< Pointer to noise estimate buffer */ + int16_t *gain_lut; /**< Pointer to gain LUT */ + int num_channels; /**< Number of channels */ + int32_t snr_shift; /**< SNR bit shift */ + uint16_t smoothing_bits; /**< Smoothing bits */ + bool enable_pcan; /**< PCAN enabled */ + bool allocated_noise; /**< Internally allocated noise buffer */ + bool allocated_lut; /**< Internally allocated gain LUT buffer */ +}; + +/** + * \brief Evaluate Google's WideDynamicFunction. + */ +static inline int16_t pcan_wide_dynamic_function(uint32_t x, const int16_t *lut) +{ + return WideDynamicFunction(x, lut); +} + +/** + * \brief Evaluate Google's PcanShrink. + */ +static inline uint32_t pcan_shrink(uint32_t x) +{ + return PcanShrink(x); +} + +/** + * \brief Compute single point in continuous PCAN gain curve. + * + * \param strength Exponent alpha in Q1.15. + * \param offset Additive offset delta in Q8.7. + */ +int16_t pcan_gain_lookup_function(int32_t strength, int32_t offset, int32_t gain_bits, + int32_t input_bits, uint32_t x); + +/** + * \brief Fill 125-entry gain lookup table for WideDynamicFunction. + * + * \param strength Exponent alpha in Q1.15. + * \param offset Additive offset delta in Q8.7. + */ +int pcan_compute_lut(int32_t strength, int32_t offset, int32_t gain_bits, + int32_t input_bits, int16_t *gain_lut); + +/** + * \brief Initialize PCAN state with supplied buffers or allocate them. + */ +int pcan_populate_state(const struct pcan_config *config, struct pcan_state *state, + uint32_t *noise_estimate_buffer, int16_t *gain_lut_buffer, + int num_channels, uint16_t smoothing_bits, + int32_t input_correction_bits); + +/** + * \brief Free allocated resources in PCAN state. + */ +void pcan_free_state(struct pcan_state *state); + +/** + * \brief Reset PCAN temporal state. + */ +void pcan_reset(struct pcan_state *state); + +/** + * \brief Apply noise reduction and update noise estimate using Google's NoiseReductionApply. + */ +static inline void pcan_noise_reduction(struct pcan_state *state, uint32_t *signal) +{ + if (state && state->enable_pcan) + NoiseReductionApply(&state->g_noise, signal); +} + +/** + * \brief Apply PCAN gain control and compression using Google's PcanGainControlApply. + */ +static inline void pcan_apply(struct pcan_state *state, uint32_t *signal) +{ + if (state && state->enable_pcan) + PcanGainControlApply(&state->g_pcan, signal); +} + +/** + * \brief Apply Google's fixed-point logarithm and scale to signal in-place. + */ +void pcan_log_scale(struct pcan_state *state, uint32_t *signal); + +#endif /* __SOF_MATH_PCAN_H__ */ diff --git a/src/math/CMakeLists.txt b/src/math/CMakeLists.txt index c653145f1668..abb23e23aa7f 100644 --- a/src/math/CMakeLists.txt +++ b/src/math/CMakeLists.txt @@ -89,6 +89,10 @@ if(CONFIG_MATH_AUDITORY) add_subdirectory(auditory) endif() +if(CONFIG_MATH_PCAN) + add_subdirectory(pcan) +endif() + if(CONFIG_MATH_DCT) list(APPEND base_files dct.c) endif() diff --git a/src/math/Kconfig b/src/math/Kconfig index f962415e66d8..6f0a2c783695 100644 --- a/src/math/Kconfig +++ b/src/math/Kconfig @@ -304,6 +304,17 @@ config MATH_32BIT_MEL_FILTERBANK endmenu +config MATH_PCAN + bool "PCAN (Per-Channel AGC Normalization) library" + default n + select BINARY_LOGARITHM_FIXED + select MATH_EXP + select NATURAL_LOGARITHM_FIXED + help + Select this to build PCAN (Per-Channel Automatic Gain Control Normalization) + library. PCAN performs dynamic per-channel gain control and piecewise polynomial + root compression across time to suppress stationary noise and enhance acoustic transients. + config MATH_DCT bool "DCT transform library" default n diff --git a/src/math/auditory/mel_filterbank_32.c b/src/math/auditory/mel_filterbank_32.c index 414ddf482f93..c496973f64a1 100644 --- a/src/math/auditory/mel_filterbank_32.c +++ b/src/math/auditory/mel_filterbank_32.c @@ -9,10 +9,23 @@ #include #include #include +#include #include -void psy_apply_mel_filterbank_32(struct psy_mel_filterbank *fb, struct icomplex32 *fft_out, - int32_t *power_spectra, int32_t *mel_log, int bitshift) +static inline uint32_t mel_sqrt32(uint32_t num) +{ + if (num == 0) + return 0; + + /* sofm_sqrt_int32 treats input as Q2.30, returning sqrt(n)*2^15. + * Scale down by 2^15 with rounding to obtain integer sqrt(num). + */ + return (uint32_t)((sofm_sqrt_int32((int32_t)num) + (1 << 14)) >> 15); +} + +void psy_apply_mel_filterbank_with_linear_32(struct psy_mel_filterbank *fb, struct icomplex32 *fft_out, + int32_t *power_spectra, int32_t *mel_log, + uint32_t *mel_linear, int bitshift) { int64_t pmax; int64_t p; @@ -67,20 +80,56 @@ void psy_apply_mel_filterbank_32(struct psy_mel_filterbank *fb, struct icomplex3 */ log_arg = sat_int32(Q_SHIFT_RND(p, 45, 25)); log_arg = MAX(log_arg, AUDITORY_EPS_Q31); - log = base2_logarithm((uint32_t)log_arg); - log -= AUDITORY_LOG2_2P25_Q16; - /* Compensate Mel triangles scale */ - log += fb->scale_log2; + if (mel_linear) { + /* Compensate dynamic lshift and FFT bitshift so mel_linear reflects + * true acoustic magnitude calibrated to Google microfrontend range. + */ + uint32_t s = mel_sqrt32((uint32_t)log_arg); + /* Total power shift applied was: lshift + 2 * bitshift */ + int neg_shift = -((int32_t)lshift + 2 * bitshift); + int int_shift = neg_shift >> 1; + int frac_shift = neg_shift & 1; - /* Subtract the applied lshift for power spectra - * log2(x * 2^(-n)) = log2(x) - n. Note that the bitshift need to be subtracted - * as doubled because it was applied in linear domain, from log(x * 2^(-2 * n)) - */ - log -= ((int32_t)lshift + 2 * bitshift) << 16; + uint64_t s_comp = s; + if (frac_shift) + s_comp = (s_comp * 46341U) >> 15; /* 46341 / 32768 ~= sqrt(2) */ + + if (int_shift > 0) + s_comp <<= int_shift; + else if (int_shift < 0) + s_comp >>= -int_shift; + + /* Scale to Google microfrontend range: 25826 / 32768 ~= 0.788 */ + s_comp = (s_comp * 25826U) >> 15; + if (s_comp > UINT32_MAX) + s_comp = UINT32_MAX; - /* Scale for desired log, output as Q9.23 */ - log = Q_MULTSR_32X32((int64_t)log, fb->log_mult, 16, 29, 23); - mel_log[i] = log; /* Q9.23 */ + mel_linear[i] = (uint32_t)s_comp; + } + + if (mel_log) { + log = base2_logarithm((uint32_t)log_arg); + log -= AUDITORY_LOG2_2P25_Q16; + + /* Compensate Mel triangles scale */ + log += fb->scale_log2; + + /* Subtract the applied lshift for power spectra + * log2(x * 2^(-n)) = log2(x) - n. Note that the bitshift need to be subtracted + * as doubled because it was applied in linear domain, from log(x * 2^(-2 * n)) + */ + log -= ((int32_t)lshift + 2 * bitshift) << 16; + + /* Scale for desired log, output as Q9.23 */ + log = Q_MULTSR_32X32((int64_t)log, fb->log_mult, 16, 29, 23); + mel_log[i] = log; /* Q9.23 */ + } } } + +void psy_apply_mel_filterbank_32(struct psy_mel_filterbank *fb, struct icomplex32 *fft_out, + int32_t *power_spectra, int32_t *mel_log, int bitshift) +{ + psy_apply_mel_filterbank_with_linear_32(fb, fft_out, power_spectra, mel_log, NULL, bitshift); +} diff --git a/src/math/numbers.c b/src/math/numbers.c index df4f822c749a..129bc4f7e026 100644 --- a/src/math/numbers.c +++ b/src/math/numbers.c @@ -180,3 +180,4 @@ uint32_t crc32(uint32_t base, const void *data, uint32_t bytes) return ~crc; } +EXPORT_SYMBOL(crc32); diff --git a/src/math/pcan/CMakeLists.txt b/src/math/pcan/CMakeLists.txt new file mode 100644 index 000000000000..aafb9ca07640 --- /dev/null +++ b/src/math/pcan/CMakeLists.txt @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: BSD-3-Clause + +if(NOT DEFINED TFLM_PATH) + if(DEFINED SOF_ROOT_SOURCE_DIRECTORY AND EXISTS "${SOF_ROOT_SOURCE_DIRECTORY}/../tflite-micro") + set(TFLM_PATH "${SOF_ROOT_SOURCE_DIRECTORY}/../tflite-micro") + elseif(DEFINED sof_top_dir AND EXISTS "${sof_top_dir}/../tflite-micro") + set(TFLM_PATH "${sof_top_dir}/../tflite-micro") + elseif(EXISTS "${PROJECT_SOURCE_DIR}/../tflite-micro") + set(TFLM_PATH "${PROJECT_SOURCE_DIR}/../tflite-micro") + elseif(EXISTS "${CMAKE_CURRENT_LIST_DIR}/../../../../tflite-micro") + set(TFLM_PATH "${CMAKE_CURRENT_LIST_DIR}/../../../../tflite-micro") + endif() +endif() + +set(MICROFRONTEND_DIR ${TFLM_PATH}/tensorflow/lite/experimental/microfrontend/lib) + +set(base_files + pcan.c + ${MICROFRONTEND_DIR}/pcan_gain_control.c + ${MICROFRONTEND_DIR}/noise_reduction.c + ${MICROFRONTEND_DIR}/noise_reduction_util.c + ${MICROFRONTEND_DIR}/log_scale.c + ${MICROFRONTEND_DIR}/log_lut.c +) + +is_zephyr(zephyr) +if(zephyr) ### Zephyr ### + + zephyr_include_directories(${TFLM_PATH}) + zephyr_library_sources( + ${base_files} + ) + +else() ### library, e.g. testbench or plugin ### + + target_include_directories(sof PRIVATE ${TFLM_PATH}) + add_local_sources(sof ${base_files}) + +endif() diff --git a/src/math/pcan/README.md b/src/math/pcan/README.md new file mode 100644 index 000000000000..d038b733fa54 --- /dev/null +++ b/src/math/pcan/README.md @@ -0,0 +1,105 @@ +# Per-Channel AGC Normalization (PCAN) Math Library + +This directory contains the **PCAN (Per-Channel Automatic Gain Control Normalization)** library for Sound Open Firmware (SOF), integrating Google's upstream `microfrontend` library from [TFLite Micro](https://github.com/tensorflow/tflite-micro/tree/main/tensorflow/lite/experimental/microfrontend/lib) under the **Apache 2.0 license** with express patent grant protection. + +--- + +## 1. Overview & Mathematical Formulation + +PCAN applies per-channel adaptive dynamic gain control and root dynamic range compression across time to linear filterbank energies (e.g. Mel spectrogram bins), suppressing stationary background noise while enhancing transient acoustic events (speech onsets, keywords). + +``` + +-------------------------------------------------------------+ + | Input Filterbank Energy Matrix | + | E_in[channel, frame] | + +-------------------------------------------------------------+ + | + v ++---------------------------------------------------------------------------------------------+ +| PCAN Processing Stages | +| | +| 1. Temporal Noise Estimation (IIR Smoothing): | +| E_est[k] = ((E_in[k] << smoothing_bits)*alpha_s + E_est[k]*(1 - alpha_s)) >> 14 | +| | +| 2. Piecewise Quadratic Octave Gain Lookup: | +| gain[k] = WideDynamicFunction(E_est[k], gain_lut) | +| - Fast single-cycle CLZ/MSB (AE_NSAU on Tensilica HiFi) | +| - 10-bit fractional index quadratic interpolation | +| | +| 3. Dynamic Gain & Root Polynomial Compression: | +| SNR[k] = ((uint64_t)E_in[k] * gain[k]) >> snr_shift | +| E_out[k] = PcanShrink(SNR[k]) | +| - If SNR[k] < 8192 (2 << 12): SNR[k]^2 >> 20 | +| - If SNR[k] >= 8192: (SNR[k] >> 6) - 64 | ++---------------------------------------------------------------------------------------------+ + | + v + +-------------------------------------------------------------+ + | PCAN-Normalized Feature Tensor | + | E_out[channel, frame] | + +-------------------------------------------------------------+ +``` + +--- + +## 2. Dependencies + +The PCAN math library requires the following tools and repositories: + +| Dependency | Required Version | Description | +|---|---|---| +| **West Manifest (`west.yml`)** | $\ge 0.13$ | Pulls `tflite-micro` workspace dependency via `west update` | +| **TFLite-Micro** | Git revision `e86d97b6` | Upstream Google microfrontend C source files (`pcan_gain_control.c`, `noise_reduction.c`, `bits.h`) | +| **CMake** | $\ge 3.13$ | SOF build and configuration system | +| **Host Toolchain** | GCC $\ge 9.0$ / Clang $\ge 11.0$ | For building host testbench and CMocka unit tests | +| **DSP Toolchains** | Zephyr SDK / Xtensa XCC / Clang | For building target firmware with HiFi3 / HiFi4 / HiFi5 intrinsics | +| **CMocka** | Built with SOF | Unit testing framework for bit-exact validation | +| **GNU Octave** | $\ge 5.0$ | Reference modeling and golden test vector generation | + +--- + +## 3. Build & Test Instructions + +### 3.1 Synchronize Workspace via West +Ensure `tflite-micro` is pulled and synchronized in your workspace: +```bash +cd /path/to/sof-workspace +west update +``` + +### 3.2 Build and Run CMocka Unit Tests (Host) +Configure and run the 5-phase PCAN unit test suite on the host: +```bash +# Configure unit test build +cmake -S sof -B build_ut -DBUILD_UNIT_TESTS=ON -DBUILD_UNIT_TESTS_HOST=ON -DINIT_CONFIG=unit_test_defconfig + +# Build PCAN unit test binary +cmake --build build_ut --target pcan + +# Run PCAN test executable directly +./build_ut/test/cmocka/src/math/pcan/pcan + +# Or run via CTest with full math regression +ctest --test-dir build_ut -R "pcan|auditory|dct|matrix|window|fft" --output-on-failure +``` + +### 3.3 Regenerate Octave Golden Reference Vectors +To re-generate or verify golden test headers from the Octave reference suite: +```bash +cd test/cmocka/src/math/pcan +octave-cli --eval "ref_pcan" +``` +This updates `ref_pcan_lut.h`, `ref_pcan_func.h`, `ref_pcan_stream.h`, and `ref_pcan_corners.h`. + +### 3.4 Build Target Firmware (Zephyr / SOF) +When building SOF for a target DSP platform (e.g. Intel ACE15 / Meteor Lake / Arrow Lake): +```bash +west build -b intel_adsp_ace15_mtpm app +``` + +--- + +## 4. Kconfig & CMake Options + +- `CONFIG_MATH_PCAN`: Enables building the PCAN math library and links Google's microfrontend C source files. +- `CONFIG_COMP_MFCC`: Automatically selects `CONFIG_MATH_PCAN` when MFCC feature extraction is enabled. diff --git a/src/math/pcan/pcan.c b/src/math/pcan/pcan.c new file mode 100644 index 000000000000..e212a83e51fe --- /dev/null +++ b/src/math/pcan/pcan.c @@ -0,0 +1,234 @@ +// SPDX-License-Identifier: BSD-3-Clause +// +// Copyright(c) 2026 Intel Corporation. All rights reserved. +// +// Author: Antigravity AI & SOF Team + +#include +#include +#include +#include +#include +#include + +/* ln(2) in Q5.27: round(ln(2) * 2^27) */ +#define PCAN_LN2_Q27 93032640 + +int16_t pcan_gain_lookup_function(int32_t strength_q15, int32_t offset_q7, int32_t gain_bits, + int32_t input_bits, uint32_t x) +{ + uint64_t u64; + uint32_t u32; + uint32_t ln_u_q27; + int32_t ln_actual_q27; + int64_t s_ln; + int32_t exp_arg_q27; + int32_t exp_arg_ceiling; + int32_t gain_q20; + int32_t gain; + + /* u = x + offset * 2^input_bits, matches upstream's (x_as_float + offset) in fixed-point. */ + u64 = (uint64_t)x + (((uint64_t)offset_q7 << input_bits) >> 7); + if (u64 == 0) + u64 = 1; + u32 = (u64 > 0xFFFFFFFFu) ? 0xFFFFFFFFu : (uint32_t)u64; + + /* ln(u) as UQ5.27. */ + ln_u_q27 = ln_int32(u32); + + /* ln(x_as_float + offset) = ln(u) - input_bits * ln(2), in Q5.27. */ + ln_actual_q27 = (int32_t)ln_u_q27 - input_bits * PCAN_LN2_Q27; + + /* strength * ln(actual): Q1.15 * Q5.27 -> Q6.42, shift down 15 -> Q5.27. */ + s_ln = ((int64_t)strength_q15 * (int64_t)ln_actual_q27) >> 15; + + /* exp_arg = gain_bits * ln(2) - strength * ln(actual), Q5.27. */ + exp_arg_q27 = gain_bits * PCAN_LN2_Q27 - (int32_t)s_ln; + + /* exp(10.3972) = 32767.5, above this the int16 clamp always fires. + * Q5.27: round(10.3972 * 2^27) = 1395385005. + */ + exp_arg_ceiling = 1395385005; + if (exp_arg_q27 >= exp_arg_ceiling) + return INT16_MAX; + if (exp_arg_q27 <= -SOFM_EXP_FIXED_INPUT_MAX) + return 0; + + /* sofm_exp_fixed returns Q12.20 for input Q5.27 in [-16, +7.6246]. Above the + * upper input bound the output saturates. Handle the intermediate range + * [7.6246, 10.3972] with an explicit split so we still get an accurate value. + */ + if (exp_arg_q27 > SOFM_EXP_FIXED_INPUT_MAX) { + /* exp(a + b) = exp(a) * exp(b); pick b = 5.5 in Q5.27. */ + const int32_t half_q27 = 738197504; /* round(5.5 * 2^27) */ + const int32_t half_exp_q20 = 256590991; /* round(exp(5.5) * 2^20) */ + int64_t full_q40; + + gain_q20 = sofm_exp_fixed(exp_arg_q27 - half_q27); + /* Q12.20 * Q12.20 -> Q24.40. Do the >> 20 to Q(?)20 as int64. */ + full_q40 = (int64_t)gain_q20 * half_exp_q20; + /* Round to integer directly to avoid intermediate int32 overflow. */ + gain = (int32_t)((full_q40 + ((int64_t)1 << 39)) >> 40); + if (gain > INT16_MAX) + return INT16_MAX; + if (gain < 0) + return 0; + return (int16_t)gain; + } + + gain_q20 = sofm_exp_fixed(exp_arg_q27); + + /* Round to nearest integer (matching upstream: gain_as_float + 0.5f, then cast). */ + gain = (gain_q20 + (1 << 19)) >> 20; + if (gain > INT16_MAX) + return INT16_MAX; + if (gain < 0) + return 0; + return (int16_t)gain; +} + +int pcan_compute_lut(int32_t strength, int32_t offset, int32_t gain_bits, + int32_t input_bits, int16_t *gain_lut) +{ + int interval; + + if (!gain_lut) + return -EINVAL; + + memset(gain_lut, 0, PCAN_LUT_SIZE * sizeof(int16_t)); + + /* Layout matches upstream PcanGainControlPopulateState(): entries 0 and 1 + * hold the low-x samples, then for intervals 2..kWideDynamicFunctionBits + * the triplet (y0, a1, a2) is stored at (4 * interval - 6, -5, -4). + */ + gain_lut[0] = pcan_gain_lookup_function(strength, offset, gain_bits, input_bits, 0); + gain_lut[1] = pcan_gain_lookup_function(strength, offset, gain_bits, input_bits, 1); + + for (interval = 2; interval <= kWideDynamicFunctionBits; ++interval) { + const uint32_t x0 = (uint32_t)1 << (interval - 1); + const uint32_t x1 = x0 + (x0 >> 1); + const uint32_t x2 = (interval == kWideDynamicFunctionBits) ? + x0 + (x0 - 1) : 2 * x0; + const int16_t y0 = pcan_gain_lookup_function(strength, offset, gain_bits, + input_bits, x0); + const int16_t y1 = pcan_gain_lookup_function(strength, offset, gain_bits, + input_bits, x1); + const int16_t y2 = pcan_gain_lookup_function(strength, offset, gain_bits, + input_bits, x2); + const int32_t diff1 = (int32_t)y1 - y0; + const int32_t diff2 = (int32_t)y2 - y0; + const int32_t a1 = 4 * diff1 - diff2; + const int32_t a2 = diff2 - a1; + + gain_lut[4 * interval - 6] = y0; + gain_lut[4 * interval - 5] = (int16_t)a1; + gain_lut[4 * interval - 4] = (int16_t)a2; + } + + return 0; +} + +int pcan_populate_state(const struct pcan_config *config, struct pcan_state *state, + uint32_t *noise_estimate_buffer, int16_t *gain_lut_buffer, + int num_channels, uint16_t smoothing_bits, + int32_t input_correction_bits) +{ + int ret; + + if (!config || !state || num_channels <= 0) + return -EINVAL; + + memset(state, 0, sizeof(*state)); + state->enable_pcan = config->enable_pcan; + if (!state->enable_pcan) + return 0; + + state->num_channels = num_channels; + state->smoothing_bits = smoothing_bits; + state->snr_shift = config->gain_bits - input_correction_bits - PCAN_SNR_BITS; + if (state->snr_shift < 0) + return -EINVAL; + + if (noise_estimate_buffer) { + state->noise_estimate = noise_estimate_buffer; + } else { + state->noise_estimate = malloc(num_channels * sizeof(uint32_t)); + if (!state->noise_estimate) + return -ENOMEM; + state->allocated_noise = true; + } + memset(state->noise_estimate, 0, num_channels * sizeof(uint32_t)); + + if (gain_lut_buffer) { + state->gain_lut = gain_lut_buffer; + } else { + state->gain_lut = malloc(PCAN_LUT_SIZE * sizeof(int16_t)); + if (!state->gain_lut) { + pcan_free_state(state); + return -ENOMEM; + } + state->allocated_lut = true; + } + + ret = pcan_compute_lut(config->strength, config->offset, config->gain_bits, + (int32_t)smoothing_bits - input_correction_bits, + state->gain_lut); + if (ret < 0) { + pcan_free_state(state); + return ret; + } + + /* Mirror the SOF state into the upstream struct consumed by PcanGainControlApply(). */ + state->g_pcan.enable_pcan = 1; + state->g_pcan.noise_estimate = state->noise_estimate; + state->g_pcan.num_channels = num_channels; + state->g_pcan.gain_lut = state->gain_lut; + state->g_pcan.snr_shift = state->snr_shift; + + state->g_noise.estimate = state->noise_estimate; + state->g_noise.num_channels = num_channels; + state->g_noise.smoothing_bits = smoothing_bits; + state->g_noise.even_smoothing = 410; /* 0.025 * (1 << 14) */ + state->g_noise.odd_smoothing = 983; /* 0.06 * (1 << 14) */ + state->g_noise.min_signal_remaining = 819; /* 0.05 * (1 << 14) */ + + state->g_log_scale.enable_log = 1; + state->g_log_scale.scale_shift = 6; + + return 0; +} + +void pcan_free_state(struct pcan_state *state) +{ + if (!state) + return; + + if (state->allocated_noise) + free(state->noise_estimate); + if (state->allocated_lut) + free(state->gain_lut); + + memset(state, 0, sizeof(*state)); +} + +void pcan_reset(struct pcan_state *state) +{ + if (!state || !state->noise_estimate) + return; + + memset(state->noise_estimate, 0, state->num_channels * sizeof(uint32_t)); +} + +void pcan_log_scale(struct pcan_state *state, uint32_t *signal) +{ + int i; + uint16_t *scaled; + + if (!state || !state->enable_pcan) + return; + + scaled = LogScaleApply(&state->g_log_scale, signal, state->num_channels, + PCAN_INPUT_CORRECTION_BITS); + for (i = state->num_channels - 1; i >= 0; --i) + signal[i] = scaled[i]; +} diff --git a/test/cmocka/src/math/auditory/CMakeLists.txt b/test/cmocka/src/math/auditory/CMakeLists.txt index fe200e6b15eb..04b5feec01d2 100644 --- a/test/cmocka/src/math/auditory/CMakeLists.txt +++ b/test/cmocka/src/math/auditory/CMakeLists.txt @@ -9,4 +9,5 @@ cmocka_test(auditory ${PROJECT_SOURCE_DIR}/src/math/base2log.c ${PROJECT_SOURCE_DIR}/src/math/decibels.c ${PROJECT_SOURCE_DIR}/src/math/numbers.c + ${PROJECT_SOURCE_DIR}/src/math/sqrt_int32.c ) diff --git a/test/ztest/unit/math/advanced/pcan/CMakeLists.txt b/test/ztest/unit/math/advanced/pcan/CMakeLists.txt new file mode 100644 index 000000000000..f3bcb5af4910 --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/CMakeLists.txt @@ -0,0 +1,61 @@ +cmake_minimum_required(VERSION 3.20.0) + +find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) +project(test_math_advanced_pcan) + +set(SOF_ROOT "${PROJECT_SOURCE_DIR}/../../../../../..") + +# Set SOF top directory for UUID registry generation +set(sof_top_dir ${SOF_ROOT}) + +# Include SOF CMake utilities for proper SOF source compilation +include(${SOF_ROOT}/scripts/cmake/misc.cmake) +include(${SOF_ROOT}/scripts/cmake/uuid-registry.cmake) + +# Locate the tflite-micro checkout (west-managed in the SOF workspace) +if(NOT DEFINED TFLM_PATH) + if(EXISTS "${SOF_ROOT}/../tflite-micro") + set(TFLM_PATH "${SOF_ROOT}/../tflite-micro") + elseif(EXISTS "${SOF_ROOT}/../../tflite-micro") + set(TFLM_PATH "${SOF_ROOT}/../../tflite-micro") + endif() +endif() + +if(NOT DEFINED TFLM_PATH OR NOT EXISTS "${TFLM_PATH}") + message(FATAL_ERROR + "tflite-micro not found; expected next to the SOF workspace. " + "Set TFLM_PATH manually or run 'west update' to fetch it.") +endif() + +set(MICROFRONTEND_DIR ${TFLM_PATH}/tensorflow/lite/experimental/microfrontend/lib) + +target_include_directories(app PRIVATE + ${SOF_ROOT}/zephyr/include + ${SOF_ROOT}/src/include + ${SOF_ROOT}/src/platform/posix/include + ${SOF_ROOT}/test/cmocka/include + ${TFLM_PATH} + ${PROJECT_BINARY_DIR}/include/generated +) + +target_compile_definitions(app PRIVATE + -DCONFIG_ZEPHYR_POSIX=1 + -DCONFIG_LIBRARY=1 + -DUNIT_TEST=1 +) + +target_sources(app PRIVATE + pcan_test.c + ${SOF_ROOT}/src/math/pcan/pcan.c + ${SOF_ROOT}/src/math/log_e.c + ${SOF_ROOT}/src/math/base2log.c + ${SOF_ROOT}/src/math/exp_fcn.c + ${SOF_ROOT}/src/math/exp_fcn_hifi.c + ${MICROFRONTEND_DIR}/pcan_gain_control.c + ${MICROFRONTEND_DIR}/noise_reduction.c + ${MICROFRONTEND_DIR}/noise_reduction_util.c + ${MICROFRONTEND_DIR}/log_scale.c + ${MICROFRONTEND_DIR}/log_lut.c +) + +sof_append_relative_path_definitions(app) diff --git a/test/ztest/unit/math/advanced/pcan/pcan_gain_lookup.m b/test/ztest/unit/math/advanced/pcan/pcan_gain_lookup.m new file mode 100644 index 000000000000..68fc83f246b6 --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/pcan_gain_lookup.m @@ -0,0 +1,77 @@ +% pcan_gain_lookup - Compute PCAN continuous gain and generate LUT +% +% SPDX-License-Identifier: BSD-3-Clause +% Copyright(c) 2026 Intel Corporation. All rights reserved. + +function [gain_lut, y_lut] = pcan_gain_lookup(config, input_bits) +% Inputs: +% config.strength - Exponent alpha (e.g., 0.95) +% config.offset - Additive constant delta (e.g., 80.0) +% config.gain_bits - Scale factor exponent (e.g., 21) +% input_bits - smoothing_bits - input_correction_bits +% +% Outputs: +% gain_lut - 125-entry int16 lookup table for WideDynamicFunction +% y_lut - Raw function values at octave evaluation points + + if nargin < 2 + input_bits = 10; + end + + strength = config.strength; + offset = config.offset; + gain_bits = config.gain_bits; + + kWideDynamicFunctionBits = 32; + kWideDynamicFunctionLUTSize = 4 * kWideDynamicFunctionBits - 3; % 125 + + gain_lut = zeros(kWideDynamicFunctionLUTSize, 1, 'int16'); + + % Evaluate point x in gain function + function y = eval_gain(x_val) + x_float = double(x_val) / double(bitshift(uint64(1), input_bits)); + g_float = double(bitshift(uint64(1), gain_bits)) * ((x_float + offset) ^ (-strength)); + if g_float > 32767 + y = int16(32767); + else + y = int16(round(g_float)); + end + end + + gain_lut(1) = eval_gain(0); + gain_lut(2) = eval_gain(1); + + % Intervals 2 through 32 + % In C: lut is offset by -6 so that interval 2 writes to lut[4*2]=lut[8] -> offset 2 in array + for interval = 2:kWideDynamicFunctionBits + x0 = bitshift(uint64(1), interval - 1); + x1 = x0 + bitshift(x0, -1); + if interval == kWideDynamicFunctionBits + x2 = x0 + (x0 - 1); + else + x2 = 2 * x0; + end + + y0 = int32(eval_gain(x0)); + y1 = int32(eval_gain(x1)); + y2 = int32(eval_gain(x2)); + + diff1 = y1 - y0; + diff2 = y2 - y0; + a1 = 4 * diff1 - diff2; + a2 = diff2 - a1; + + % Map to 1-based index in gain_lut: + % In C: index is 4 * interval - 6 (0-based) -> +1 for 1-based + idx = 4 * interval - 5; + + gain_lut(idx) = int16(y0); + gain_lut(idx + 1) = int16(a1); + gain_lut(idx + 2) = int16(a2); + if interval < kWideDynamicFunctionBits + gain_lut(idx + 3) = int16(0); + end + end + + y_lut = gain_lut; +end diff --git a/test/ztest/unit/math/advanced/pcan/pcan_noise_estimate.m b/test/ztest/unit/math/advanced/pcan/pcan_noise_estimate.m new file mode 100644 index 000000000000..b9f340de52df --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/pcan_noise_estimate.m @@ -0,0 +1,37 @@ +% pcan_noise_estimate - Octave fixed-point model of PCAN temporal IIR noise smoothing +% +% SPDX-License-Identifier: BSD-3-Clause +% Copyright(c) 2026 Intel Corporation. All rights reserved. + +function [estimate_out] = pcan_noise_estimate(estimate_in, signal_in, smoothing_coef, smoothing_bits, coef_bits) +% Inputs: +% estimate_in - Previous noise estimate vector (uint32) +% signal_in - Current frame input energy vector (uint32) +% smoothing_coef - IIR smoothing factor in Q(coef_bits) (default 819 for 0.05 in Q14) +% smoothing_bits - Scale shift for input energy (default 10) +% coef_bits - Number of fractional bits in smoothing_coef (default 14) +% +% Output: +% estimate_out - Updated noise estimate vector (uint32) + + if nargin < 3 + smoothing_coef = 819; % ~0.05 in Q14 (16384 * 0.05 = 819.2) + end + if nargin < 4 + smoothing_bits = 10; + end + if nargin < 5 + coef_bits = 14; + end + + one_minus_coef = bitshift(1, coef_bits) - smoothing_coef; + num_channels = length(signal_in); + estimate_out = zeros(num_channels, 1, 'uint32'); + + for i = 1:num_channels + sig_scaled = bitshift(uint64(signal_in(i)), smoothing_bits); + est_prev = uint64(estimate_in(i)); + est_new = bitshift((sig_scaled * uint64(smoothing_coef)) + (est_prev * uint64(one_minus_coef)), -coef_bits); + estimate_out(i) = uint32(est_new); + end +end diff --git a/test/ztest/unit/math/advanced/pcan/pcan_process.m b/test/ztest/unit/math/advanced/pcan/pcan_process.m new file mode 100644 index 000000000000..d853c117da36 --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/pcan_process.m @@ -0,0 +1,55 @@ +% pcan_process - Octave model of full PCAN frame processing +% +% SPDX-License-Identifier: BSD-3-Clause +% Copyright(c) 2026 Intel Corporation. All rights reserved. + +function [output_frames, final_noise_estimate] = pcan_process(input_frames, config, smoothing_bits, input_correction_bits) +% Inputs: +% input_frames - [num_channels x num_frames] matrix of uint32 filterbank energies +% config.strength - Exponent alpha (e.g. 0.95) +% config.offset - Additive constant delta (e.g. 80.0) +% config.gain_bits - Gain bit shift (e.g. 21) +% config.smoothing_coef - Smoothing factor in Q14 (e.g. 819) +% smoothing_bits - Smoothing bit shift (e.g. 10) +% input_correction_bits - Input correction shift (e.g. 0) +% +% Outputs: +% output_frames - [num_channels x num_frames] matrix of uint32 PCAN normalized outputs +% final_noise_estimate - [num_channels x 1] final noise estimate state + + if nargin < 3 + smoothing_bits = 10; + end + if nargin < 4 + input_correction_bits = 0; + end + + [num_channels, num_frames] = size(input_frames); + input_bits = smoothing_bits - input_correction_bits; + kPcanSnrBits = 12; + snr_shift = config.gain_bits - input_correction_bits - kPcanSnrBits; + + [gain_lut, ~] = pcan_gain_lookup(config, input_bits); + + noise_estimate = zeros(num_channels, 1, 'uint32'); + output_frames = zeros(num_channels, num_frames, 'uint32'); + + for f = 1:num_frames + sig_in = input_frames(:, f); + + % 1. Update temporal noise estimate + noise_estimate = pcan_noise_estimate(noise_estimate, sig_in, config.smoothing_coef, smoothing_bits, 14); + + % 2. Apply PCAN gain control per channel + frame_out = zeros(num_channels, 1, 'uint32'); + for c = 1:num_channels + gain = pcan_wide_dynamic_func(noise_estimate(c), gain_lut); + snr = bitshift(uint64(sig_in(c)) * uint64(uint16(gain)), -snr_shift); + frame_out(c) = pcan_shrink(uint32(snr), 12, 6); + end + + output_frames(:, f) = frame_out; + end + + final_noise_estimate = noise_estimate; +end diff --git a/test/ztest/unit/math/advanced/pcan/pcan_shrink.m b/test/ztest/unit/math/advanced/pcan/pcan_shrink.m new file mode 100644 index 000000000000..2ebd98736cc9 --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/pcan_shrink.m @@ -0,0 +1,41 @@ +% pcan_shrink - Octave fixed-point model of PcanShrink piecewise compression +% +% SPDX-License-Identifier: BSD-3-Clause +% Copyright(c) 2026 Intel Corporation. All rights reserved. + +function y = pcan_shrink(x, snr_bits, output_bits) +% Inputs: +% x - 32-bit unsigned SNR input value (scalar or vector) +% snr_bits - Number of fractional bits in SNR (default 12) +% output_bits - Number of fractional bits in output (default 6) +% +% Output: +% y - 32-bit unsigned compressed output value + + if nargin < 2 + snr_bits = 12; + end + if nargin < 3 + output_bits = 6; + end + + threshold = bitshift(uint64(2), snr_bits); % 2 << 12 = 8192 + quadratic_shift = -(2 + 2 * snr_bits - output_bits); % -20 + linear_shift = -(snr_bits - output_bits); % -6 + linear_offset = uint64(bitshift(1, output_bits)); % 64 + + y = zeros(size(x), 'uint32'); + + for k = 1:numel(x) + val = uint64(x(k)); + if val < threshold + % Quadratic compression: x^2 / 4 + prod_val = val * val; + res = bitshift(prod_val, quadratic_shift); + else + % Linear compression: x - 1 + res = bitshift(val, linear_shift) - linear_offset; + end + y(k) = uint32(res); + end +end diff --git a/test/ztest/unit/math/advanced/pcan/pcan_test.c b/test/ztest/unit/math/advanced/pcan/pcan_test.c new file mode 100644 index 000000000000..eb7873e542aa --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/pcan_test.c @@ -0,0 +1,173 @@ +// SPDX-License-Identifier: BSD-3-Clause +// +// Copyright(c) 2026 Intel Corporation. All rights reserved. +// +// These contents may have been developed with support from one or more Intel-operated +// generative artificial intelligence solutions. +// +// Converted from cmocka to Ztest +// Original: test/cmocka/src/math/pcan/pcan_test.c + +#include +#include +#include +#include + +#include + +#include "ref_pcan_lut.h" +#include "ref_pcan_func.h" +#include "ref_pcan_stream.h" +#include "ref_pcan_corners.h" + +/* The SOF PCAN core computes the gain LUT in fixed-point (ln_int32 + + * sofm_exp_fixed) while the Octave reference uses double-precision powf. + * The two agree to within a couple of LSBs on the sampled y-values, but the + * quadratic slope terms a1 = 4*(y1-y0) - (y2-y0) and a2 = -a1 + (y2-y0) + * amplify per-sample rounding by up to ~6x, so allow a bigger LUT tolerance. + */ +#define PCAN_TEST_LSB_TOL 2 +#define PCAN_TEST_LUT_TOL 6 + +#define zassert_int_near(actual, expected, tol) \ + do { \ + long long _a = (long long)(actual); \ + long long _e = (long long)(expected); \ + long long _d = _a - _e; \ + \ + if (_d < 0) \ + _d = -_d; \ + zassert_true(_d <= (long long)(tol), \ + "value %lld deviates from reference %lld by %lld (tol %lld)", \ + _a, _e, _d, (long long)(tol)); \ + } while (0) + +ZTEST(pcan_suite, test_pcan_lut_generation) +{ + int16_t lut[PCAN_LUT_SIZE]; + int ret; + int i; + + ret = pcan_compute_lut(31130, 10240, 21, 10, lut); + zassert_equal(ret, 0); + + for (i = 0; i < PCAN_TEST_LUT1_SIZE; i++) + zassert_int_near(lut[i], ref_pcan_lut1[i], PCAN_TEST_LUT_TOL); + + ret = pcan_compute_lut(26214, 6400, 18, 12, lut); + zassert_equal(ret, 0); + + for (i = 0; i < PCAN_TEST_LUT2_SIZE; i++) + zassert_int_near(lut[i], ref_pcan_lut2[i], PCAN_TEST_LUT_TOL); +} + +ZTEST(pcan_suite, test_pcan_wide_dynamic_function) +{ + int16_t lut[PCAN_LUT_SIZE]; + int16_t out; + int ret; + int i; + + ret = pcan_compute_lut(31130, 10240, 21, 10, lut); + zassert_equal(ret, 0); + + for (i = 0; i < PCAN_TEST_WDF_NUM_POINTS; i++) { + out = pcan_wide_dynamic_function(ref_pcan_wdf_inputs[i], lut); + zassert_int_near(out, ref_pcan_wdf_outputs[i], PCAN_TEST_LSB_TOL); + } +} + +ZTEST(pcan_suite, test_pcan_shrink) +{ + uint32_t out; + int i; + + for (i = 0; i < PCAN_TEST_SHRINK_NUM_POINTS; i++) { + out = pcan_shrink(ref_pcan_shrink_inputs[i]); + zassert_equal(out, ref_pcan_shrink_outputs[i]); + } +} + +ZTEST(pcan_suite, test_pcan_streaming) +{ + struct pcan_config cfg; + struct pcan_state pstate; + uint32_t channel_data[PCAN_STREAM_NUM_CHANNELS]; + int ret; + int f; + int c; + + cfg.strength = 31130; /* 0.95 in Q1.15 */ + cfg.offset = 10240; /* 80.0 in Q8.7 */ + cfg.gain_bits = 21; + cfg.smoothing_coef = PCAN_STREAM_SMOOTHING_COEF; + cfg.smoothing_bits = PCAN_STREAM_SMOOTHING_BITS; + cfg.input_correction_bits = PCAN_STREAM_INPUT_CORRECTION_BITS; + cfg.enable_pcan = true; + + ret = pcan_populate_state(&cfg, &pstate, NULL, NULL, + PCAN_STREAM_NUM_CHANNELS, + PCAN_STREAM_SMOOTHING_BITS, + PCAN_STREAM_INPUT_CORRECTION_BITS); + zassert_equal(ret, 0); + + for (f = 0; f < PCAN_STREAM_NUM_FRAMES; f++) { + for (c = 0; c < PCAN_STREAM_NUM_CHANNELS; c++) + channel_data[c] = ref_pcan_stream_inputs[f * PCAN_STREAM_NUM_CHANNELS + c]; + + pcan_noise_reduction(&pstate, channel_data); + pcan_apply(&pstate, channel_data); + pcan_log_scale(&pstate, channel_data); + } + + for (c = 0; c < PCAN_STREAM_NUM_CHANNELS; c++) + zassert_true(pstate.noise_estimate[c] > 0, "noise estimate should be positive"); + + pcan_reset(&pstate); + for (c = 0; c < PCAN_STREAM_NUM_CHANNELS; c++) + zassert_equal(pstate.noise_estimate[c], 0); + + pcan_free_state(&pstate); +} + +ZTEST(pcan_suite, test_pcan_corner_cases) +{ + int16_t lut[PCAN_LUT_SIZE]; + struct pcan_config bad_cfg; + struct pcan_state bad_state; + int16_t wdf_out; + uint32_t shrink_out; + int ret; + int i; + + ret = pcan_compute_lut(31130, 10240, 21, 10, lut); + zassert_equal(ret, 0); + + for (i = 0; i < PCAN_CORNERS_NUM_POINTS; i++) { + wdf_out = pcan_wide_dynamic_function(ref_pcan_corner_inputs[i], lut); + zassert_int_near(wdf_out, ref_pcan_corner_wdf_outputs[i], PCAN_TEST_LSB_TOL); + + shrink_out = pcan_shrink(ref_pcan_corner_inputs[i]); + zassert_equal(shrink_out, ref_pcan_corner_shrink_outputs[i]); + } + + /* gain_bits too small -> negative snr_shift */ + bad_cfg.strength = 31130; /* 0.95 in Q1.15 */ + bad_cfg.offset = 10240; /* 80.0 in Q8.7 */ + bad_cfg.gain_bits = 5; + bad_cfg.smoothing_coef = 819; + bad_cfg.smoothing_bits = 10; + bad_cfg.input_correction_bits = 0; + bad_cfg.enable_pcan = true; + + ret = pcan_populate_state(&bad_cfg, &bad_state, NULL, NULL, 16, 10, 0); + zassert_true(ret < 0); + + ret = pcan_populate_state(NULL, &bad_state, NULL, NULL, 16, 10, 0); + zassert_true(ret < 0); + + ret = pcan_populate_state(&bad_cfg, &bad_state, NULL, NULL, 0, 10, 0); + zassert_true(ret < 0); +} + +ZTEST_SUITE(pcan_suite, NULL, NULL, NULL, NULL, NULL); diff --git a/test/ztest/unit/math/advanced/pcan/pcan_wide_dynamic_func.m b/test/ztest/unit/math/advanced/pcan/pcan_wide_dynamic_func.m new file mode 100644 index 000000000000..1ecf32041efb --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/pcan_wide_dynamic_func.m @@ -0,0 +1,56 @@ +% pcan_wide_dynamic_func - Octave fixed-point model of WideDynamicFunction +% +% SPDX-License-Identifier: BSD-3-Clause +% Copyright(c) 2026 Intel Corporation. All rights reserved. + +function y = pcan_wide_dynamic_func(x, gain_lut) +% Inputs: +% x - 32-bit unsigned input value (scalar or vector) +% gain_lut - 125-entry int16 lookup table from pcan_gain_lookup +% +% Output: +% y - 16-bit signed interpolated gain factor (same shape as x) + + y = zeros(size(x), 'int16'); + + for k = 1:numel(x) + val = uint32(x(k)); + if val <= 2 + % Directly return lut[0], lut[1], or lut[2] + y(k) = gain_lut(val + 1); + else + % Compute MSB (1 to 32) + clz_val = 0; + tmp = val; + for b = 31:-1:0 + if bitand(tmp, bitshift(uint32(1), b)) ~= 0 + break; + end + clz_val = clz_val + 1; + end + interval = 32 - clz_val; + + % In C: lut pointer is offset by (4 * interval - 6) + % 1-based index for lut[0]: + idx = 4 * interval - 5; + l0 = int32(gain_lut(idx)); + l1 = int32(gain_lut(idx + 1)); + l2 = int32(gain_lut(idx + 2)); + + if interval < 11 + frac = bitand(bitshift(val, 11 - interval), uint32(1023)); % 0x3FF + else + frac = bitand(bitshift(val, -(interval - 11)), uint32(1023)); + end + frac_i32 = int32(frac); + + res = bitshift(l2 * frac_i32, -5); + res = res + bitshift(l1, 5); + res = res * frac_i32; + res = bitshift(res + 16384, -15); % (1 << 14) = 16384 + res = res + l0; + + y(k) = int16(res); + end + end +end diff --git a/test/ztest/unit/math/advanced/pcan/prj.conf b/test/ztest/unit/math/advanced/pcan/prj.conf new file mode 100644 index 000000000000..d34c7781cd0a --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/prj.conf @@ -0,0 +1,2 @@ +CONFIG_ZTEST=y +CONFIG_SOF_FULL_ZEPHYR_APPLICATION=n diff --git a/test/ztest/unit/math/advanced/pcan/ref_pcan.m b/test/ztest/unit/math/advanced/pcan/ref_pcan.m new file mode 100644 index 000000000000..865d52757840 --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/ref_pcan.m @@ -0,0 +1,212 @@ +% ref_pcan - Generate C header files for PCAN library unit tests +% +% SPDX-License-Identifier: BSD-3-Clause +% Copyright(c) 2026 Intel Corporation. All rights reserved. + +function ref_pcan() + % Add path to cmocka helper export functions + path(path(), '../../../m'); + + try + opt.describe = export_get_git_describe(); + catch + opt.describe = 'SOF PCAN Reference Generator'; + end + + %% Phase 1: Export Golden LUTs for default and custom configurations + export_ref_lut(opt); + + %% Phase 2 & 3: Export Golden values for WideDynamicFunction and PcanShrink + export_ref_functions(opt); + + %% Phase 4: Export Streaming Multi-Channel Multi-Frame Test Vectors + export_ref_streaming(opt); + + %% Phase 5: Export Corner & Edge Cases + export_ref_corner_cases(opt); + + fprintf(1, 'All PCAN test headers exported successfully.\n'); +end + +function export_ref_lut(opt) + header_fn = 'ref_pcan_lut.h'; + fh = export_headerfile_open(header_fn); + export_comment(fh, sprintf('Generated by ref_pcan.m (%s)', opt.describe)); + + % Config 1: Default TFLM configuration + cfg1.strength = 0.95; + cfg1.offset = 80.0; + cfg1.gain_bits = 21; + input_bits1 = 10; + [lut1, ~] = pcan_gain_lookup(cfg1, input_bits1); + + export_ndefine(fh, 'PCAN_TEST_LUT1_SIZE', length(lut1)); + export_ndefine(fh, 'PCAN_TEST_LUT1_GAIN_BITS', cfg1.gain_bits); + export_ndefine(fh, 'PCAN_TEST_LUT1_INPUT_BITS', input_bits1); + export_vector(fh, 16, 'ref_pcan_lut1', lut1); + + % Config 2: Custom configuration (strength=0.8, offset=50.0, gain_bits=18) + cfg2.strength = 0.8; + cfg2.offset = 50.0; + cfg2.gain_bits = 18; + input_bits2 = 12; + [lut2, ~] = pcan_gain_lookup(cfg2, input_bits2); + + export_ndefine(fh, 'PCAN_TEST_LUT2_SIZE', length(lut2)); + export_ndefine(fh, 'PCAN_TEST_LUT2_GAIN_BITS', cfg2.gain_bits); + export_ndefine(fh, 'PCAN_TEST_LUT2_INPUT_BITS', input_bits2); + export_vector(fh, 16, 'ref_pcan_lut2', lut2); + + fclose(fh); + fprintf(1, 'Exported %s.\n', header_fn); +end + +function export_ref_functions(opt) + header_fn = 'ref_pcan_func.h'; + fh = export_headerfile_open(header_fn); + export_comment(fh, sprintf('Generated by ref_pcan.m (%s)', opt.describe)); + + cfg.strength = 0.95; + cfg.offset = 80.0; + cfg.gain_bits = 21; + input_bits = 10; + [lut, ~] = pcan_gain_lookup(cfg, input_bits); + + % 1. WideDynamicFunction Test Vector: Test various points across all 32 intervals + wdf_inputs = uint32([ ... + 0, 1, 2, 3, 4, 5, 7, 8, 15, 16, 31, 32, 63, 64, 127, 128, ... + 255, 256, 511, 512, 1023, 1024, 2047, 2048, 4095, 4096, 8191, 8192, ... + 16383, 16384, 32767, 32768, 65535, 65536, 131071, 131072, ... + 262143, 262144, 524287, 524288, 1048575, 1048576, 2097151, 2097152, ... + 4194303, 4194304, 8388607, 8388608, 16777215, 16777216, ... + 33554431, 33554432, 67108863, 67108864, 134217727, 134217728, ... + 268435455, 268435456, 536870911, 536870912, 1073741823, 1073741824, ... + 2147483647, 2147483648, 4294967295 ... + ]); + wdf_outputs = pcan_wide_dynamic_func(wdf_inputs, lut); + + export_ndefine(fh, 'PCAN_TEST_WDF_NUM_POINTS', length(wdf_inputs)); + export_uint32_vector(fh, 'ref_pcan_wdf_inputs', wdf_inputs); + export_vector(fh, 16, 'ref_pcan_wdf_outputs', wdf_outputs); + + % 2. PcanShrink Test Vector: Sweep below, around (8192), and above threshold + shrink_inputs = uint32([ ... + 0, 1, 10, 100, 500, 1000, 2000, 4000, 8000, 8190, 8191, 8192, 8193, 8194, ... + 10000, 16384, 32768, 65536, 100000, 500000, 1000000, 10000000 ... + ]); + shrink_outputs = pcan_shrink(shrink_inputs, 12, 6); + + export_ndefine(fh, 'PCAN_TEST_SHRINK_NUM_POINTS', length(shrink_inputs)); + export_uint32_vector(fh, 'ref_pcan_shrink_inputs', shrink_inputs); + export_uint32_vector(fh, 'ref_pcan_shrink_outputs', shrink_outputs); + + fclose(fh); + fprintf(1, 'Exported %s.\n', header_fn); +end + +function export_ref_streaming(opt) + header_fn = 'ref_pcan_stream.h'; + fh = export_headerfile_open(header_fn); + export_comment(fh, sprintf('Generated by ref_pcan.m (%s)', opt.describe)); + + cfg.strength = 0.95; + cfg.offset = 80.0; + cfg.gain_bits = 21; + cfg.smoothing_coef = 819; % 0.05 in Q14 + smoothing_bits = 10; + input_correction_bits = 0; + + num_channels = 16; + num_frames = 20; + + % Create deterministic synthetic test signal: + % Baseline background noise + mid-stream bursts + rng(42); + input_matrix = zeros(num_channels, num_frames, 'uint32'); + for f = 1:num_frames + for c = 1:num_channels + noise = 50 + mod(c * 17 + f * 23, 100); + if f >= 5 && f <= 12 && c >= 4 && c <= 10 + speech_burst = 2000 + (c * 150); + else + speech_burst = 0; + end + input_matrix(c, f) = uint32(noise + speech_burst); + end + end + + [output_matrix, final_noise] = pcan_process(input_matrix, cfg, smoothing_bits, input_correction_bits); + + export_ndefine(fh, 'PCAN_STREAM_NUM_CHANNELS', num_channels); + export_ndefine(fh, 'PCAN_STREAM_NUM_FRAMES', num_frames); + export_ndefine(fh, 'PCAN_STREAM_SMOOTHING_COEF', cfg.smoothing_coef); + export_ndefine(fh, 'PCAN_STREAM_SMOOTHING_BITS', smoothing_bits); + export_ndefine(fh, 'PCAN_STREAM_INPUT_CORRECTION_BITS', input_correction_bits); + + input_linear = reshape(input_matrix, [], 1); + output_linear = reshape(output_matrix, [], 1); + + export_uint32_vector(fh, 'ref_pcan_stream_inputs', input_linear); + export_uint32_vector(fh, 'ref_pcan_stream_outputs', output_linear); + export_uint32_vector(fh, 'ref_pcan_stream_final_noise', final_noise); + + fclose(fh); + fprintf(1, 'Exported %s.\n', header_fn); +end + +function export_ref_corner_cases(opt) + header_fn = 'ref_pcan_corners.h'; + fh = export_headerfile_open(header_fn); + export_comment(fh, sprintf('Generated by ref_pcan.m (%s)', opt.describe)); + + cfg.strength = 0.95; + cfg.offset = 80.0; + cfg.gain_bits = 21; + input_bits = 10; + [lut, ~] = pcan_gain_lookup(cfg, input_bits); + + % Corner case points: zeros, boundaries, transitions, overflows + corner_inputs = uint32([ ... + 0, ... + 1, ... + 2, ... + 3, ... + 4, ... + 2047, 2048, 2049, ... + 8191, 8192, 8193, ... + 65535, 65536, 65537, ... + 1073741823, 1073741824, 1073741825, ... + 2147483647, 2147483648, 2147483649, ... + 4294967294, 4294967295 ... + ]); + + wdf_corner_outs = pcan_wide_dynamic_func(corner_inputs, lut); + shrink_corner_outs = pcan_shrink(corner_inputs, 12, 6); + + export_ndefine(fh, 'PCAN_CORNERS_NUM_POINTS', length(corner_inputs)); + export_uint32_vector(fh, 'ref_pcan_corner_inputs', corner_inputs); + export_vector(fh, 16, 'ref_pcan_corner_wdf_outputs', wdf_corner_outs); + export_uint32_vector(fh, 'ref_pcan_corner_shrink_outputs', shrink_corner_outs); + + fclose(fh); + fprintf(1, 'Exported %s.\n', header_fn); +end + +function export_uint32_vector(fh, vname, data) + columns = 6; + rows = ceil(length(data) / columns); + fprintf(fh, '\nstatic const uint32_t %s[%d] = {\n', vname, length(data)); + i = 1; + for j = 1:rows + fprintf(fh, '\t%11uU,', data(i)); + i = i + 1; + for k = 2:columns + if i <= length(data) + fprintf(fh, ' %11uU,', data(i)); + i = i + 1; + end + end + fprintf(fh, '\n'); + end + fprintf(fh, '};\n'); +end diff --git a/test/ztest/unit/math/advanced/pcan/ref_pcan_corners.h b/test/ztest/unit/math/advanced/pcan/ref_pcan_corners.h new file mode 100644 index 000000000000..8fa1852b4222 --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/ref_pcan_corners.h @@ -0,0 +1,28 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * + * Copyright(c) 2026 Intel Corporation. + */ + +/* Generated by ref_pcan.m (v1.9-rc1-7901-g9500fa321) */ + +#define PCAN_CORNERS_NUM_POINTS 22 + +static const uint32_t ref_pcan_corner_inputs[22] = { + 0U, 1U, 2U, 3U, 4U, 2047U, + 2048U, 2049U, 8191U, 8192U, 8193U, 65535U, + 65536U, 65537U, 1073741823U, 1073741824U, 1073741825U, 2147483647U, + 2147483648U, 2147483649U, 4294967294U, 4294967295U, +}; + +static const int16_t ref_pcan_corner_wdf_outputs[22] = { + 32636, 32635, 32635, 32635, 32634, 31879, 31879, 31879, 29812, 29811, + 29811, 18676, 18672, 18672, 4, 4, 4, 2, 2, 2, + 1, 1, +}; + +static const uint32_t ref_pcan_corner_shrink_outputs[22] = { + 0U, 0U, 0U, 0U, 0U, 3U, + 4U, 4U, 63U, 64U, 64U, 959U, + 960U, 960U, 16777151U, 16777152U, 16777152U, 33554367U, + 33554368U, 33554368U, 67108799U, 67108799U, +}; diff --git a/test/ztest/unit/math/advanced/pcan/ref_pcan_func.h b/test/ztest/unit/math/advanced/pcan/ref_pcan_func.h new file mode 100644 index 000000000000..f86dfb415d6f --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/ref_pcan_func.h @@ -0,0 +1,47 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * + * Copyright(c) 2026 Intel Corporation. + */ + +/* Generated by ref_pcan.m (v1.9-rc1-7901-g9500fa321) */ + +#define PCAN_TEST_WDF_NUM_POINTS 65 + +static const uint32_t ref_pcan_wdf_inputs[65] = { + 0U, 1U, 2U, 3U, 4U, 5U, + 7U, 8U, 15U, 16U, 31U, 32U, + 63U, 64U, 127U, 128U, 255U, 256U, + 511U, 512U, 1023U, 1024U, 2047U, 2048U, + 4095U, 4096U, 8191U, 8192U, 16383U, 16384U, + 32767U, 32768U, 65535U, 65536U, 131071U, 131072U, + 262143U, 262144U, 524287U, 524288U, 1048575U, 1048576U, + 2097151U, 2097152U, 4194303U, 4194304U, 8388607U, 8388608U, + 16777215U, 16777216U, 33554431U, 33554432U, 67108863U, 67108864U, + 134217727U, 134217728U, 268435455U, 268435456U, 536870911U, 536870912U, + 1073741823U, 1073741824U, 2147483647U, 2147483648U, 4294967295U, +}; + +static const int16_t ref_pcan_wdf_outputs[65] = { + 32636, 32635, 32635, 32635, 32634, 32634, 32634, 32633, 32630, 32630, + 32624, 32624, 32612, 32612, 32587, 32587, 32539, 32539, 32443, 32443, + 32253, 32253, 31879, 31879, 31159, 31158, 29812, 29811, 27448, 27446, + 23710, 23707, 18676, 18672, 13169, 13166, 8351, 8348, 4876, 4874, + 2698, 2697, 1446, 1446, 762, 762, 398, 398, 207, 207, + 107, 107, 56, 56, 29, 29, 15, 15, 8, 8, + 4, 4, 2, 2, 1, +}; +#define PCAN_TEST_SHRINK_NUM_POINTS 22 + +static const uint32_t ref_pcan_shrink_inputs[22] = { + 0U, 1U, 10U, 100U, 500U, 1000U, + 2000U, 4000U, 8000U, 8190U, 8191U, 8192U, + 8193U, 8194U, 10000U, 16384U, 32768U, 65536U, + 100000U, 500000U, 1000000U, 10000000U, +}; + +static const uint32_t ref_pcan_shrink_outputs[22] = { + 0U, 0U, 0U, 0U, 0U, 0U, + 3U, 15U, 61U, 63U, 63U, 64U, + 64U, 64U, 92U, 192U, 448U, 960U, + 1498U, 7748U, 15561U, 156186U, +}; diff --git a/test/ztest/unit/math/advanced/pcan/ref_pcan_lut.h b/test/ztest/unit/math/advanced/pcan/ref_pcan_lut.h new file mode 100644 index 000000000000..6736041146cc --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/ref_pcan_lut.h @@ -0,0 +1,45 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * + * Copyright(c) 2026 Intel Corporation. + */ + +/* Generated by ref_pcan.m (v1.9-rc1-7901-g9500fa321) */ + +#define PCAN_TEST_LUT1_SIZE 125 +#define PCAN_TEST_LUT1_GAIN_BITS 21 +#define PCAN_TEST_LUT1_INPUT_BITS 10 + +static const int16_t ref_pcan_lut1[125] = { + 32636, 32635, 32635, 1, -2, 0, 32634, 1, -2, 0, + 32633, -5, 2, 0, 32630, -6, 0, 0, 32624, -12, + 0, 0, 32612, -23, -2, 0, 32587, -48, 0, 0, + 32539, -96, 0, 0, 32443, -190, 0, 0, 32253, -378, + 4, 0, 31879, -739, 18, 0, 31158, -1409, 62, 0, + 29811, -2567, 202, 0, 27446, -4301, 562, 0, 23707, -6265, + 1230, 0, 18672, -7458, 1952, 0, 13166, -7030, 2212, 0, + 8348, -5342, 1868, 0, 4874, -3459, 1282, 0, 2697, -2025, + 774, 0, 1446, -1120, 436, 0, 762, -596, 232, 0, + 398, -313, 122, 0, 207, -164, 64, 0, 107, -85, + 34, 0, 56, -45, 18, 0, 29, -22, 8, 0, + 15, -13, 6, 0, 8, -8, 4, 0, 4, -2, + 0, 0, 2, -3, 2, +}; +#define PCAN_TEST_LUT2_SIZE 125 +#define PCAN_TEST_LUT2_GAIN_BITS 18 +#define PCAN_TEST_LUT2_INPUT_BITS 12 + +static const int16_t ref_pcan_lut2[125] = { + 11465, 11465, 11465, 0, 0, 0, 11465, -3, 2, 0, + 11464, 0, 0, 0, 11464, 1, -2, 0, 11463, 1, + -2, 0, 11462, -5, 2, 0, 11459, -6, 0, 0, + 11453, -9, -2, 0, 11442, -25, 2, 0, 11419, -47, + 2, 0, 11374, -91, 2, 0, 11285, -178, 4, 0, + 11111, -341, 10, 0, 10780, -637, 38, 0, 10181, -1116, + 116, 0, 9181, -1749, 286, 0, 7718, -2315, 526, 0, + 5929, -2478, 700, 0, 4151, -2156, 696, 0, 2691, -1588, + 552, 0, 1655, -1047, 378, 0, 986, -647, 238, 0, + 577, -386, 144, 0, 335, -226, 84, 0, 193, -130, + 48, 0, 111, -77, 30, 0, 64, -45, 18, 0, + 37, -24, 8, 0, 21, -15, 6, 0, 12, -7, + 2, 0, 7, -5, 2, +}; diff --git a/test/ztest/unit/math/advanced/pcan/ref_pcan_stream.h b/test/ztest/unit/math/advanced/pcan/ref_pcan_stream.h new file mode 100644 index 000000000000..1960909baa6f --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/ref_pcan_stream.h @@ -0,0 +1,132 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * + * Copyright(c) 2026 Intel Corporation. + */ + +/* Generated by ref_pcan.m (v1.9-rc1-7901-g9500fa321) */ + +#define PCAN_STREAM_NUM_CHANNELS 16 +#define PCAN_STREAM_NUM_FRAMES 20 +#define PCAN_STREAM_SMOOTHING_COEF 819 +#define PCAN_STREAM_SMOOTHING_BITS 10 +#define PCAN_STREAM_INPUT_CORRECTION_BITS 0 + +static const uint32_t ref_pcan_stream_inputs[320] = { + 90U, 107U, 124U, 141U, 58U, 75U, + 92U, 109U, 126U, 143U, 60U, 77U, + 94U, 111U, 128U, 145U, 113U, 130U, + 147U, 64U, 81U, 98U, 115U, 132U, + 149U, 66U, 83U, 100U, 117U, 134U, + 51U, 68U, 136U, 53U, 70U, 87U, + 104U, 121U, 138U, 55U, 72U, 89U, + 106U, 123U, 140U, 57U, 74U, 91U, + 59U, 76U, 93U, 110U, 127U, 144U, + 61U, 78U, 95U, 112U, 129U, 146U, + 63U, 80U, 97U, 114U, 82U, 99U, + 116U, 2733U, 2800U, 2967U, 3134U, 3301U, + 3468U, 3635U, 52U, 69U, 86U, 103U, + 120U, 137U, 105U, 122U, 139U, 2656U, + 2823U, 2990U, 3157U, 3324U, 3491U, 3558U, + 75U, 92U, 109U, 126U, 143U, 60U, + 128U, 145U, 62U, 2679U, 2846U, 3013U, + 3180U, 3347U, 3414U, 3581U, 98U, 115U, + 132U, 149U, 66U, 83U, 51U, 68U, + 85U, 2702U, 2869U, 3036U, 3103U, 3270U, + 3437U, 3604U, 121U, 138U, 55U, 72U, + 89U, 106U, 74U, 91U, 108U, 2725U, + 2892U, 2959U, 3126U, 3293U, 3460U, 3627U, + 144U, 61U, 78U, 95U, 112U, 129U, + 97U, 114U, 131U, 2748U, 2815U, 2982U, + 3149U, 3316U, 3483U, 3550U, 67U, 84U, + 101U, 118U, 135U, 52U, 120U, 137U, + 54U, 2671U, 2838U, 3005U, 3172U, 3339U, + 3406U, 3573U, 90U, 107U, 124U, 141U, + 58U, 75U, 143U, 60U, 77U, 2694U, + 2861U, 3028U, 3195U, 3262U, 3429U, 3596U, + 113U, 130U, 147U, 64U, 81U, 98U, + 66U, 83U, 100U, 117U, 134U, 51U, + 68U, 85U, 102U, 119U, 136U, 53U, + 70U, 87U, 104U, 121U, 89U, 106U, + 123U, 140U, 57U, 74U, 91U, 108U, + 125U, 142U, 59U, 76U, 93U, 110U, + 127U, 144U, 112U, 129U, 146U, 63U, + 80U, 97U, 114U, 131U, 148U, 65U, + 82U, 99U, 116U, 133U, 50U, 67U, + 135U, 52U, 69U, 86U, 103U, 120U, + 137U, 54U, 71U, 88U, 105U, 122U, + 139U, 56U, 73U, 90U, 58U, 75U, + 92U, 109U, 126U, 143U, 60U, 77U, + 94U, 111U, 128U, 145U, 62U, 79U, + 96U, 113U, 81U, 98U, 115U, 132U, + 149U, 66U, 83U, 100U, 117U, 134U, + 51U, 68U, 85U, 102U, 119U, 136U, + 104U, 121U, 138U, 55U, 72U, 89U, + 106U, 123U, 140U, 57U, 74U, 91U, + 108U, 125U, 142U, 59U, 127U, 144U, + 61U, 78U, 95U, 112U, 129U, 146U, + 63U, 80U, 97U, 114U, 131U, 148U, + 65U, 82U, +}; + +static const uint32_t ref_pcan_stream_outputs[320] = { + 28U, 39U, 51U, 65U, 12U, 19U, + 29U, 40U, 53U, 67U, 13U, 21U, + 30U, 42U, 54U, 68U, 39U, 50U, + 62U, 12U, 21U, 30U, 40U, 52U, + 64U, 13U, 22U, 31U, 42U, 53U, + 8U, 14U, 50U, 8U, 13U, 21U, + 32U, 41U, 51U, 8U, 14U, 22U, + 33U, 42U, 52U, 9U, 16U, 23U, + 9U, 15U, 21U, 31U, 42U, 52U, + 9U, 16U, 22U, 32U, 44U, 53U, + 10U, 17U, 25U, 33U, 16U, 24U, + 31U, 922U, 936U, 949U, 979U, 1006U, + 1013U, 1036U, 6U, 11U, 17U, 26U, + 35U, 43U, 25U, 33U, 40U, 574U, + 597U, 604U, 617U, 628U, 631U, 628U, + 13U, 18U, 26U, 35U, 45U, 8U, + 34U, 43U, 7U, 421U, 432U, 435U, + 442U, 450U, 444U, 456U, 21U, 27U, + 35U, 44U, 9U, 14U, 5U, 9U, + 14U, 336U, 346U, 350U, 345U, 351U, + 355U, 361U, 30U, 36U, 6U, 10U, + 16U, 22U, 10U, 15U, 21U, 283U, + 288U, 280U, 285U, 287U, 289U, 292U, + 39U, 6U, 11U, 16U, 23U, 30U, + 17U, 23U, 29U, 240U, 234U, 236U, + 240U, 242U, 244U, 241U, 8U, 12U, + 18U, 24U, 32U, 4U, 25U, 31U, + 4U, 199U, 203U, 205U, 209U, 213U, + 210U, 215U, 14U, 19U, 26U, 32U, + 5U, 9U, 33U, 5U, 9U, 176U, + 181U, 185U, 189U, 185U, 189U, 192U, + 21U, 26U, 34U, 6U, 11U, 16U, + 6U, 10U, 15U, 0U, 0U, 0U, + 0U, 0U, 0U, 0U, 28U, 4U, + 7U, 11U, 17U, 23U, 12U, 17U, + 22U, 0U, 0U, 0U, 0U, 0U, + 0U, 0U, 5U, 8U, 13U, 17U, + 24U, 30U, 18U, 23U, 29U, 0U, + 0U, 0U, 0U, 0U, 0U, 0U, + 10U, 14U, 19U, 24U, 3U, 6U, + 25U, 3U, 6U, 0U, 0U, 0U, + 0U, 0U, 0U, 0U, 16U, 21U, + 26U, 4U, 7U, 11U, 4U, 7U, + 11U, 0U, 0U, 0U, 0U, 0U, + 0U, 0U, 22U, 28U, 5U, 8U, + 13U, 17U, 9U, 13U, 17U, 0U, + 1U, 0U, 0U, 0U, 0U, 0U, + 3U, 6U, 9U, 13U, 19U, 24U, + 14U, 19U, 23U, 0U, 0U, 0U, + 0U, 0U, 0U, 0U, 7U, 10U, + 15U, 19U, 26U, 4U, 20U, 25U, + 4U, 0U, 0U, 0U, 0U, 0U, + 0U, 0U, 12U, 16U, 21U, 26U, + 5U, 8U, +}; + +static const uint32_t ref_pcan_stream_final_noise[16] = { + 65089U, 66549U, 66741U, 658990U, 693317U, 727673U, + 763723U, 799477U, 833963U, 863004U, 61280U, 65959U, + 67716U, 69176U, 63373U, 64115U, +}; diff --git a/test/ztest/unit/math/advanced/pcan/testcase.yaml b/test/ztest/unit/math/advanced/pcan/testcase.yaml new file mode 100644 index 000000000000..cca40819399c --- /dev/null +++ b/test/ztest/unit/math/advanced/pcan/testcase.yaml @@ -0,0 +1,16 @@ +# SPDX-License-Identifier: BSD-3-Clause +# +# Copyright(c) 2026 Intel Corporation. All rights reserved. +# +# PCAN (Per-Channel AGC Normalization) unit tests for Ztest framework +# + +tests: + sof.unit.math.advanced.pcan: + tags: + - math + - pcan + platform_allow: native_sim + integration_platforms: + - native_sim + build_only: false From 8321358f5753c16d47f148701581d400eb359fa6 Mon Sep 17 00:00:00 2001 From: Seppo Ingalsuo Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 09/31] audio: mfcc: add 8-bit PCAN and soft AGC Mel feature extraction modes Extend the MFCC component with selectable output data types at setup, including 8-bit PCAN normalization and 8-bit soft AGC (AGC8) Mel spectrum output modes used by microWakeWord topologies. Signed-off-by: Seppo Ingalsuo --- src/audio/mfcc/CMakeLists.txt | 20 +++- src/audio/mfcc/Kconfig | 23 ++++ src/audio/mfcc/README.md | 104 +++++++++++++--- src/audio/mfcc/llext/CMakeLists.txt | 1 + src/audio/mfcc/mfcc.c | 72 ++++++++++- src/audio/mfcc/mfcc_agc8.c | 71 +++++++++++ src/audio/mfcc/mfcc_common.c | 159 ++++++++++++++++--------- src/audio/mfcc/mfcc_setup.c | 90 ++++++++++++++ src/audio/mfcc/tune/setup_mfcc.m | 127 +++++++++++++++++--- src/include/sof/audio/mfcc/mfcc_agc8.h | 68 +++++++++++ src/include/sof/audio/mfcc/mfcc_comp.h | 29 ++++- src/include/sof/audio/mfcc/mfcc_vad.h | 8 +- src/include/user/mfcc.h | 15 ++- 13 files changed, 684 insertions(+), 103 deletions(-) create mode 100644 src/audio/mfcc/mfcc_agc8.c create mode 100644 src/include/sof/audio/mfcc/mfcc_agc8.h diff --git a/src/audio/mfcc/CMakeLists.txt b/src/audio/mfcc/CMakeLists.txt index 274c7aa05eb8..3ad5f39fcdfd 100644 --- a/src/audio/mfcc/CMakeLists.txt +++ b/src/audio/mfcc/CMakeLists.txt @@ -1,10 +1,28 @@ # SPDX-License-Identifier: BSD-3-Clause +if(CONFIG_COMP_MFCC_PCAN) + if(NOT DEFINED TFLM_PATH) + if(DEFINED SOF_ROOT_SOURCE_DIRECTORY AND EXISTS "${SOF_ROOT_SOURCE_DIRECTORY}/../tflite-micro") + set(TFLM_PATH "${SOF_ROOT_SOURCE_DIRECTORY}/../tflite-micro") + elseif(DEFINED sof_top_dir AND EXISTS "${sof_top_dir}/../tflite-micro") + set(TFLM_PATH "${sof_top_dir}/../tflite-micro") + elseif(EXISTS "${CMAKE_CURRENT_LIST_DIR}/../../../../tflite-micro") + set(TFLM_PATH "${CMAKE_CURRENT_LIST_DIR}/../../../../tflite-micro") + endif() + endif() + is_zephyr(zephyr) + if(zephyr) + zephyr_include_directories(${TFLM_PATH}) + else() + target_include_directories(sof PRIVATE ${TFLM_PATH}) + endif() +endif() + if(CONFIG_COMP_MFCC STREQUAL "m" AND DEFINED CONFIG_LLEXT) add_subdirectory(llext ${PROJECT_BINARY_DIR}/mfcc_llext) add_dependencies(app mfcc) else() - add_local_sources(sof mfcc.c mfcc_setup.c mfcc_common.c mfcc_generic.c mfcc_hifi4.c mfcc_hifi3.c mfcc_vad.c) + add_local_sources(sof mfcc.c mfcc_setup.c mfcc_common.c mfcc_generic.c mfcc_hifi4.c mfcc_hifi3.c mfcc_vad.c mfcc_agc8.c) if(CONFIG_IPC_MAJOR_4) add_local_sources(sof mfcc_ipc4.c) endif() diff --git a/src/audio/mfcc/Kconfig b/src/audio/mfcc/Kconfig index f56cadb40de2..1faa74998e72 100644 --- a/src/audio/mfcc/Kconfig +++ b/src/audio/mfcc/Kconfig @@ -24,3 +24,26 @@ config COMP_MFCC The characteristic of the audio features are defined in the binary control blob. Directory tools/tune/mfcc contains a tool to create the configurations. + +if COMP_MFCC + +config COMP_MFCC_PCAN + bool "Enable PCAN (Per-Channel AGC Normalization) in MFCC" + default n + select MATH_PCAN + help + Select to build MFCC with PCAN (Per-Channel Automatic Gain Control + Normalization) support on the Mel filterbank energies. PCAN performs + dynamic per-channel gain control and piecewise polynomial root + compression to suppress stationary noise and enhance transients, + producing normalized features suitable for direct int8 quantization + downstream (e.g. microWakeWord). The topology PCAN configuration + fields are ignored when this option is disabled. + +config COMP_MFCC_DEBUG_TRACE + bool "Verbose per-process debug traces in MFCC" + default n + help + Enable MFCC per-process debug prints in the hot path. + +endif # COMP_MFCC diff --git a/src/audio/mfcc/README.md b/src/audio/mfcc/README.md index 31f9c331e545..6c7f598110a9 100644 --- a/src/audio/mfcc/README.md +++ b/src/audio/mfcc/README.md @@ -1,25 +1,99 @@ -# MFCC Feature Extraction Architecture +# MFCC & PCAN Feature Extraction Architecture -This directory contains the Mel-Frequency Cepstral Coefficients (MFCC) feature extractor. +This directory contains the **Mel-Frequency Cepstral Coefficients (MFCC)** feature extractor and integrated **PCAN (Per-Channel AGC Normalization)** audio pre-processing component for Sound Open Firmware (SOF). -## Overview +--- -MFCC extracts audio features commonly used as inputs for machine learning models, such as wake-word detection or speech recognition. +## 1. Overview -## Architecture Diagram +The MFCC module converts raw streaming time-domain PCM audio into compact acoustic feature representations (e.g. 13-bin cepstral coefficients, 40-bin or 80-bin Mel spectrograms) suitable for on-device machine learning models such as wake-word classifiers (TFLM, microWakeWord) and speech recognition engines (Whisper). + +When enabled, **PCAN** applies per-channel adaptive dynamic gain control and piecewise root dynamic range compression across time to suppress stationary background noise and normalize channel energy before feature quantization. + +### Output modes + +One build supports all output modes, selected at runtime by the configuration blob: + +| Mode | Blob settings | Output per hop | +|---|---|---| +| Cepstral coefficients | `num_ceps > 0` | int16 Q9.7 widened to int32 | +| Mel log spectra | `num_ceps == 0` | int32 Q9.23 | +| PCAN Mel | `num_ceps == 0`, `enable_pcan` (needs `CONFIG_COMP_MFCC_PCAN`) | int8 | +| Soft AGC Mel (AGC8) | `num_ceps == 0`, `enable_agc8` | int8 Q1.7 | + +AGC8 is a light alternative to PCAN without the per-channel noise estimate and the `tflite-micro` dependency. A single gain is added to all Q9.23 Mel log values of a hop. The gain attacks instantly to keep the hop peak at or below +1.0, and releases towards a target with a slower step when the VAD reports speech. The values are clamped to -1.0 .. +1.0 and converted to int8 Q1.7. The blob fields `agc_target`, `agc_floor` (Q8.7) and `agc_release`, `agc_release_speech` (Q9.23 per hop) set the parameters, zero selects the default. + +--- + +## 2. Architecture & Data Flow ```mermaid graph LR - In[Audio Frame] --> Win[Windowing] - Win --> FFT[FFT] - FFT --> Mel[Mel Filterbank] - Mel --> DCT[DCT] - DCT --> Out[MFCC Output Features] + In[Audio PCM Frame] --> Win[Windowing: Hamming/Hann] + Win --> FFT[FFT: 512-pt] + FFT --> Mel[Mel Filterbank: 40/80 Bins] + Mel --> PCAN[PCAN Gain Normalization] + PCAN --> Log[Log Scaling / dB] + Log --> VAD[VAD / DTX Silence Gating] + Log --> AGC8[Soft AGC int8] + VAD --> AGC8 + Log --> DCT[DCT: Cepstral Matrix] + DCT --> Lifter[Cepstral Lifter] + Lifter --> Out[MFCC Output Features] +``` + +--- + +## 3. Dependencies + +| Dependency | Purpose | +|---|---| +| **West Manifest (`west.yml`)** | Manages workspace dependencies including `tflite-micro` | +| **`tflite-micro`** | Provides Google's upstream Apache-2.0 `microfrontend` PCAN library (`pcan_gain_control.c`, `noise_reduction.c`) | +| **GNU Octave ($\ge 5.0$)** | Required for topology configuration generation (`tune/setup_mfcc.m`) and reference vector export | +| **CMake ($\ge 3.13$)** | SOF build system | +| **Zephyr SDK / Xtensa XCC** | DSP cross-compilation toolchains for Cadence HiFi3 / HiFi4 SIMD kernels | +| **CMocka** | Host unit testing framework | + +--- + +## 4. Build & Tuning Instructions + +### 4.1 Synchronize Dependencies via West +```bash +west update +``` + +### 4.2 Build Host Unit Tests +```bash +# Configure unit tests +cmake -S sof -B build_ut -DBUILD_UNIT_TESTS=ON -DBUILD_UNIT_TESTS_HOST=ON -DINIT_CONFIG=unit_test_defconfig + +# Build all math and MFCC tests +cmake --build build_ut --target pcan +ctest --test-dir build_ut -R "pcan|auditory|dct|matrix|window|fft" --output-on-failure ``` -## Configuration and Scripts +### 4.3 Build Target DSP Firmware +```bash +west build -b intel_adsp_ace15_mtpm app +``` + +### 4.4 Generate Topology Configurations (Octave) +The tuning script generates binary configuration blobs and ALSA topology configurations: +```bash +cd src/audio/mfcc/tune +octave-cli --eval "setup_mfcc" +``` +Available presets generated: +- `ceps13_compress_dtx.conf`: 13-bin cepstral features with VAD and DTX silence suppression. +- `mel80_compress.conf`: 80-bin linear Mel spectrogram features. +- `mel80_compress_dtx.conf`: 80-bin Mel spectrogram with DTX gating. +- `mel80_pcan_compress.conf`: 80-bin Mel spectrogram with Google PCAN dynamic AGC normalization. + +--- + +## 5. Configuration Options -- **Kconfig**: Enables the MFCC component (`COMP_MFCC`) which selects necessary math libraries (`MATH_FFT`, `MATH_DCT`, `MATH_16BIT_MEL_FILTERBANK`, etc.). Depends on `COMP_MODULE_ADAPTER`. -- **CMakeLists.txt**: Compiles generic, common, and HIFI implementations (`mfcc_hifi3.c`, `mfcc_hifi4.c`). Provides support for Zephyr loadable extensions (`llext`). -- **mfcc.toml**: Specifies the topology configuration for the MFCC module (UUID, affinity, memory parameters, and pin formats). -- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/mfcc.conf`, configuring a `mfcc` widget object of type `effect` with UUID `73:a7:10:db:a4:1a:ea:4c:a2:1f:2d:57:a5:c9:82:eb`. +- **`CONFIG_COMP_MFCC`**: Enables the MFCC component and automatically selects required math libraries (`CONFIG_MATH_FFT`, `CONFIG_MATH_AUDITORY`, `CONFIG_MATH_DCT`, `CONFIG_MATH_PCAN`, `CONFIG_MATH_WINDOW`). +- **`CONFIG_COMP_MODULE_ADAPTER`**: Module adapter infrastructure for SOF processing components. diff --git a/src/audio/mfcc/llext/CMakeLists.txt b/src/audio/mfcc/llext/CMakeLists.txt index 688342751d75..0032f469c1ef 100644 --- a/src/audio/mfcc/llext/CMakeLists.txt +++ b/src/audio/mfcc/llext/CMakeLists.txt @@ -8,5 +8,6 @@ sof_llext_build("mfcc" ../mfcc_generic.c ../mfcc_hifi3.c ../mfcc_hifi4.c + ../mfcc_agc8.c LIB openmodules ) diff --git a/src/audio/mfcc/mfcc.c b/src/audio/mfcc/mfcc.c index 945c77c6d613..0827b1ef6788 100644 --- a/src/audio/mfcc/mfcc.c +++ b/src/audio/mfcc/mfcc.c @@ -32,11 +32,19 @@ #include #include #include +#if CONFIG_COMP_MFCC_DEBUG_TRACE +#include +#endif LOG_MODULE_REGISTER(mfcc, CONFIG_SOF_LOG_LEVEL); SOF_DEFINE_REG_UUID(mfcc); +#if CONFIG_COMP_MFCC_DEBUG_TRACE +static uint32_t last_mfcc_cycle; +static uint32_t mfcc_call_count; +#endif + /** \brief Source/sink API based source copy function map. */ struct mfcc_source_func_map { uint8_t source_fmt; @@ -161,6 +169,13 @@ static int mfcc_process(struct processing_module *mod, size_t source_avail; int frames; int num_ceps; +#if CONFIG_COMP_MFCC_DEBUG_TRACE + uint32_t now = k_cycle_get_32(); + uint32_t delta_cycles = now - last_mfcc_cycle; + + last_mfcc_cycle = now; + mfcc_call_count++; +#endif comp_dbg(dev, "start"); @@ -171,23 +186,47 @@ static int mfcc_process(struct processing_module *mod, * can continue while the previous period is drained. */ pending = state->header_pending || state->out_remain > 0; - if (cd->config->compress_output && pending) - return mfcc_process_output(mod, cd, sources, sinks, 0, 0); + if (cd->config->compress_output && pending) { + int ret = mfcc_process_output(mod, cd, sources, sinks, 0, 0); + +#if CONFIG_COMP_MFCC_DEBUG_TRACE + comp_info(dev, "[MFCC proc %u] delta=%u us (pending retry, ret=%d)", + mfcc_call_count, k_cyc_to_us_near32(delta_cycles), ret); +#endif + return ret; + } source_avail = source_get_data_frames_available(sources[0]); frames = MIN(source_avail, cd->max_frames); - if (!frames) + if (!frames) { +#if CONFIG_COMP_MFCC_DEBUG_TRACE + comp_info(dev, "[MFCC proc %u] delta=%u us (no frames, avail=%zu)", + mfcc_call_count, k_cyc_to_us_near32(delta_cycles), source_avail); +#endif return 0; + } /* Copy input audio from source to MFCC internal circular buffer */ cd->source_func(sources[0], &state->buf, &state->emph, frames, state->source_channel); /* Run STFT and Mel/DCT processing */ num_ceps = mfcc_stft_process(mod, cd); - if (num_ceps < 0) + if (num_ceps < 0) { +#if CONFIG_COMP_MFCC_DEBUG_TRACE + comp_info(dev, "[MFCC proc %u] delta=%u us stft error %d", + mfcc_call_count, k_cyc_to_us_near32(delta_cycles), num_ceps); +#endif return num_ceps; + } + + int ret = mfcc_process_output(mod, cd, sources, sinks, num_ceps, frames); - return mfcc_process_output(mod, cd, sources, sinks, num_ceps, frames); +#if CONFIG_COMP_MFCC_DEBUG_TRACE + comp_info(dev, "[MFCC proc %u] delta=%u us avail=%zu frames=%d ceps=%d ret=%d", + mfcc_call_count, k_cyc_to_us_near32(delta_cycles), + source_avail, frames, num_ceps, ret); +#endif + return ret; } /** @@ -243,12 +282,29 @@ static int mfcc_prepare(struct processing_module *mod, * in the processing code, so require it to be at least that large. */ if (cd->config && data_size >= sizeof(struct sof_mfcc_config)) { - ret = mfcc_setup(mod, dev->frames + 4, audio_stream_get_rate(&sourceb->stream), + uint32_t src_rate = audio_stream_get_rate(&sourceb->stream); + int max_frames; + + if (dev->frames < cd->config->frame_shift) + dev->frames = cd->config->frame_shift; + + max_frames = dev->frames + 4; + + ret = mfcc_setup(mod, max_frames, src_rate, audio_stream_get_channels(&sourceb->stream)); if (ret < 0) { comp_err(dev, "setup failed."); return ret; } + + /* Set DP scheduling period from FFT hop cadence; sink rate is + * not yet propagated at prepare time so module_adapter cannot + * derive it from mod->sinks[]. + */ + if (src_rate && cd->state.fft.fft_hop_size) + dev->period = (uint32_t)(1000000ULL * + cd->state.fft.fft_hop_size / + src_rate); } else { comp_err(dev, "configuration is missing."); return -EINVAL; @@ -308,6 +364,10 @@ static int mfcc_reset(struct processing_module *mod) /* Reset to similar state as init() */ cd->source_func = NULL; +#if CONFIG_COMP_MFCC_DEBUG_TRACE + last_mfcc_cycle = 0; + mfcc_call_count = 0; +#endif return 0; } diff --git a/src/audio/mfcc/mfcc_agc8.c b/src/audio/mfcc/mfcc_agc8.c new file mode 100644 index 000000000000..854977372111 --- /dev/null +++ b/src/audio/mfcc/mfcc_agc8.c @@ -0,0 +1,71 @@ +// SPDX-License-Identifier: BSD-3-Clause +// +// Copyright(c) 2026 Intel Corporation. +// +// Author: Seppo Ingalsuo + +/** + * \file mfcc_agc8.c + * \brief Soft AGC and int8 quantization of MFCC Mel log spectra. + */ + +#include +#include +#include +#include + +#define MFCC_AGC8_CLIP_MAX_Q23 (1 << 23) +#define MFCC_AGC8_CLIP_MIN_Q23 (-(1 << 23)) + +void mfcc_agc8_init(struct mfcc_agc8 *agc, const struct sof_mfcc_config *config) +{ + /* Blob target and floor are Q8.7, release steps are Q9.23 */ + agc->target = config->agc_target ? (int32_t)config->agc_target << 16 : + MFCC_AGC8_TARGET_Q23; + agc->floor = config->agc_floor ? (int32_t)config->agc_floor << 16 : + MFCC_AGC8_FLOOR_Q23; + agc->release = config->agc_release ? config->agc_release : + MFCC_AGC8_RELEASE_Q23; + agc->release_speech = config->agc_release_speech ? config->agc_release_speech : + MFCC_AGC8_RELEASE_SPEECH_Q23; + agc->gain = agc->target; +} + +void mfcc_agc8_process(struct mfcc_agc8 *agc, const int32_t *mel, int8_t *out, int n, + bool speech) +{ + int32_t peak = mel[0]; + int32_t gain; + int32_t v; + int i; + + for (i = 1; i < n; i++) { + if (mel[i] > peak) + peak = mel[i]; + } + + /* Attack: instantly keep the hop peak at or below +1.0 */ + if (agc->gain > MFCC_AGC8_CLIP_MAX_Q23 - peak) + agc->gain = MFCC_AGC8_CLIP_MAX_Q23 - peak; + if (agc->gain < agc->floor) + agc->gain = agc->floor; + + gain = agc->gain; + for (i = 0; i < n; i++) { + v = mel[i] + gain; + if (v > MFCC_AGC8_CLIP_MAX_Q23) + v = MFCC_AGC8_CLIP_MAX_Q23; + else if (v < MFCC_AGC8_CLIP_MIN_Q23) + v = MFCC_AGC8_CLIP_MIN_Q23; + + v = Q_SHIFT_RND(v, 23, 7); + out[i] = (int8_t)(v > INT8_MAX ? INT8_MAX : v); + } + + /* Release towards target, with a slower step during speech */ + if (agc->gain < agc->target) { + agc->gain += speech ? agc->release_speech : agc->release; + if (agc->gain > agc->target) + agc->gain = agc->target; + } +} diff --git a/src/audio/mfcc/mfcc_common.c b/src/audio/mfcc/mfcc_common.c index cd082cae5ebf..db7d9ff4981e 100644 --- a/src/audio/mfcc/mfcc_common.c +++ b/src/audio/mfcc/mfcc_common.c @@ -13,6 +13,9 @@ #include #include #include +#if CONFIG_COMP_MFCC_PCAN +#include +#endif #include #include #include @@ -352,8 +355,51 @@ int mfcc_stft_process(struct processing_module *mod, struct mfcc_comp_data *cd) * to add the missing "gain". */ mel_scale_shift = input_shift - fft->fft_plan->len; + +#if CONFIG_COMP_MFCC_PCAN + if (state->pcan.enable_pcan) { + psy_apply_mel_filterbank_with_linear_32(&state->melfb, fft->fft_out, + state->power_spectra, state->mel_log_32, + state->mel_linear, mel_scale_shift); + pcan_noise_reduction(&state->pcan, state->mel_linear); + pcan_apply(&state->pcan, state->mel_linear); + pcan_log_scale(&state->pcan, state->mel_linear); + + /* Throttled data-flow trace: linear Mel energy and noise + * estimate after PCAN to confirm the detector input is + * not pinned to the floor. + */ + { + static uint32_t pcan_dbg; + int nb = state->pcan.num_channels; + + if ((pcan_dbg++ % 32) == 1) { + uint32_t mel_max = 0; + uint64_t mel_sum = 0; + uint32_t ne0 = state->pcan.noise_estimate ? + state->pcan.noise_estimate[0] : 0; + int b; + + for (b = 0; b < nb; b++) { + uint32_t v = state->mel_linear[b]; + + mel_sum += v; + mel_max = MAX(mel_max, v); + } + if (mel_max > 0 || (pcan_dbg % 4096) == 1) + comp_dbg(dev, + "pcan[%u] bins=%d mel_max=%u mel_sum=%u noise0=%u", + pcan_dbg, nb, mel_max, (uint32_t)mel_sum, ne0); + } + } + } else { + psy_apply_mel_filterbank_32(&state->melfb, fft->fft_out, state->power_spectra, + state->mel_log_32, mel_scale_shift); + } +#else psy_apply_mel_filterbank_32(&state->melfb, fft->fft_out, state->power_spectra, state->mel_log_32, mel_scale_shift); +#endif if (state->mel_only) { /* In Mel-only mode output Mel log spectra directly */ @@ -419,7 +465,7 @@ int mfcc_stft_process(struct processing_module *mod, struct mfcc_comp_data *cd) /* Use hop counter for frame numbering (independent of VAD enable) */ state->header.frame_number = state->hop_count; - /* Run VAD on the mel log spectrum (available in both modes) */ + /* Run VAD on the scaled mel log spectrum (available in both modes) */ if (config->enable_vad) { mfcc_vad_update(&cd->vad, state->mel_log_32); @@ -497,16 +543,52 @@ static void mfcc_prepare_output(struct mfcc_state *state, int num_ceps) if (num_ceps <= 0) return; - /* Copy into out_stage so the next STFT hop may freely reuse - * mel_log_32 / cepstral_coef while this frame is still pending. - */ - if (state->mel_only) { + switch (state->out_mode) { +#if CONFIG_COMP_MFCC_PCAN + case MFCC_OUT_MEL8_PCAN: + { + int8_t *out8 = (int8_t *)state->out_stage; + + /* In PCAN mode mel_linear[] is indexed by k < num_ceps. + * num_ceps must not exceed the number of Mel bins or we + * read past the end of the Mel filterbank array. + */ + if (num_ceps > state->melfb.mel_bins) + return; + + for (k = 0; k < num_ceps; k++) { + /* Map PCAN log-scaled output (~0..666) to int8 [-128..127] */ + int32_t val = (int32_t)state->mel_linear[k]; + + val = ((val * 256) + 333) / 666 - 128; + if (val > 127) + val = 127; + else if (val < -128) + val = -128; + + out8[k] = (int8_t)val; + } + break; + } +#endif + case MFCC_OUT_MEL8_AGC: + mfcc_agc8_process(&state->agc8, state->mel_log_32, (int8_t *)state->out_stage, + num_ceps, state->header.vad_flag != 0); + break; + case MFCC_OUT_MEL32: + /* Copy into out_stage so the next STFT hop may freely reuse + * mel_log_32 / cepstral_coef while this frame is still pending. + */ for (k = 0; k < num_ceps; k++) state->out_stage[k] = state->mel_log_32[k]; - } else { + break; + case MFCC_OUT_CEPS: /* Widen int16 Q9.7 cepstral coefficients to int32 Q9.23. */ for (k = 0; k < num_ceps; k++) state->out_stage[k] = (int32_t)state->cepstral_coef->data[k] << 16; + break; + default: + return; } state->out_data_ptr = state->out_stage; @@ -519,9 +601,8 @@ static void mfcc_prepare_output(struct mfcc_state *state, int num_ceps) * * Writes the pending data header (if any) followed by the pending * int32_t Mel/cepstral payload into the sink as a contiguous blob, - * without zero padding. When VAD + DTX are enabled, suppresses silence - * frames after a configurable trailing-silence count and optionally - * sends periodic keep-alive silence updates. + * without zero padding. Every prepared hop is committed. VAD must not + * drop frames: the downstream streaming detector runs continuously. * * \param[in,out] mod Processing module. * \param[in,out] cd MFCC component data. @@ -543,50 +624,15 @@ static int mfcc_output_compress(struct processing_module *mod, struct mfcc_comp_ uint8_t *dst; int ret; bool pending; - bool send_periodic; pending = state->header_pending || state->out_remain > 0; if (!pending) return 0; - if (num_ceps > 0 && cd->config->enable_vad && !cd->vad.is_speech) { - state->vad_silence_count++; - /* With DTX enabled, send trailing silence frames - * (configurable count) then suppress. After trailing - * frames, optionally send periodic silence updates - * at the configured interval. This gives the host - * enough silence to detect end-of-speech while - * keeping alive updates during long silence. - * Without DTX, output every frame regardless of VAD. - */ - if (cd->config->enable_dtx && - state->vad_silence_count > state->dtx_trailing_silence) { - send_periodic = false; - - /* Check periodic silence frame send */ - if (state->dtx_silence_interval > 0) { - state->dtx_silence_counter++; - if (state->dtx_silence_counter >= - state->dtx_silence_interval) { - state->dtx_silence_counter = 0; - send_periodic = true; - } - } - - if (!send_periodic) { - /* Suppress this frame */ - state->header_pending = false; - state->out_remain = 0; - return 0; - } - } - } else { - state->vad_silence_count = 0; - state->dtx_silence_counter = 0; - } + size_t sample_size = mfcc_out_sample_size(state); out_bytes = (state->header_pending ? sizeof(state->header) : 0) + - state->out_remain * sizeof(int32_t); + state->out_remain * sample_size; if (out_bytes == 0) return 0; @@ -609,7 +655,7 @@ static int mfcc_output_compress(struct processing_module *mod, struct mfcc_comp_ if (state->out_remain > 0) { mfcc_sink_write_bytes(&dst, sink_start, sink_buf_size, (uint8_t *)state->out_data_ptr, - state->out_remain * sizeof(int32_t)); + state->out_remain * sample_size); } ret = sink_commit_buffer(sinks[0], commit_bytes); @@ -653,11 +699,10 @@ static int mfcc_output_legacy(struct processing_module *mod, struct mfcc_comp_da void *sink_start; size_t sink_buf_size; uint8_t *dst; - int n32; int ret; /* The MFCC sink is treated as an opaque byte container: the period - * carries an MFCC blob (header + int32 features), not PCM audio. + * carries an MFCC blob (header + features), not PCM audio. * Sizing the commit as sink_frame_bytes * frames keeps the period * size matched to whatever the sink advertises (S16_LE / S24_4LE / * S32_LE), so no format-specific conversion is needed. Any payload @@ -702,17 +747,21 @@ static int mfcc_output_legacy(struct processing_module *mod, struct mfcc_comp_da } } - /* Write pending feature data (always int32) */ + /* Write pending feature data (int8 or int32 per output mode) */ if (state->out_remain > 0 && avail > 0) { - data_bytes = state->out_remain * sizeof(int32_t); - to_write = MIN(data_bytes, avail) & ~(size_t)3; + size_t sample_size = mfcc_out_sample_size(state); + data_bytes = state->out_remain * sample_size; + to_write = MIN(data_bytes, avail); + if (sample_size > 1) + to_write &= ~(sample_size - 1); if (to_write > 0) { mfcc_sink_write_bytes(&dst, sink_start, sink_buf_size, (uint8_t *)state->out_data_ptr, to_write); - n32 = to_write / sizeof(int32_t); - state->out_data_ptr += n32; - state->out_remain -= n32; + int n = to_write / sample_size; + + state->out_data_ptr = (void *)((uint8_t *)state->out_data_ptr + to_write); + state->out_remain -= n; } } diff --git a/src/audio/mfcc/mfcc_setup.c b/src/audio/mfcc/mfcc_setup.c index 1d062b2a5206..6d4e132e974c 100644 --- a/src/audio/mfcc/mfcc_setup.c +++ b/src/audio/mfcc/mfcc_setup.c @@ -10,6 +10,9 @@ #include #include #include +#if CONFIG_COMP_MFCC_PCAN +#include +#endif #include #include #include @@ -209,6 +212,16 @@ int mfcc_setup(struct processing_module *mod, int max_frames, int sample_rate, i return -EINVAL; } + if (config->enable_pcan && config->enable_agc8) { + comp_err(dev, "enable_pcan and enable_agc8 are exclusive"); + return -EINVAL; + } + + if ((config->enable_pcan || config->enable_agc8) && config->num_ceps > 0) { + comp_err(dev, "int8 Mel output requires num_ceps 0"); + return -EINVAL; + } + cd->max_frames = max_frames; state->sample_rate = sample_rate; state->low_freq = config->low_freq; @@ -383,6 +396,9 @@ int mfcc_setup(struct processing_module *mod, int max_frames, int sample_rate, i /* Use FFT buffer as scratch for later computed data */ state->power_spectra = (int32_t *)&fft->fft_buf[0]; state->mel_log_32 = &state->power_spectra[fft->half_fft_size]; +#if CONFIG_COMP_MFCC_PCAN + state->mel_linear = (uint32_t *)&state->mel_log_32[config->num_mel_bins]; +#endif /* Check that mel_log_32 fits in the remaining fft_buf scratch space */ mel_log_32_space = (int)(fft->fft_buffer_size / sizeof(int32_t)) - fft->half_fft_size; @@ -459,9 +475,79 @@ int mfcc_setup(struct processing_module *mod, int max_frames, int sample_rate, i } } + if (config->enable_pcan) { +#if CONFIG_COMP_MFCC_PCAN + struct pcan_config pcfg; + uint32_t *pcan_noise; + int16_t *pcan_lut; + + /* Q1.15 and Q8.7, defaults 0.95 and 80.0 */ + pcfg.strength = (config->pcan_strength > 0) ? config->pcan_strength : 31130; + pcfg.offset = (config->pcan_offset > 0) ? config->pcan_offset : 10240; + pcfg.gain_bits = (config->pcan_gain_bits > 0) ? + config->pcan_gain_bits : 21; + pcfg.smoothing_coef = (config->pcan_smoothing_coef > 0) ? + (uint16_t)config->pcan_smoothing_coef : 819; + pcfg.smoothing_bits = 10; + pcfg.input_correction_bits = PCAN_INPUT_CORRECTION_BITS; + pcfg.enable_pcan = true; + + pcan_noise = mod_zalloc(mod, config->num_mel_bins * sizeof(uint32_t)); + if (!pcan_noise) { + comp_err(dev, "Failed PCAN noise estimate alloc"); + ret = -ENOMEM; + goto free_vad; + } + + pcan_lut = mod_zalloc(mod, PCAN_LUT_SIZE * sizeof(int16_t)); + if (!pcan_lut) { + comp_err(dev, "Failed PCAN gain LUT alloc"); + mod_free(mod, pcan_noise); + ret = -ENOMEM; + goto free_vad; + } + + ret = pcan_populate_state(&pcfg, &state->pcan, pcan_noise, pcan_lut, + config->num_mel_bins, 10, + PCAN_INPUT_CORRECTION_BITS); + if (ret < 0) { + comp_err(dev, "Failed PCAN state init"); + mod_free(mod, pcan_noise); + mod_free(mod, pcan_lut); + goto free_vad; + } + } else { + state->pcan.enable_pcan = false; + state->pcan.noise_estimate = NULL; + state->pcan.gain_lut = NULL; + } +#else + comp_err(dev, "enable_pcan set but CONFIG_COMP_MFCC_PCAN is not selected"); + ret = -EINVAL; + goto free_vad; + } +#endif + + if (config->enable_pcan) { + state->out_mode = MFCC_OUT_MEL8_PCAN; + } else if (config->enable_agc8) { + mfcc_agc8_init(&state->agc8, config); + state->out_mode = MFCC_OUT_MEL8_AGC; + } else { + state->out_mode = state->mel_only ? MFCC_OUT_MEL32 : MFCC_OUT_CEPS; + } + comp_dbg(dev, "done"); return 0; +free_vad: + if (config->enable_vad) { + mod_free(mod, cd->vad.noise_floor); + mod_free(mod, cd->vad.weights); + cd->vad.noise_floor = NULL; + cd->vad.weights = NULL; + } + free_out_stage: mod_free(mod, state->out_stage); @@ -528,6 +614,10 @@ void mfcc_free_buffers(struct processing_module *mod) mfcc_free_and_null(mod, (void **)&cd->state.dct.matrix); mfcc_free_and_null(mod, (void **)&cd->state.lifter.matrix); mfcc_free_and_null(mod, (void **)&cd->state.out_stage); +#if CONFIG_COMP_MFCC_PCAN + mfcc_free_and_null(mod, (void **)&cd->state.pcan.noise_estimate); + mfcc_free_and_null(mod, (void **)&cd->state.pcan.gain_lut); +#endif mfcc_free_and_null(mod, (void **)&cd->vad.noise_floor); mfcc_free_and_null(mod, (void **)&cd->vad.weights); } diff --git a/src/audio/mfcc/tune/setup_mfcc.m b/src/audio/mfcc/tune/setup_mfcc.m index dbf69587a74f..9ebc952e734c 100644 --- a/src/audio/mfcc/tune/setup_mfcc.m +++ b/src/audio/mfcc/tune/setup_mfcc.m @@ -31,6 +31,55 @@ function setup_mfcc() setup.tplg_fn = 'mel80_compress.conf'; export_mfcc_setup(gen_cfg, setup); + % Blob for 40-bin/20ms-hop mel spectrogram, matching TFLM micro_speech's + % front-end shape (TFLM_FEATURE_SIZE=40, TFLM_FEATURE_STRIDE_MS=20, + % TFLM_FEATURE_DURATION_MS=30) for interim wake-word sanity-checking. + setup = get_mel_spectrogram_config(); + setup.frame_length = 30.0; % 480 samples at 16 kHz + setup.frame_shift = 20.0; % 320 samples at 16 kHz + setup.num_mel_bins = 40; + setup.tplg_fn = 'mel40.conf'; + export_mfcc_setup(gen_cfg, setup); + + % Same 40-bin/20ms-hop mel spectrogram with compress PCM output for the + % on-device TFLM wake-word path (KPB -> SRC -> MFCC -> tflmcly). + setup = get_mel_spectrogram_config(); + setup.frame_length = 30.0; + setup.frame_shift = 20.0; + setup.num_mel_bins = 40; + setup.compress_output = true; + setup.tplg_fn = 'mel40_compress.conf'; + export_mfcc_setup(gen_cfg, setup); + + % Blob for 40-bin/10ms-hop mel spectrogram, matching microWakeWord's + % MixConv front-end shape (40 features per 10ms stride over a 30ms + % window, 125 Hz to 7500 Hz bandwidth) -- see src/audio/microwakeword. + setup = get_mel_spectrogram_config(); + setup.frame_length = 30.0; % 480 samples at 16 kHz + setup.frame_shift = 10.0; % 160 samples at 16 kHz + setup.num_mel_bins = 40; + setup.low_freq = 125; + setup.high_freq = 7500; + setup.tplg_fn = 'mel40_10ms.conf'; + export_mfcc_setup(gen_cfg, setup); + + % Same 40-bin/10ms-hop mel spectrogram with compress PCM output for + % microWakeWord compress stream capture. + setup = get_mel_spectrogram_config(); + setup.frame_length = 30.0; + setup.frame_shift = 10.0; + setup.num_mel_bins = 40; + setup.low_freq = 125; + setup.high_freq = 7500; + setup.compress_output = true; + setup.update_controls = false; + setup.enable_vad = false; + setup.enable_dtx = false; + setup.dtx_trailing_silence_hops = 0; + setup.dtx_silence_hops_interval = 0; + setup.tplg_fn = 'mel40_10ms_compress.conf'; + export_mfcc_setup(gen_cfg, setup); + % Blob for mel spectrogram with compress PCM output and DTX setup = get_mel_spectrogram_config(); setup.compress_output = true; @@ -51,6 +100,39 @@ function setup_mfcc() setup.tplg_fn = 'ceps13_compress_dtx.conf'; export_mfcc_setup(gen_cfg, setup); + % Mel spectrogram with PCAN normalization and compress PCM output + setup = get_mel_spectrogram_config(); + setup.enable_pcan = true; + setup.compress_output = true; + setup.tplg_fn = 'mel80_pcan_compress.conf'; + export_mfcc_setup(gen_cfg, setup); + + % 40 mel bins, 10 ms hop PCAN for microWakeWord (no Slaney norm, Google-matched) + setup = get_mel_spectrogram_config(); + setup.frame_length = 30.0; + setup.frame_shift = 10.0; + setup.num_mel_bins = 40; + setup.low_freq = 125; + setup.high_freq = 7500; + setup.norm = 'none'; + setup.mel_offset = 0; + setup.mel_scale = 1.0; + setup.top_db = 0; + setup.dynamic_mmax = false; + setup.enable_pcan = true; + setup.pcan_strength = 0.95; + setup.pcan_offset = 80.0; + setup.pcan_gain_bits = 21; + setup.pcan_smoothing_coef = 819; + setup.compress_output = true; + setup.update_controls = false; + setup.enable_vad = false; + setup.enable_dtx = false; + setup.dtx_trailing_silence_hops = 0; + setup.dtx_silence_hops_interval = 0; + setup.tplg_fn = 'mel40_10ms_pcan_compress.conf'; + export_mfcc_setup(gen_cfg, setup); + end function cfg = get_mfcc_default_config() @@ -94,6 +176,11 @@ function setup_mfcc() cfg.dtx_silence_hops_interval = 0; cfg.update_controls = false; cfg.compress_output = false; + cfg.enable_pcan = false; + cfg.pcan_strength = 0.95; + cfg.pcan_offset = 80.0; + cfg.pcan_gain_bits = 21; + cfg.pcan_smoothing_coef = 819; end function cfg = get_mel_spectrogram_config() @@ -113,7 +200,7 @@ function setup_mfcc() cfg.num_mel_bins = 80; cfg.preemphasis_coefficient = 0; cfg.raw_energy = false; - cfg.remove_dc_offset = false; + cfg.remove_dc_offset = true; cfg.round_to_power_of_two = true; cfg.sample_frequency = 16000; cfg.snip_edges = true; @@ -123,20 +210,25 @@ function setup_mfcc() cfg.vtln_low = 0; cfg.vtln_warp = 1.0; cfg.window_type = 'hann'; - cfg.mel_log = 'log10'; + cfg.mel_log = 'log'; % Set to 'db' for librosa, set to 'log10' for matlab cfg.pmin = 1e-10; - cfg.top_db = 8; % applied for log10, would be 80 dB clamp for decibels as 10*log10() - cfg.mel_offset = 4.0; % For whisper like Mel scale and normalize - cfg.mel_scale = 0.25; % For whisper like Mel scale and normalize - cfg.mmax_init = 0; % Initial value max Mel value, data clamp is mmax - top_db - cfg.mmax_coef = 0; % Dynamic max Mel value decay coefficient (zero lock to found max) - cfg.dynamic_mmax = true; - cfg.enable_vad = true; + cfg.top_db = 80.0; + cfg.mel_offset = 4.0; % Whisper: (mel + 4.0) * 0.25 + cfg.mel_scale = 0.25; + cfg.mmax_init = 0; + cfg.mmax_coef = 0.005; % Whisper mmax tracking: slow decay + cfg.dynamic_mmax = false; + cfg.enable_vad = false; cfg.enable_dtx = false; cfg.dtx_trailing_silence_hops = 0; cfg.dtx_silence_hops_interval = 0; - cfg.update_controls = true; + cfg.update_controls = false; cfg.compress_output = false; + cfg.enable_pcan = false; + cfg.pcan_strength = 0.95; + cfg.pcan_offset = 80.0; + cfg.pcan_gain_bits = 21; + cfg.pcan_smoothing_coef = 819; end function export_mfcc_setup(gen_cfg, cfg) @@ -173,8 +265,9 @@ function export_mfcc_setup(gen_cfg, cfg) v = cfg.dtx_trailing_silence_hops; [b8, j] = add_w16b(v, b8, j); % DTX trailing silence hops v = cfg.dtx_silence_hops_interval; [b8, j] = add_w16b(v, b8, j); % DTX silence frame interval +v = cfg.pcan_smoothing_coef; [b8, j] = add_w32b(v, b8, j); % PCAN smoothing coef in Q14 % Reserved -for i = 1:5 +for i = 1:4 [b8, j] = add_w32b(0, b8, j); end @@ -200,10 +293,9 @@ function export_mfcc_setup(gen_cfg, cfg) v = 0; [b8, j] = add_w16b(v, b8, j); % vtln_high Qx.y TBD v = 0; [b8, j] = add_w16b(v, b8, j); % vtln_low Qx.y TBD v = 0; [b8, j] = add_w16b(v, b8, j); % vtln_warp Qx.y TBD -% reserved16[3] -for i = 1:3 - [b8, j] = add_w16b(0, b8, j); -end +v = q_convert(cfg.pcan_strength, 15); [b8, j] = add_w16b(v, b8, j); % PCAN strength in Q1.15 +v = q_convert(cfg.pcan_offset, 7); [b8, j] = add_w16b(v, b8, j); % PCAN offset in Q8.7 +v = cfg.pcan_gain_bits; [b8, j] = add_w16b(v, b8, j); % PCAN gain bits v = cfg.htk_compat; [b8, j] = add_w8b(v, b8, j); % bool v = cfg.raw_energy; [b8, j] = add_w8b(v, b8, j); % bool v = cfg.remove_dc_offset; [b8, j] = add_w8b(v, b8, j); % bool @@ -216,8 +308,9 @@ function export_mfcc_setup(gen_cfg, cfg) v = cfg.enable_dtx; [b8, j] = add_w8b(v, b8, j); % bool v = cfg.update_controls; [b8, j] = add_w8b(v, b8, j); % bool v = cfg.compress_output; [b8, j] = add_w8b(v, b8, j); % bool -% reserved_bool[4] -for i = 1:4 +v = cfg.enable_pcan; [b8, j] = add_w8b(v, b8, j); % bool +% reserved_bool[3] +for i = 1:3 [b8, j] = add_w8b(0, b8, j); end diff --git a/src/include/sof/audio/mfcc/mfcc_agc8.h b/src/include/sof/audio/mfcc/mfcc_agc8.h new file mode 100644 index 000000000000..62962ae8902f --- /dev/null +++ b/src/include/sof/audio/mfcc/mfcc_agc8.h @@ -0,0 +1,68 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * + * Copyright(c) 2026 Intel Corporation. + * + * Author: Seppo Ingalsuo + */ + +/** + * \file mfcc_agc8.h + * \brief Soft AGC and int8 quantization of MFCC Mel log spectra. + * + * A light alternative to PCAN for int8 Mel feature output. A single gain + * is added to all Q9.23 Mel log values of a hop. The gain attacks + * instantly so that the hop peak stays at or below +1.0 and releases + * slowly towards the target, slower during speech. The result is clamped + * to -1.0 .. +1.0 and converted to int8 Q1.7. + */ + +#ifndef __SOF_AUDIO_MFCC_MFCC_AGC8_H__ +#define __SOF_AUDIO_MFCC_MFCC_AGC8_H__ + +#include +#include + +struct sof_mfcc_config; + +/** \brief Default gain target in Q9.23, 0.25 */ +#define MFCC_AGC8_TARGET_Q23 2097152 +/** \brief Default gain floor in Q9.23, -2.0 */ +#define MFCC_AGC8_FLOOR_Q23 -16777216 +/** \brief Default release step per hop in Q9.23 during silence */ +#define MFCC_AGC8_RELEASE_Q23 4194 +/** \brief Default release step per hop in Q9.23 during speech */ +#define MFCC_AGC8_RELEASE_SPEECH_Q23 419 + +/** \brief Soft AGC state */ +struct mfcc_agc8 { + int32_t gain; /**< Current gain in Q9.23 */ + int32_t target; /**< Gain target in Q9.23 */ + int32_t floor; /**< Minimum gain in Q9.23 */ + int32_t release; /**< Release step per hop in Q9.23 during silence */ + int32_t release_speech; /**< Release step per hop in Q9.23 during speech */ +}; + +/** + * \brief Initialize soft AGC parameters from the configuration blob. + * + * Zero valued blob parameters select the defaults. The gain is set to + * the target. + * + * \param[out] agc Soft AGC state. + * \param[in] config MFCC configuration blob. + */ +void mfcc_agc8_init(struct mfcc_agc8 *agc, const struct sof_mfcc_config *config); + +/** + * \brief Apply soft AGC to one hop of Mel log values and convert to int8. + * + * \param[in,out] agc Soft AGC state. + * \param[in] mel Mel log values in Q9.23. + * \param[out] out int8 Q1.7 output values. + * \param[in] n Number of Mel values. + * \param[in] speech True when VAD reports speech for this hop. + */ +void mfcc_agc8_process(struct mfcc_agc8 *agc, const int32_t *mel, int8_t *out, int n, + bool speech); + +#endif /* __SOF_AUDIO_MFCC_MFCC_AGC8_H__ */ diff --git a/src/include/sof/audio/mfcc/mfcc_comp.h b/src/include/sof/audio/mfcc/mfcc_comp.h index 885339004fc0..43b69f869aae 100644 --- a/src/include/sof/audio/mfcc/mfcc_comp.h +++ b/src/include/sof/audio/mfcc/mfcc_comp.h @@ -13,6 +13,10 @@ #include #include #include +#if CONFIG_COMP_MFCC_PCAN +#include +#endif +#include #include #include #include @@ -39,6 +43,14 @@ /** \brief Switch control index for VAD notification to user space */ #define MFCC_CTRL_INDEX_VAD 0 +/** \brief Output data type, selected at setup from the configuration blob. */ +enum mfcc_out_mode { + MFCC_OUT_CEPS = 0, /**< Cepstral coefficients, int16 Q9.7 widened to int32 */ + MFCC_OUT_MEL32, /**< Mel log spectra, int32 Q9.23 */ + MFCC_OUT_MEL8_PCAN, /**< PCAN normalized Mel energies, int8 */ + MFCC_OUT_MEL8_AGC, /**< Soft AGC Mel log spectra, int8 Q1.7 */ +}; + /** * \brief Data header prepended to every MFCC output frame. * @@ -99,6 +111,11 @@ struct mfcc_state { struct mfcc_fft fft; /**< FFT related */ struct dct_plan_16 dct; /**< DCT related */ struct psy_mel_filterbank melfb; /**< Mel filter bank */ +#if CONFIG_COMP_MFCC_PCAN + struct pcan_state pcan; /**< PCAN state */ + uint32_t *mel_linear; /**< Linear Mel band magnitudes for PCAN */ +#endif + struct mfcc_agc8 agc8; /**< Soft AGC state for int8 Mel output */ struct mfcc_cepstral_lifter lifter; /**< Cepstral lifter coefficients */ struct mat_matrix_16b *mel_spectra; /**< Pointer to scratch */ struct mat_matrix_16b *cepstral_coef; /**< Pointer to scratch */ @@ -117,13 +134,14 @@ struct mfcc_state { int high_freq; int sample_rate; bool mel_only; /**< When true, output Mel spectra instead of cepstral coefficients */ + enum mfcc_out_mode out_mode; /**< Output data type */ bool waiting_fill; /**< booleans */ bool prev_samples_valid; bool header_pending; /**< True when data header not yet written for current output */ struct mfcc_data_header header; /**< Data header for current output frame */ size_t sample_buffers_size; /**< bytes */ - int32_t *out_data_ptr; /**< Read pointer into staging data for multi-period output */ - int out_remain; /**< Remaining int32_t samples to write to sink from staging */ + void *out_data_ptr; /**< Read pointer into staging data for multi-period output */ + int out_remain; /**< Remaining samples to write to sink from staging */ int32_t *out_stage; /**< Dedicated staging buffer for pending output, decoupled from STFT scratch */ int out_stage_size; /**< Capacity of out_stage in int32_t samples */ uint32_t hop_count; /**< FFT hop counter, increments every processed hop */ @@ -151,6 +169,13 @@ static inline int mfcc_buffer_samples_without_wrap(struct mfcc_buffer *buffer, i return buffer->end_addr - ptr; } +/** \brief Size in bytes of one output value for the current output mode. */ +static inline size_t mfcc_out_sample_size(const struct mfcc_state *state) +{ + return (state->out_mode == MFCC_OUT_MEL8_PCAN || state->out_mode == MFCC_OUT_MEL8_AGC) ? + sizeof(int8_t) : sizeof(int32_t); +} + static inline int16_t *mfcc_buffer_wrap(struct mfcc_buffer *buffer, int16_t *ptr) { if (ptr >= buffer->end_addr) diff --git a/src/include/sof/audio/mfcc/mfcc_vad.h b/src/include/sof/audio/mfcc/mfcc_vad.h index 6873343d334e..048ea475eba1 100644 --- a/src/include/sof/audio/mfcc/mfcc_vad.h +++ b/src/include/sof/audio/mfcc/mfcc_vad.h @@ -29,9 +29,9 @@ struct processing_module; #define MFCC_VAD_NOISE_INIT_FRAMES 100 /** - * \brief Slow noise floor rise coefficient in Q1.15 (0.003 * 2^15). + * \brief Slow noise floor rise coefficient in Q1.15 (0.001 * 2^15, tau ~10 s). */ -#define MFCC_VAD_NOISE_RISE_ALPHA 98 +#define MFCC_VAD_NOISE_RISE_ALPHA 33 /** * \brief Fast noise floor rise coefficient in Q1.15 (0.020 * 2^15). @@ -39,9 +39,9 @@ struct processing_module; #define MFCC_VAD_NOISE_RISE_ALPHA_FAST 655 /** - * \brief Energy threshold for speech detection in Q9.23 (0.30 * 2^23). + * \brief Energy threshold for speech detection in Q9.23 (0.20 * 2^23). */ -#define MFCC_VAD_ENERGY_THRESHOLD 2516582 +#define MFCC_VAD_ENERGY_THRESHOLD 1677722 /** * \brief Hangover frame count to keep VAD active after last speech detection. diff --git a/src/include/user/mfcc.h b/src/include/user/mfcc.h index 286ee4f5e985..80604cfd2729 100644 --- a/src/include/user/mfcc.h +++ b/src/include/user/mfcc.h @@ -56,7 +56,12 @@ struct sof_mfcc_config { int16_t mmax_coef; /**< Q1.15 decay coefficient for dynamic mmax, a small value for slow */ uint16_t dtx_trailing_silence_hops; /**< DTX: number of silence hops to send after speech, 0 = send first only */ uint16_t dtx_silence_hops_interval; /**< DTX: send silence frame every Nth hop during VAD=0, 0 = disable */ - uint32_t reserved[5]; + uint32_t pcan_smoothing_coef; /**< Q14 smoothing coef for PCAN, e.g. 819 for 0.05 */ + int16_t agc_target; /**< Q8.7 soft AGC gain target, 0 = default 0.25 */ + int16_t agc_floor; /**< Q8.7 soft AGC minimum gain, 0 = default -2.0 */ + int16_t agc_release; /**< Q9.23 soft AGC release step per hop, 0 = default 4194 */ + int16_t agc_release_speech; /**< Q9.23 release step per hop in speech, 0 = default 419 */ + uint32_t reserved[2]; int32_t sample_frequency; /**< Hz. e.g. 16000 */ int32_t pmin; /**< Q1.31 linear power, limit minimum Mel energy, e.g. 1e-9 */ enum sof_mfcc_mel_log_type mel_log; /**< Use MEL_LOG_IS_LOG, LOG10 or DB*/ @@ -79,7 +84,9 @@ struct sof_mfcc_config { int16_t vtln_high; /**< Reserved, no support */ int16_t vtln_low; /**< Reserved, no support */ int16_t vtln_warp; /**< Reserved, no support */ - int16_t reserved16[3]; /**< Reserved for future 16-bit fields, set to 0 */ + int16_t pcan_strength; /**< Q1.15 strength alpha, e.g. 31130 for 0.95 */ + int16_t pcan_offset; /**< Q8.7 offset delta, e.g. 10240 for 80.0 */ + int16_t pcan_gain_bits; /**< Gain bits scale, e.g. 21 */ bool htk_compat; /**< Must be false */ bool raw_energy; /**< Reserved, no support */ bool remove_dc_offset; /**< Reserved, no support */ @@ -92,7 +99,9 @@ struct sof_mfcc_config { bool enable_dtx; /**< Discontinuous transmission: suppress silence after trailing frames */ bool update_controls; /**< Update controls with VAD decision */ bool compress_output; /**< Use compress PCM output: variable size, no zero padding */ - bool reserved_bool[4]; /* Reserved for future boolean flags, set to false (0) */ + bool enable_pcan; /**< Enable PCAN normalization on Mel filterbank energies */ + bool enable_agc8; /**< Enable soft AGC and int8 Mel output, exclusive with PCAN */ + bool reserved_bool[2]; /* Reserved for future boolean flags, set to false (0) */ } __attribute__((packed)); #endif /* __USER_MFCC_H__ */ From 58d568b55adafcaea9474c3257f24a7ed1000203 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 10/31] audio: kpb: add multi-client WOV detector triggering and dynamic sample rates Support multiple downstream WOV detector pipelines sharing a single KPB history buffer: - Support multi-sink topology binding, dynamic sample rates, and synchronous IPC4 reset. - Fix drain boundary copy, cross-core drain request coherency, and buffer parameter configuration races. - Continue history buffering when a selector sink is full, and disable synchronous draining mode blocking. - Increase KPB_MAX_NO_OF_CLIENTS default to 4 and KPB_MAX_BUFF_TIME to 6000 ms on ACE 3.0+. Signed-off-by: Liam Girdwood Co-authored-by: Seppo Ingalsuo Signed-off-by: Seppo Ingalsuo --- src/audio/Kconfig | 14 ++ src/audio/kpb.c | 482 ++++++++++++++++++++++++++---------- src/audio/kpb.toml | 7 +- src/include/ipc4/kpb.h | 2 + src/include/sof/audio/kpb.h | 13 +- 5 files changed, 383 insertions(+), 135 deletions(-) diff --git a/src/audio/Kconfig b/src/audio/Kconfig index fecbf0d25afa..8468570fe45a 100644 --- a/src/audio/Kconfig +++ b/src/audio/Kconfig @@ -174,6 +174,20 @@ config KPB_NOTIFIER This transport can be enabled independently of the Async Messaging Service (AMS), including together with AMS. +config KPB_MAX_NO_OF_CLIENTS + int "Maximum number of KPB clients" + default 4 + help + Maximum number of simultaneous KPB drain clients (host + WOV detectors). + Increase if more than 4 clients need concurrent KPB access. + +config KPB_MAX_BUFF_TIME + int "KPB history buffer time (ms)" + default 6000 if XCHAL_HW_VERSION_MAJOR >= 300 + default 2100 + help + KPB history ring-buffer length in milliseconds. + config KPB_FORCE_COPY_TYPE_NORMAL bool "KPB force copy type normal" default y diff --git a/src/audio/kpb.c b/src/audio/kpb.c index f0f3ff743584..6999b1f93aad 100644 --- a/src/audio/kpb.c +++ b/src/audio/kpb.c @@ -18,12 +18,18 @@ #include #include #include +#include +#define SOF_MODULE_API_PRIVATE +#include +#include #include #include #include #include +#include #include #include +#include #include #include #include @@ -102,6 +108,7 @@ struct comp_data { enum comp_copy_type force_copy_type; /**< should we force copy_type on kpb sink? */ #ifdef CONFIG_IPC_MAJOR_4 struct ipc4_kpb_module_cfg ipc4_cfg; + uint32_t buff_time_ms; /**< history depth in ms; 0 = CONFIG_KPB_MAX_BUFF_TIME */ #endif /* CONFIG_IPC_MAJOR_4 */ uint32_t num_of_sel_mic; uint32_t num_of_in_channels; @@ -133,6 +140,7 @@ K_KERNEL_STACK_DEFINE(kpb_stack, 4096); #if CONFIG_KPB_NOTIFIER static void kpb_event_handler(void *arg, enum notify_id type, void *event_data); +static void kpb_on_wov_ctrl(void *arg, enum notify_id id, void *data); static int kpb_register_client(struct comp_data *kpb, struct kpb_client *cli); #endif @@ -142,7 +150,6 @@ static int kpb_buffer_data(struct comp_dev *dev, const struct comp_buffer *source, size_t size); static size_t kpb_allocate_history_buffer(struct comp_data *kpb, size_t hb_size_req); -static void kpb_clear_history_buffer(struct history_buffer *buff); static void kpb_free_history_buffer(struct history_buffer *buff); static inline bool kpb_is_sample_width_supported(uint32_t sampling_width); static void kpb_copy_samples(struct comp_buffer *sink, @@ -250,6 +257,17 @@ static void kpb_lock_init(struct comp_data *kpb) #endif /* __ZEPHYR__ */ + +/* Return per-instance history depth (ms); fall back to Kconfig if not set via topology. */ +static inline uint32_t kpb_get_buff_time_ms(const struct comp_data *kpb) +{ +#if CONFIG_IPC_MAJOR_4 + return kpb->buff_time_ms ? kpb->buff_time_ms : CONFIG_KPB_MAX_BUFF_TIME; +#else + return CONFIG_KPB_MAX_BUFF_TIME; +#endif +} + #if CONFIG_IPC_MAJOR_4 /** * \brief Set and verify ipc params. @@ -285,8 +303,9 @@ __cold static int kpb_set_verify_ipc_params(struct comp_dev *dev, return -EINVAL; } - if (kpb->config.sampling_freq != KPB_SAMPLNG_FREQUENCY) { - comp_err(dev, "requested sampling frequency not supported"); + if (kpb->config.sampling_freq != 16000 && kpb->config.sampling_freq != 48000) { + comp_err(dev, "requested sampling frequency %u not supported", + kpb->config.sampling_freq); return -EINVAL; } @@ -314,7 +333,7 @@ static void kpb_set_params(struct comp_dev *dev, params->sample_valid_bytes = kpb->ipc4_cfg.base_cfg.audio_fmt.valid_bit_depth / 8; params->buffer_fmt = kpb->ipc4_cfg.base_cfg.audio_fmt.interleaving_style; - params->buffer.size = kpb->ipc4_cfg.base_cfg.ibs * KPB_MAX_BUFF_TIME * params->channels; + params->buffer.size = kpb->ipc4_cfg.base_cfg.ibs * kpb_get_buff_time_ms(kpb) * params->channels; params->host_period_bytes = params->channels * params->sample_container_bytes * @@ -391,6 +410,9 @@ __cold static int kpb_bind(struct comp_dev *dev, const struct bind_info *bind_da sink_buf_id = buf_get_id(sink); if (sink_buf_id == buf_id) { + struct comp_dev *sc = comp_buffer_get_sink_component(sink); + comp_dbg(dev, "kpb_bind: buf_id=%d sink_comp=0x%x -> %s", + buf_id, sc ? dev_comp_id(sc) : 0, sink_buf_id == 0 ? "sel_sink" : "host_sink"); if (sink_buf_id == 0) kpb->sel_sink = sink; else @@ -468,8 +490,9 @@ __cold static int kpb_set_verify_ipc_params(struct comp_dev *dev, return -EINVAL; } - if (kpb->config.sampling_freq != KPB_SAMPLNG_FREQUENCY) { - comp_err(dev, "requested sampling frequency not supported"); + if (kpb->config.sampling_freq != 16000 && kpb->config.sampling_freq != 48000) { + comp_err(dev, "requested sampling frequency %u not supported", + kpb->config.sampling_freq); return -EINVAL; } @@ -691,7 +714,7 @@ static size_t kpb_allocate_history_buffer(struct comp_data *kpb, hb_size -= ca_size; hb->next = kpb->hd.c_hb; /* Do we need another buffer? */ - if (hb_size > 0) { + if (hb_size > 0 && i + 1 < ARRAY_SIZE(hb_mcp)) { /* Yes, we still need at least one more buffer. * Let's first create new container for it. */ @@ -792,6 +815,7 @@ __cold static void kpb_free(struct comp_dev *dev) #if CONFIG_KPB_NOTIFIER /* Unregister KPB from notifications */ notifier_unregister(dev, NULL, NOTIFIER_ID_KPB_CLIENT_EVT); + notifier_unregister(dev, NULL, NOTIFIER_ID_WOV_CTRL); #endif/* CONFIG_KPB_NOTIFIER */ /* Reclaim memory occupied by history buffer */ @@ -800,6 +824,7 @@ __cold static void kpb_free(struct comp_dev *dev) kpb->hd.buffer_size = 0; /* remove scheduling */ + schedule_task_cancel(&kpb->draining_task); schedule_task_free(&kpb->draining_task); /* change state */ @@ -889,7 +914,11 @@ static int kpb_prepare(struct comp_dev *dev) struct sof_ipc_stream_params params; int ret = 0; int i; - size_t hb_size_req = KPB_MAX_BUFFER_SIZE(kpb->config.sampling_width, kpb->config.channels); + /* Use topology-set depth if provided; otherwise Kconfig default. */ + uint32_t buff_ms = kpb_get_buff_time_ms(kpb); + size_t hb_size_req = (kpb->config.sampling_freq / 1000) * + (KPB_SAMPLE_CONTAINER_SIZE(kpb->config.sampling_width) / 8) * + buff_ms * kpb->config.channels; comp_dbg(dev, "entry"); @@ -902,6 +931,11 @@ static int kpb_prepare(struct comp_dev *dev) return -EINVAL; } + if (kpb->sel_sink) + buffer_set_params(kpb->sel_sink, ¶ms, true); + if (kpb->host_sink) + buffer_set_params(kpb->host_sink, ¶ms, true); + if (kpb->state == KPB_STATE_RESETTING || kpb->state == KPB_STATE_RESET_FINISHING) { comp_cl_err(&comp_kpb, "can not prepare KPB due to ongoing reset, state log %x", @@ -958,8 +992,12 @@ static int kpb_prepare(struct comp_dev *dev) } #if CONFIG_KPB_NOTIFIER - /* Register KPB for notification *on the current core* */ + /* Register KPB for notification *on the current core* (ensure no duplicate registrations) */ + notifier_unregister(dev, NULL, NOTIFIER_ID_KPB_CLIENT_EVT); + notifier_unregister(dev, NULL, NOTIFIER_ID_WOV_CTRL); ret = notifier_register(dev, NULL, NOTIFIER_ID_KPB_CLIENT_EVT, kpb_event_handler); + if (ret >= 0) + ret = notifier_register(dev, NULL, NOTIFIER_ID_WOV_CTRL, kpb_on_wov_ctrl); if (ret < 0) { kpb_free_history_buffer(kpb->hd.c_hb); @@ -985,6 +1023,51 @@ static int kpb_prepare(struct comp_dev *dev) #endif /* CONFIG_AMS */ #endif + struct comp_buffer *sink; + /* Output pin IDs: IPC4_COMP_ID(src_queue, dst_queue) = (dst_queue<<16)|src_queue. + * In a multi-KPB topology each KPB connects to a different arbiter input pin so + * dst_queue varies (0,1,2...) but src_queue is always 0 (sel) or 1 (host). + * Match on src_queue only (lower 16 bits of buf_id). */ + enum { KPB_PIN_SEL_SINK = 0, KPB_PIN_HOST_SINK_SRC = 1 }; + comp_dev_for_each_consumer(dev, sink) { + uint32_t src_q = buf_get_id(sink) & 0xFFFF; + + if (src_q == KPB_PIN_SEL_SINK) + kpb->sel_sink = sink; + else if (src_q == KPB_PIN_HOST_SINK_SRC && !kpb->host_sink) + kpb->host_sink = sink; + else + comp_warn(dev, "kpb_prepare: unexpected consumer pin, buf_id=0x%x", + buf_get_id(sink)); + } + comp_dbg(dev, "kpb_params: sel_sink=%p host_sink=%p", + kpb->sel_sink, kpb->host_sink); + + /* Cross-pipeline prepare: the WOV detector (detect_test) lives on a + * separate IPC4 pipeline and won't be prepared by the normal IPC4 walk, + * so KPB bootstraps it here during its own prepare phase. + */ + if (kpb->sel_sink) { + struct comp_dev *sink_comp = comp_buffer_get_sink_component(kpb->sel_sink); + if (sink_comp && sink_comp->state == COMP_STATE_INIT) { + struct sof_ipc_stream_params sink_params; + memset_s(&sink_params, sizeof(sink_params), 0, sizeof(sink_params)); + sink_params.channels = kpb->config.channels ? kpb->config.channels : 2; + sink_params.rate = kpb->config.sampling_freq ? kpb->config.sampling_freq : 16000; + sink_params.sample_container_bytes = 4; + sink_params.sample_valid_bytes = 4; + sink_params.frame_fmt = SOF_IPC_FRAME_S32_LE; + comp_params(sink_comp, &sink_params); + ret = comp_prepare(sink_comp); + if (ret < 0) { + comp_err(dev, "kpb_prepare: cross-pipeline prepare of wov detector failed: %d", ret); + return ret; + } + } + } + + kpb_change_state(kpb, KPB_STATE_RUN); + #ifndef CONFIG_IPC_MAJOR_4 /* Search for KPB related sinks. * NOTE! We assume here that channel selector component device @@ -1034,13 +1117,45 @@ static int kpb_prepare(struct comp_dev *dev) } #endif /* CONFIG_IPC_MAJOR_4 */ + /* Fallback: iterate consumers to assign sel_sink and host_sink in order. + * The guards ensure each is set at most once — no overwrite on later iterations. */ + if (!kpb->sel_sink && !kpb->host_sink) { + struct comp_buffer *sink; + + comp_dev_for_each_consumer(dev, sink) { + if (!kpb->sel_sink) + kpb->sel_sink = sink; + else if (!kpb->host_sink) + kpb->host_sink = sink; + } + } + if (!kpb->sel_sink) { comp_err(dev, "could not find sink: sel_sink %p", kpb->sel_sink); ret = -EIO; + } else { + struct comp_dev *sink_comp = comp_buffer_get_sink_component(kpb->sel_sink); + if (sink_comp && sink_comp->state == COMP_STATE_INIT) { + struct sof_ipc_stream_params sink_params; + memset_s(&sink_params, sizeof(sink_params), 0, sizeof(sink_params)); + sink_params.channels = kpb->config.channels ? kpb->config.channels : 2; + sink_params.rate = kpb->config.sampling_freq ? kpb->config.sampling_freq : 16000; + sink_params.sample_container_bytes = 4; + sink_params.sample_valid_bytes = 4; + sink_params.frame_fmt = SOF_IPC_FRAME_S32_LE; + comp_params(sink_comp, &sink_params); + ret = comp_prepare(sink_comp); + comp_info(dev, "kpb_prepare: prepared downstream sink_comp %d in state %d", + dev_comp_id(sink_comp), sink_comp->state); + if (ret < 0) { + comp_err(dev, "kpb_prepare: cross-pipeline prepare failed: %d", ret); + return ret; + } + } } - kpb->sync_draining_mode = true; + kpb->sync_draining_mode = false; kpb_change_state(kpb, KPB_STATE_RUN); @@ -1076,14 +1191,52 @@ static int kpb_reset(struct comp_dev *dev) comp_cl_info(&comp_kpb, "resetting from state %d, state log %x", kpb->state, kpb->state_log); +#ifndef CONFIG_AMS + /* Unregister KPB from notifications */ + notifier_unregister(dev, NULL, NOTIFIER_ID_KPB_CLIENT_EVT); + notifier_unregister(dev, NULL, NOTIFIER_ID_WOV_CTRL); +#endif + switch (kpb->state) { case KPB_STATE_BUFFERING: case KPB_STATE_DRAINING: - /* KPB is performing some task now, - * terminate it gently. + case KPB_STATE_HOST_COPY: + /* Cancel any scheduled draining task immediately on reset */ + schedule_task_cancel(&kpb->draining_task); + + /* If a dedicated host drain is in progress to a separate host sink, + * let kpb_copy complete the reset once scheduled. + * If host_sink is NULL or same as sel_sink (unified WOV pipeline), + * or state is BUFFERING, reset immediately. + * Under IPC4, pipeline triggers and resets are synchronous; + * returning -EBUSY breaks the pipeline state machine and causes + * host teardown to fail. */ - kpb_change_state(kpb, KPB_STATE_RESETTING); - ret = -EBUSY; +#if !CONFIG_IPC_MAJOR_4 + if (kpb->host_sink && kpb->host_sink != kpb->sel_sink && + kpb->state == KPB_STATE_DRAINING) { + kpb_change_state(kpb, KPB_STATE_RESETTING); + ret = -EBUSY; + break; + } +#endif + /* host_sink == NULL or unified WOV path: immediate full reset */ + kpb->hd.buffered = 0; + kpb->sel_sink = NULL; + kpb->host_sink = NULL; + kpb->host_buffer_size = 0; + kpb->host_period_size = 0; + for (i = 0; i < KPB_MAX_NO_OF_CLIENTS; i++) { + kpb->clients[i].state = KPB_CLIENT_UNREGISTERED; + kpb->clients[i].r_ptr = NULL; + } + if (kpb->hd.c_hb) + kpb_reset_history_buffer(kpb->hd.c_hb); + /* Must transition away from KPB_STATE_RUN before returning so that + * a subsequent kpb_copy() does not see a stale RUN state and + * immediately begin copying before the next prepare completes. */ + kpb_change_state(kpb, KPB_STATE_PREPARING); + ret = comp_set_state(dev, COMP_TRIGGER_RESET); break; case KPB_STATE_DISABLED: case KPB_STATE_CREATED: @@ -1091,6 +1244,7 @@ static int kpb_reset(struct comp_dev *dev) ret = comp_set_state(dev, COMP_TRIGGER_RESET); break; default: + schedule_task_cancel(&kpb->draining_task); kpb->hd.buffered = 0; kpb->sel_sink = NULL; kpb->host_sink = NULL; @@ -1112,6 +1266,7 @@ static int kpb_reset(struct comp_dev *dev) #if CONFIG_KPB_NOTIFIER /* Unregister KPB from notifications */ notifier_unregister(dev, NULL, NOTIFIER_ID_KPB_CLIENT_EVT); + notifier_unregister(dev, NULL, NOTIFIER_ID_WOV_CTRL); #endif /* Finally KPB is ready after reset */ kpb_change_state(kpb, KPB_STATE_PREPARING); @@ -1395,20 +1550,16 @@ static int kpb_copy(struct comp_dev *dev) /* In normal RUN state we simply copy to our sink. */ sink = kpb->sel_sink; + comp_dbg(dev, "kpb_copy: source_buf=%p sel_sink=%p avail=%u", + source, sink, audio_stream_get_avail_bytes(&source->stream)); + if (!sink) { - comp_err(dev, "no sink."); + comp_warn(dev, "no sink."); ret = -EINVAL; break; } - /* Discard data if sink is not active */ - if (comp_buffer_get_sink_component(sink)->state != COMP_STATE_ACTIVE) { - copy_bytes = audio_stream_get_avail_bytes(&source->stream); - comp_update_buffer_consume(source, copy_bytes); - comp_dbg(dev, "KD not active, dropping %zu bytes...", copy_bytes); - ret = PPL_STATUS_PATH_STOP; - break; - } + /* Allow downstream WOV detector copy regardless of state */ /* Validate sink */ if (!audio_stream_get_wptr(&sink->stream)) { @@ -1417,44 +1568,44 @@ static int kpb_copy(struct comp_dev *dev) break; } - copy_bytes = audio_stream_get_copy_bytes(&source->stream, &sink->stream); - if (!copy_bytes) { - comp_err(dev, "nothing to copy sink->free %u source->avail %u", - audio_stream_get_free_bytes(&sink->stream), - audio_stream_get_avail_bytes(&source->stream)); - if (!audio_stream_get_avail_bytes(&sink->stream)) - ret = PPL_STATUS_PATH_STOP; + uint32_t src_avail = audio_stream_get_avail_bytes(&source->stream); + uint32_t snk_free = audio_stream_get_free_bytes(&sink->stream); + size_t frame_bytes = (sample_width >> 3) * channels; + size_t consume_bytes = 0; + + if (!src_avail) { + ret = PPL_STATUS_PATH_STOP; break; } + copy_bytes = MIN(src_avail, snk_free); + if (frame_bytes) + copy_bytes = ROUND_DOWN(copy_bytes, frame_bytes); + if (kpb->num_of_sel_mic == 0) { - kpb_copy_samples(sink, source, copy_bytes, sample_width, channels); + if (copy_bytes) + kpb_copy_samples(sink, source, copy_bytes, sample_width, channels); + consume_bytes = copy_bytes ? copy_bytes : (frame_bytes ? ROUND_DOWN(src_avail, frame_bytes) : 0); } else { - uint32_t avail = audio_stream_get_avail_bytes(&source->stream); - uint32_t free = audio_stream_get_free_bytes(&sink->stream); + uint32_t free = snk_free; - copy_bytes = MIN(avail, free * channels / kpb->num_of_sel_mic); + copy_bytes = MIN(src_avail, free * channels / kpb->num_of_sel_mic); copy_bytes = ROUND_DOWN(copy_bytes, (sample_width >> 3) * channels); unsigned int total_bytes_per_sample = (sample_width >> 3) * kpb->num_of_sel_mic; produced_bytes = copy_bytes * kpb->num_of_sel_mic / channels; produced_bytes = ROUND_DOWN(produced_bytes, total_bytes_per_sample); - if (!copy_bytes) { - comp_err(dev, "nothing to copy sink->free %u source->avail %u", - free, - avail); - if (!audio_stream_get_avail_bytes(&sink->stream)) - ret = PPL_STATUS_PATH_STOP; - break; - } - kpb_micselect_copy(dev, sink, source, produced_bytes, channels); + if (copy_bytes) + kpb_micselect_copy(dev, sink, source, produced_bytes, channels); + consume_bytes = copy_bytes ? copy_bytes : (frame_bytes ? ROUND_DOWN(src_avail, frame_bytes) : 0); } - /* Buffer source data internally in history buffer for future - * use by clients. + + /* Buffer into history buffer (consume_bytes ensures history ring keeps filling + * and upstream ECNS never stalls even if downstream sel_sink is full). */ - if (copy_bytes <= kpb->hd.buffer_size) { - ret = kpb_buffer_data(dev, source, copy_bytes); + if (consume_bytes && consume_bytes <= kpb->hd.buffer_size) { + ret = kpb_buffer_data(dev, source, consume_bytes); if (ret) { comp_err(dev, "internal buffering failed."); @@ -1466,17 +1617,29 @@ static int kpb_copy(struct comp_dev *dev) */ kpb->hd.buffered += MIN(kpb->hd.buffer_size - kpb->hd.buffered, - copy_bytes); - } else { + consume_bytes); + } else if (consume_bytes > kpb->hd.buffer_size) { comp_err(dev, "too much data to buffer."); } - if (kpb->num_of_sel_mic == 0) - comp_update_buffer_produce(sink, copy_bytes); - else - comp_update_buffer_produce(sink, produced_bytes); + if (copy_bytes) { + if (kpb->num_of_sel_mic == 0) + comp_update_buffer_produce(sink, copy_bytes); + else + comp_update_buffer_produce(sink, produced_bytes); - comp_update_buffer_consume(source, copy_bytes); + struct comp_dev *wov_comp = sink ? comp_buffer_get_sink_component(sink) : NULL; + if (wov_comp) { + comp_dbg(dev, "kpb_copy: produced=%u bytes, triggering wov=0x%x", + copy_bytes, dev_comp_id(wov_comp)); + comp_copy(wov_comp); + } else { + comp_warn(dev, "kpb_copy: downstream sink_comp returned NULL!"); + } + } + + if (consume_bytes) + comp_update_buffer_consume(source, consume_bytes); break; case KPB_STATE_HOST_COPY: @@ -1506,13 +1669,22 @@ static int kpb_copy(struct comp_dev *dev) * (no HOST DMA IRQs) we need to call host copy * anyway so it can update its pointers. */ + struct comp_dev *host_comp = sink ? comp_buffer_get_sink_component(sink) : NULL; + if (host_comp) + comp_copy(host_comp); + ret = PPL_STATUS_PATH_STOP; break; } kpb_copy_samples(sink, source, copy_bytes, sample_width, channels); + buffer_stream_writeback(sink, copy_bytes); comp_update_buffer_produce(sink, copy_bytes); + struct comp_dev *host_comp = sink ? comp_buffer_get_sink_component(sink) : NULL; + if (host_comp) + comp_copy(host_comp); comp_update_buffer_consume(source, copy_bytes); + ret = PPL_STATUS_PATH_STOP; break; case KPB_STATE_INIT_DRAINING: @@ -1571,7 +1743,6 @@ static int kpb_buffer_data(struct comp_dev *dev, uint32_t offset = 0; uint64_t timeout = 0; uint64_t current_time; - enum kpb_state state_preserved = kpb->state; size_t sample_width = kpb->config.sampling_width; comp_dbg(dev, "entry"); @@ -1588,8 +1759,6 @@ static int kpb_buffer_data(struct comp_dev *dev, return PPL_STATUS_PATH_STOP; } - kpb_change_state(kpb, KPB_STATE_BUFFERING); - timeout = sof_cycle_get_64() + k_ms_to_cyc_ceil64(1); /* Let's store audio stream data in internal history buffer */ while (size_to_copy) { @@ -1674,10 +1843,35 @@ static int kpb_buffer_data(struct comp_dev *dev, } } - kpb_change_state(kpb, state_preserved); return ret; } +#if CONFIG_KPB_NOTIFIER +static void kpb_on_wov_ctrl(void *arg, enum notify_id id, void *data) +{ + struct comp_dev *dev = arg; + struct comp_data *kpb = comp_get_drvdata(dev); + const struct wov_ctrl_notif *n = data; + + if (n->cmd == WOV_ARB_CMD_RESUME) { + comp_info(dev, "kpb: received WOV_ARB_CMD_RESUME, current state=%d", kpb->state); + kpb_lock(kpb); + if (kpb->state == KPB_STATE_DRAINING || + kpb->state == KPB_STATE_INIT_DRAINING || + kpb->state == KPB_STATE_HOST_COPY) { + schedule_task_cancel(&kpb->draining_task); + kpb->draining_task_data.drain_req = 0; + if (kpb->hd.c_hb) + kpb_reset_history_buffer(kpb->hd.c_hb); + kpb->hd.buffered = 0; + kpb->hd.free = kpb->hd.buffer_size; + kpb_change_state(kpb, KPB_STATE_RUN); + comp_info(dev, "kpb: resumed to RUN state"); + } + kpb_unlock(kpb); + } +} +#endif /* CONFIG_KPB_NOTIFIER */ /** * \brief Main event dispatcher. * \param[in] arg - KPB component internal data. @@ -1693,6 +1887,11 @@ static void kpb_event_handler(void *arg, enum notify_id type, void *event_data) struct kpb_event_data *evd = event_data; struct kpb_client *cli = evd->client_data; + /* client data may have been written by another core */ + if (cli) + dcache_invalidate_region((__sparse_force void __sparse_cache *)cli, + sizeof(*cli)); + comp_info(dev, "received event with ID: %d ", evd->event_id); @@ -1786,11 +1985,12 @@ static void kpb_init_draining(struct comp_dev *dev, struct kpb_client *cli) size_t buffered = 0; size_t local_buffered; size_t drain_interval; - size_t host_period_size = kpb->host_period_size; - size_t bytes_per_ms = (size_t)KPB_SAMPLES_PER_MS * + size_t host_period_size; + size_t bytes_per_ms = (size_t)(kpb->config.sampling_freq / 1000) * (KPB_SAMPLE_CONTAINER_SIZE(sample_width) / 8) * kpb->config.channels; size_t period_bytes_limit; + bool is_sink_ready; comp_info(dev, "requested draining of %d [ms] from history buffer", cli->drain_req); @@ -1801,23 +2001,33 @@ static void kpb_init_draining(struct comp_dev *dev, struct kpb_client *cli) return; } + if (!kpb->host_period_size) { + kpb->host_period_size = bytes_per_ms; + kpb->host_buffer_size = audio_stream_get_size(&kpb->host_sink->stream); + } + host_period_size = kpb->host_period_size; + is_sink_ready = (comp_buffer_get_sink_state(kpb->host_sink) == COMP_STATE_ACTIVE || + comp_buffer_get_sink_state(kpb->host_sink) == COMP_STATE_PREPARE); + if (kpb->state != KPB_STATE_RUN) { - comp_err(dev, "wrong KPB state"); + comp_err(dev, "wrong KPB state: %d", kpb->state); } else if (cli->id > KPB_MAX_NO_OF_CLIENTS) { - comp_err(dev, "wrong client id"); + comp_err(dev, "wrong client id: %u", cli->id); /* TODO: check also if client is registered */ /* sel_sink is NULL before bind and after reset/unbind */ - } else if (!kpb->sel_sink || - comp_buffer_get_sink_state(kpb->host_sink) != COMP_STATE_ACTIVE) { - comp_err(dev, "sink not ready for draining"); - } else if (kpb->hd.buffered < drain_req || - cli->drain_req > KPB_MAX_DRAINING_REQ) { - comp_cl_err(&comp_kpb, "not enough data in history buffer"); + } else if (!kpb->sel_sink || !is_sink_ready) { + comp_err(dev, "sink not ready for draining (sel_sink=%p sink_state=%d)", + kpb->sel_sink, comp_buffer_get_sink_state(kpb->host_sink)); + } else if (cli->drain_req > kpb_get_buff_time_ms(kpb)) { + comp_cl_err(&comp_kpb, "drain request exceeds max"); } else { - /* Draining accepted, find proper buffer to start reading - * At this point we are guaranteed that there is enough data - * in the history buffer. All we have to do now is to calculate - * read pointer from which we will start draining. + if (kpb->hd.buffered < drain_req) { + comp_cl_warn(&comp_kpb, "partial pre-roll: capping drain to buffered"); + drain_req = kpb->hd.buffered; + } + /* Draining accepted, find proper buffer to start reading. + * If less history than requested is buffered, drain_req is + * capped above so we drain whatever is available. */ kpb_lock(kpb); @@ -1888,8 +2098,7 @@ static void kpb_init_draining(struct comp_dev *dev, struct kpb_client *cli) * shall take place. This time will be used to * synchronize us with application interrupts. */ - drain_interval = k_ms_to_cyc_ceil64(host_period_size / bytes_per_ms) / - KPB_DRAIN_NUM_OF_PPL_PERIODS_AT_ONCE; + drain_interval = k_ms_to_cyc_ceil64(host_period_size / bytes_per_ms); period_bytes_limit = host_period_size; comp_info(dev, "sync_draining_mode selected with interval %u [uS].", (unsigned int)k_cyc_to_us_near64(drain_interval)); @@ -1927,8 +2136,7 @@ static void kpb_init_draining(struct comp_dev *dev, struct kpb_client *cli) comp_set_attribute(comp_buffer_get_sink_component(kpb->host_sink), COMP_ATTR_COPY_TYPE, &kpb->force_copy_type); - /* Pause selector copy. */ - comp_buffer_get_sink_component(kpb->sel_sink)->state = COMP_STATE_PAUSED; + /* Do not pause selector copy; downstream detectors manage their own pause states */ if (!pm_runtime_is_active(PM_RUNTIME_DSP, PLATFORM_PRIMARY_CORE_ID)) pm_runtime_disable(PM_RUNTIME_DSP, PLATFORM_PRIMARY_CORE_ID); @@ -1967,10 +2175,10 @@ static void adjust_drain_interval(struct comp_data *kpb, struct draining_data *d /* average drained bytes per second */ actual_pace = (size_t)k_ms_to_cyc_ceil64(1000) / elapsed * drained; - pipeline_period = (size_t)KPB_SAMPLES_PER_MS * + pipeline_period = (size_t)(kpb->config.sampling_freq / 1000) * (KPB_SAMPLE_CONTAINER_SIZE(dd->sample_width) / 8) * kpb->config.channels; /* desired draining pace in bytes per second */ - optimal_pace = pipeline_period * KPB_DRAIN_NUM_OF_PPL_PERIODS_AT_ONCE * 1000; + optimal_pace = pipeline_period * 1000; /* just in case to prevent div by 0 if draining is stuck (e.g. because of host) */ if (actual_pace) { @@ -2035,6 +2243,11 @@ static enum task_state kpb_draining_task(void *arg) goto out; } + if (kpb->state != KPB_STATE_DRAINING) { + draining_data->drain_req = 0; + goto out; + } + adjust_drain_interval(kpb, draining_data); if (draining_data->drain_req > 0) { @@ -2077,20 +2290,23 @@ static enum task_state kpb_draining_task(void *arg) } if (size_to_copy) { + buffer_stream_writeback(sink, size_to_copy); comp_update_buffer_produce(sink, size_to_copy); - comp_copy(comp_buffer_get_sink_component(sink)); - } else if (!audio_stream_get_free_bytes(&sink->stream)) { - /* There is no free space in sink buffer. - * Call .copy() on sink component so it can - * process its data further. - */ - comp_copy(comp_buffer_get_sink_component(sink)); + struct comp_dev *host_comp = sink ? comp_buffer_get_sink_component(sink) : NULL; + if (host_comp) + comp_copy(host_comp); } if (sync_mode_on && draining_data->period_bytes >= period_bytes_limit) { draining_data->next_copy_time = draining_data->period_copy_start + draining_data->drain_interval; draining_data->period_copy_start = 0; + } else if (size_to_copy == 0 && draining_data->drain_req > 0) { + struct comp_dev *host_comp = sink ? comp_buffer_get_sink_component(sink) : NULL; + if (host_comp) + comp_copy(host_comp); + draining_data->next_copy_time = sof_cycle_get_64() + + (draining_data->drain_interval ? draining_data->drain_interval : k_ms_to_cyc_ceil64(1)); } else { draining_data->next_copy_time = 0; } @@ -2098,23 +2314,51 @@ static enum task_state kpb_draining_task(void *arg) /* also reached with a zero-length (no history) draining request */ if (draining_data->drain_req == 0) { - /* We have finished draining of requested data however - * while we were draining real time stream could provided - * new data which needs to be copy to host. - */ - comp_cl_info(&comp_kpb, "kpb: update drain_req by %zu", - *rt_stream_update); kpb_lock(kpb); - draining_data->drain_req += *rt_stream_update; - *rt_stream_update = 0; - if (!draining_data->drain_req && kpb->state == KPB_STATE_DRAINING) { - /* Draining is done. Now switch KPB to copy real time - * stream to client's sink. This state is called - * "draining on demand" - * Note! If KPB state changed during draining due to - * i.e reset request we should not change that state. + /* + * While draining of pre-roll history was underway, the real-time + * stream buffered newly arrived frames into the history buffer + * (*rt_stream_update). Drain them directly into the sink before + * transitioning to HOST_COPY so no frames are lost at the boundary. */ + while (*rt_stream_update > 0) { + buff = draining_data->hb; + avail = (uintptr_t)buff->end_addr - (uintptr_t)buff->r_ptr; + size_to_copy = MIN(avail, + MIN(*rt_stream_update, + audio_stream_get_free_bytes(&sink->stream))); + if (!size_to_copy) + break; + + kpb_drain_samples(buff->r_ptr, &sink->stream, size_to_copy, + sample_width); + + buff->r_ptr = (char *)buff->r_ptr + (uint32_t)size_to_copy; + *rt_stream_update -= size_to_copy; + draining_data->drained += size_to_copy; + kpb->hd.free += MIN(kpb->hd.buffer_size - + kpb->hd.free, size_to_copy); + + if (size_to_copy == avail) { + buff->r_ptr = buff->start_addr; + draining_data->hb = buff->next; + } + + buffer_stream_writeback(sink, size_to_copy); + comp_update_buffer_produce(sink, size_to_copy); + struct comp_dev *host_comp = sink ? comp_buffer_get_sink_component(sink) : NULL; + if (host_comp) + comp_copy(host_comp); + } + + if (*rt_stream_update == 0 && kpb->state == KPB_STATE_DRAINING) { + /* Draining is completely done. Switch KPB to copy real time + * stream to client's sink (HOST_COPY state). + */ kpb_change_state(kpb, KPB_STATE_HOST_COPY); + } else if (*rt_stream_update > 0) { + draining_data->drain_req = *rt_stream_update; + *rt_stream_update = 0; } kpb_unlock(kpb); } @@ -2378,30 +2622,6 @@ static void kpb_buffer_samples(const struct audio_stream *source, } } -/** - * \brief Initialize history buffer by zeroing its memory. - * \param[in] buff - pointer to current history buffer. - * - * \return: none. - */ -static void kpb_clear_history_buffer(struct history_buffer *buff) -{ - struct history_buffer *first_buff = buff; - void *start_addr; - size_t size; - - comp_cl_info(&comp_kpb, "entry"); - - do { - start_addr = buff->start_addr; - size = (uintptr_t)buff->end_addr - (uintptr_t)start_addr; - - bzero(start_addr, size); - - buff = buff->next; - } while (buff != first_buff); -} - static inline bool kpb_is_sample_width_supported(uint32_t sampling_width) { bool ret; @@ -2546,9 +2766,11 @@ static void kpb_reset_history_buffer(struct history_buffer *buff) if (!buff) return; - kpb_clear_history_buffer(buff); + do { + /* Reset to start so no stale data from a prior drain session is + * re-played on the next KPB activation. */ buff->w_ptr = buff->start_addr; buff->r_ptr = buff->start_addr; buff->state = KPB_BUFFER_FREE; @@ -2574,7 +2796,7 @@ static inline bool validate_host_params(struct comp_dev *dev, */ struct comp_data *kpb = comp_get_drvdata(dev); size_t sample_width = kpb->config.sampling_width; - size_t bytes_per_ms = (size_t)KPB_SAMPLES_PER_MS * + size_t bytes_per_ms = (size_t)(kpb->config.sampling_freq / 1000) * (KPB_SAMPLE_CONTAINER_SIZE(sample_width) / 8) * kpb->config.channels; size_t pipeline_period_size = (dev->pipeline->period / 1000) @@ -2898,6 +3120,16 @@ __cold static int kpb_set_large_config(struct comp_dev *dev, uint32_t param_id, #endif case KP_BUF_CLIENT_MIC_SELECT: return kpb_set_micselect(dev, data, data_offset); +#if CONFIG_IPC_MAJOR_4 + case KP_BUF_CFG_BUFF_TIME_MS: { + struct comp_data *kpb = comp_get_drvdata(dev); + if (data_offset < sizeof(uint32_t)) + return -EINVAL; + kpb->buff_time_ms = *(const uint32_t *)data; + comp_info(dev, "kpb: buff_time_ms set to %u ms", kpb->buff_time_ms); + return 0; + } +#endif default: return -EINVAL; } diff --git a/src/audio/kpb.toml b/src/audio/kpb.toml index e384632c1be8..60626997b96f 100644 --- a/src/audio/kpb.toml +++ b/src/audio/kpb.toml @@ -2,7 +2,7 @@ name = "KPB" uuid = UUIDREG_STR_KPB4 affinity_mask = "0x1" - instance_count = "1" + instance_count = "4" domain_types = "0" load_type = "0" module_type = "0xB" @@ -10,7 +10,12 @@ sched_caps = [1, 0x00008000] REM # pin = [dir, type, sample rate, size, container, channel-cfg] + REM # 1 source, 2 sinks: kpb.c drives a sel_sink (buf_id 0, the real-time + REM # feed to the detectors) and a host_sink (buf_id 1, the drain that + REM # bursts pre-roll to the host). Only one sink was declared here, so + REM # the drain path could not be bound from topology. pin = [0, 0, 0xfeef, 0xf, 0xf, 0x45ff, + 1, 0, 0xfeef, 0xf, 0xa, 0x45ff, 1, 0, 0xfeef, 0xf, 0xa, 0x45ff] REM # mod_cfg [PAR_0 PAR_1 PAR_2 PAR_3 IS_BYTES CPS IBS OBS MOD_FLAGS CPC OBLS] diff --git a/src/include/ipc4/kpb.h b/src/include/ipc4/kpb.h index 18476604728b..eb314ec2a600 100644 --- a/src/include/ipc4/kpb.h +++ b/src/include/ipc4/kpb.h @@ -32,6 +32,8 @@ struct ipc4_kpb_module_cfg { enum ipc4_kpb_module_config_params { /** Configure module IDs that execute within Fast Mode (FM) draining tasks. */ KP_BUF_CFG_FM_MODULE = 1, + /** Set history ring-buffer duration; 0 = use CONFIG_KPB_MAX_BUFF_TIME. */ + KP_BUF_CFG_BUFF_TIME_MS = 2, /** Real-time sink microphone channel selector ID. */ KP_BUF_CLIENT_MIC_SELECT = 11, }; diff --git a/src/include/sof/audio/kpb.h b/src/include/sof/audio/kpb.h index 74eeae964539..6c8007821637 100644 --- a/src/include/sof/audio/kpb.h +++ b/src/include/sof/audio/kpb.h @@ -26,17 +26,12 @@ #endif struct comp_buffer; +struct comp_dev *get_wov_detector_comp(uint32_t ppl_id); /* KPB internal defines */ -#if CONFIG_TIGERLAKE -#define KPB_MAX_BUFF_TIME 3000 /**< time of buffering in miliseconds */ -#define HOST_WAKEUP_TIME 1000 /* aprox. time of host DMA wakup from suspend [ms] */ -#else -/** Due to memory constraints on non-TGL platforms, the buffers are smaller. */ -#define KPB_MAX_BUFF_TIME 2100 /**< time of buffering in miliseconds */ -#define HOST_WAKEUP_TIME 0 /* aprox. time of host DMA wakup from suspend [ms] */ -#endif +#define KPB_MAX_BUFF_TIME CONFIG_KPB_MAX_BUFF_TIME /**< time of buffering in miliseconds */ +#define HOST_WAKEUP_TIME 0 /* host DMA already live; see CONFIG_KPB_MAX_BUFF_TIME */ #define KPB_MAX_DRAINING_REQ (KPB_MAX_BUFF_TIME - HOST_WAKEUP_TIME) #define KPB_MAX_SUPPORTED_CHANNELS 6 /**< number of supported channels */ @@ -47,7 +42,7 @@ struct comp_buffer; #define KPB_MAX_BUFFER_SIZE(sw, channels_number) ((KPB_SAMPLNG_FREQUENCY / 1000) * \ (KPB_SAMPLE_CONTAINER_SIZE(sw) / 8) * KPB_MAX_BUFF_TIME * \ (channels_number)) -#define KPB_MAX_NO_OF_CLIENTS 4 +#define KPB_MAX_NO_OF_CLIENTS CONFIG_KPB_MAX_NO_OF_CLIENTS #define KPB_MAX_SINK_CNT (1 + KPB_MAX_NO_OF_CLIENTS) #define KPB_NO_OF_HISTORY_BUFFERS 2 /**< no of internal buffers */ #define KPB_ALLOCATION_STEP 0x100 From bac4a73567b2908c4b76b649bcc77803f98d9dd8 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 16 Nov 2026 12:05:45 +0000 Subject: [PATCH 11/31] audio: wov_arbiter: add multi-slot WOV arbiter component Add the WOV arbiter component (CONFIG_COMP_WOV_ARBITER) to arbitrate between multiple concurrent keyword detector slots sharing a single host WoV capture PCM: - First-wins slot arbitration on NOTIFIER_ID_WOV_DETECT, broadcasting NOTIFIER_ID_WOV_CTRL pause/resume to sibling detectors. - Rate-limited PHRASE_DETECTED host notifications (sent once per detection) and active slot reset without requiring pipeline teardown. - Support mixed 16/32-bit sample widths, single active WoV PCM gating, and call-state gate control. Signed-off-by: Liam Girdwood Co-authored-by: Naveen Manohar Signed-off-by: Naveen Manohar Co-authored-by: Seppo Ingalsuo Signed-off-by: Seppo Ingalsuo Co-authored-by: Peter Ujfalusi Signed-off-by: Peter Ujfalusi --- src/audio/CMakeLists.txt | 3 + src/audio/Kconfig | 11 + src/audio/wov_arbiter/CMakeLists.txt | 3 + src/audio/wov_arbiter/README.md | 1502 ++++++++++++++++++++++++ src/audio/wov_arbiter/wov_arbiter.c | 813 +++++++++++++ src/audio/wov_arbiter/wov_arbiter.toml | 19 + src/include/sof/audio/component.h | 1 + tools/rimage/config/nvl.toml.h | 4 + tools/rimage/config/ptl.toml.h | 4 + tools/rimage/config/tgl.toml.h | 4 + tools/rimage/config/wcl.toml.h | 4 + uuid-registry.txt | 1 + 12 files changed, 2369 insertions(+) create mode 100644 src/audio/wov_arbiter/CMakeLists.txt create mode 100644 src/audio/wov_arbiter/README.md create mode 100644 src/audio/wov_arbiter/wov_arbiter.c create mode 100644 src/audio/wov_arbiter/wov_arbiter.toml diff --git a/src/audio/CMakeLists.txt b/src/audio/CMakeLists.txt index 0ca532950f5c..205b7479ee24 100644 --- a/src/audio/CMakeLists.txt +++ b/src/audio/CMakeLists.txt @@ -122,6 +122,9 @@ endif() if(CONFIG_COMP_WEBRTC_HPF) add_subdirectory(webrtc_hpf) endif() +if(CONFIG_COMP_WOV_ARBITER) + add_subdirectory(wov_arbiter) +endif() if(CONFIG_DTS_CODEC) add_subdirectory(codec) endif() diff --git a/src/audio/Kconfig b/src/audio/Kconfig index 8468570fe45a..8a3579b1cd08 100644 --- a/src/audio/Kconfig +++ b/src/audio/Kconfig @@ -153,6 +153,17 @@ config COMP_STUBS Select to force all 3P blocks to link against stubs rather than their libraries. This should only be used in testing environments like fuzzers or CI. +config COMP_WOV_ARBITER + bool "WOV arbiter component" + depends on COMP_KPB + depends on IPC_MAJOR_4 + help + Select to build the WOV (Wake-on-Voice) arbiter. The arbiter sits + between multiple KPB host-drain outputs and a single host PCM copier. + When a keyword is detected by one of the WOV detectors the arbiter + routes that KPB's drain stream to the host and instructs the remaining + detectors to pause. + config COMP_KPB bool "KPB component" default y diff --git a/src/audio/wov_arbiter/CMakeLists.txt b/src/audio/wov_arbiter/CMakeLists.txt new file mode 100644 index 000000000000..fd15150321c6 --- /dev/null +++ b/src/audio/wov_arbiter/CMakeLists.txt @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: BSD-3-Clause + +add_local_sources(sof wov_arbiter.c) diff --git a/src/audio/wov_arbiter/README.md b/src/audio/wov_arbiter/README.md new file mode 100644 index 000000000000..e9b18fbe8d80 --- /dev/null +++ b/src/audio/wov_arbiter/README.md @@ -0,0 +1,1502 @@ +# Multi-Slot Wake-On-Voice (WOV) Architecture & Arbitration + +## Overview + +The Multi-Slot WOV subsystem lets a single DMIC feed concurrent keyword detectors +running on the DSP. Audio is captured directly over a standard ALSA PCM capture device +(`hw:0,11`, 16 kHz, 2-channel, S16_LE / S32_LE). + +Audio stream capture and device verification are executed using direct Linux ALSA UAPI ioctls +(`tools/wov_capture/wov_capture_app`) or standard ALSA tools (`arecord`). + +--- + +## Table of Contents + +1. [System Architecture](#system-architecture) +2. [Signal Processing Flow](#signal-processing-flow) +3. [Arbiter State Machine](#arbiter-state-machine) +4. [Pipeline State Transitions & Re-Arm Cycle](#pipeline-state-transitions--re-arm-cycle) + - [WoV Call-State Control](#wov-call-state-control) +5. [SOF Notifier Inter-Module Signaling](#sof-notifier-inter-module-signaling) +6. [Firmware API Reference](#firmware-api-reference) +7. [Linux Host API Reference](#linux-host-api-reference) +8. [Adding a New WOV Algorithm](#adding-a-new-wov-algorithm) +9. [Topology: Build and Deploy](#topology-build-and-deploy) +10. [Build System Configuration](#build-system-configuration) +11. [Testing and Verification](#testing-and-verification) + +--- + +## System Architecture + +The Multi-Slot WOV subsystem supports two primary topology architectures: +1. **4-Channel Native 16 kHz DMIC with ECNS & Multi-Slot WOV** (PTL, TGL, WCL 4ch native manifests). +2. **2-Channel DMIC / SSP Direct Multi-Slot WOV** (2ch manifests). + +--- + +#### Architecture A: Dual-Rate DMIC with ECNS & microWakeWord (MWW) Multi-Slot WOV + +In this architecture, two dedicated physical PDM digital microphone interfaces feed the **ECNS DP module** running at a 20 ms period: +- **PDM1 (`dmic16k`)**: Dedicated 16 kHz stereo stream via Pipeline 119 feeding ECNS Input Pin 0. +- **PDM0 (`dmic01`)**: Dedicated 48 kHz stereo stream via Pipeline 110 feeding ECNS Input Pin 1. + +The ECNS module processes both streams and outputs: +- **Pin 0 (mono clean speech)**: Extracts the Left channel from Pin 0 in to produce a 16 kHz mono clean stream. Routes to KPB (Pipeline 116, 2.0s history depth = 64 KB mono buffer), then fans out via `mixin.116.1` to 3 concurrent **microWakeWord (MWW)** keyword spotting slots (running MFCC feature extraction + TFLM streaming graph in lock-step). Upon keyword detection, the detector notifies KPB (`NOTIFIER_ID_KPB_CLIENT_EVT`) to drain and the WOV Arbiter (`NOTIFIER_ID_WOV_DETECT`) to set `wov_active_slot` and pause sibling slots. The WOV Arbiter routes the active slot audio (pre-roll + live) to ALSA PCM 12 (`hw:0,12`, `DMIC Multi-WOV`, `capture_compatible_d0i3: true`). +- **Pin 1 (stereo clean speech)**: Performs a 1-to-1 copy of Pin 1 in to produce a 48 kHz stereo clean stream routed to Host Copier 11 (ALSA PCM 11, `hw:0,11`, `DMIC ECNS Capture`, `capture_compatible_d0i3: true`). + +```mermaid +flowchart TD + %% Hardware PDM Interfaces + subgraph PDM_INTERFACES ["Digital Microphone Interfaces (2 Separate PDM DAIs)"] + direction LR + PDM_48K["PDM Interface: dmic01
DAI Index: 0 (PDM0)
Rate: 48 kHz · 2ch Stereo · 16-bit"] + PDM_16K["PDM Interface: dmic16k
DAI Index: 1 (PDM1)
Rate: 16 kHz · 2ch Stereo · 16-bit"] + end + + %% Pipeline 110: 48 kHz DAI Capture + subgraph P110 ["Pipeline 110: 48 kHz DAI Capture (Core 0, LL 1ms)"] + DAI_48K["dai-copier.DMIC.dmic01.capture
(48 kHz · 2ch · S16_LE)"] + MIXIN_110["mixin.110.1
(48 kHz · 2ch)"] + DAI_48K --> MIXIN_110 + end + + %% Pipeline 119: 16 kHz DAI Capture + subgraph P119 ["Pipeline 119: 16 kHz DAI Capture (Core 0, LL 1ms)"] + DAI_16K["dai-copier.DMIC.dmic16k.capture
(16 kHz · 2ch · S16_LE)"] + MIXIN_119["mixin.119.1
(16 kHz · 2ch)"] + DAI_16K --> MIXIN_119 + end + + PDM_48K --> DAI_48K + PDM_16K --> DAI_16K + + %% Pipeline 115: Dual-Rate ECNS DP Pipeline + subgraph P115 ["Pipeline 115: ECNS Engine (Core 0, DP 20ms, lp_mode 1)"] + direction TB + + MIXOUT_115_2["mixout.115.2
(Pin 0 In: 16 kHz · 2ch stereo)"] + MIXOUT_115_1["mixout.115.1
(Pin 1 In: 48 kHz · 2ch stereo)"] + + ECNS["ecns.115.1 (DP Component · 20ms Period)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pin 0 In: 16 kHz, 2ch (IBS 1280 bytes)
Pin 1 In: 48 kHz, 2ch (IBS 3840 bytes)
─────────────────────────────
Processing:
• Pin 0: Extract Left Ch → 16k Mono Clean
• Pin 1: 1-to-1 Stereo Copy → 48k Stereo Clean
─────────────────────────────
Pin 0 Out: 16 kHz, 1ch mono (OBS 640 bytes)
Pin 1 Out: 48 kHz, 2ch stereo (OBS 3840 bytes)"] + + MIXOUT_115_2 -->|"Pin 0 In (16k)"| ECNS + MIXOUT_115_1 -->|"Pin 1 In (48k)"| ECNS + end + + MIXIN_119 --> MIXOUT_115_2 + MIXIN_110 --> MIXOUT_115_1 + + %% Pipeline 117: Host Capture PCM 11 + subgraph P117 ["Pipeline 117: ECNS Clean Host Capture (Core 0, LL 1ms)"] + HOST_11["host-copier.11.capture
(PCM 11: 'DMIC ECNS Capture'
hw:0,11 · d0i3_compatible=true)"] + end + + %% Pipeline 116: KPB History Buffer + subgraph P116 ["Pipeline 116: Key Phrase Buffer (Core 0, DP 20ms)"] + KPB["kpb.116.1
(2000 ms mono history = 64 KB)"] + MIXIN_116["mixin.116.1
(3-way detector fanout)"] + KPB -->|"Pin 0 (Live Feed)"| MIXIN_116 + end + + ECNS -->|"Pin 1 Out (Stereo 48k clean direct)"| HOST_11 + ECNS -->|"Pin 0 Out (Mono 16k clean direct)"| KPB + + %% WoV 3-Slot Detector Subgraph + subgraph SLOTS ["Wake-on-Voice Keyword Detector Slots (16 kHz mono)"] + subgraph S1 ["Slot 0 (Pipeline 111)"] + M1["mixout.111.1"] --> MF1["mfcc.111.1"] --> MW1["mww.111.1"] + end + subgraph S2 ["Slot 1 (Pipeline 112)"] + M2["mixout.112.1"] --> MF2["mfcc.112.1"] --> MW2["mww.112.1"] + end + subgraph S3 ["Slot 2 (Pipeline 113)"] + M3["mixout.113.1"] --> MF3["mfcc.113.1"] --> MW3["mww.113.1"] + end + end + + MIXIN_116 --> M1 + MIXIN_116 --> M2 + MIXIN_116 --> M3 + + %% Pipeline 114: WoV Arbiter & Host Capture PCM 12 + subgraph P114 ["Pipeline 114: WoV Arbiter (Core 0, LL 1ms)"] + ARB["wov-arbiter.114.1
• Pin 0: Drained audio stream
• Pins 1-3: Keyword triggers"] + HOST_12["host-copier.12.capture
(PCM 12: 'DMIC Multi-WOV'
hw:0,12 · d0i3_compatible=true)"] + ARB --> HOST_12 + end + + KPB -->|"Pin 1 (Host Sink Drain)"| ARB + MW1 -->|"Pin 1 (Trigger 0)"| ARB + MW2 -->|"Pin 2 (Trigger 1)"| ARB + MW3 -->|"Pin 3 (Trigger 2)"| ARB + + MW1 -. "Notifier WOV_DETECT (slot=0)" .-> ARB + MW2 -. "Notifier WOV_DETECT (slot=1)" .-> ARB + MW3 -. "Notifier WOV_DETECT (slot=2)" .-> ARB + MW1 -. "Notifier KPB_CLIENT_EVT (DRAIN 2s)" .-> KPB + MW2 -. "Notifier KPB_CLIENT_EVT (DRAIN 2s)" .-> KPB + MW3 -. "Notifier KPB_CLIENT_EVT (DRAIN 2s)" .-> KPB + ARB -. "Notifier WOV_CTRL (PAUSE/RESUME)" .-> MW1 + ARB -. "Notifier WOV_CTRL (PAUSE/RESUME)" .-> MW2 + ARB -. "Notifier WOV_CTRL (PAUSE/RESUME)" .-> MW3 + + style ECNS fill:#1b4f72,stroke:#555,color:#fff + style KPB fill:#1c4966,stroke:#555,color:#fff + style ARB fill:#4a235a,stroke:#555,color:#fff + style HOST_11 fill:#1e8449,stroke:#555,color:#fff + style HOST_12 fill:#2d5a27,stroke:#555,color:#fff +``` + +#### Dual-Rate Architecture Specifications across Target Platforms (PTL, TGL, WCL) + +The dual-rate DMIC architecture is deployed across **Panther Lake (PTL)**, **Tiger Lake (TGL)**, and **Wildcat Lake (WCL)** via `platform/intel/dmic-wov-multi.conf` and `dmic-wov-feature.conf`: + +| Property | ECNS Clean Stream (PCM 11) | WOV Stream (PCM 12) | +|---|---|---| +| ALSA Device | `hw:0,11` (`pcmC0D11c`) | `hw:0,12` (`pcmC0D12c`) | +| Sample Rate | 48 kHz | 16 kHz | +| Channels | 2 (Stereo clean mic) | 1 (Mono clean mic) | +| Sample Format | S16_LE / S32_LE | S16_LE / S32_LE | +| History / Pre-roll | Live streaming | 2.0 s (64 KB mono buffer in KPB) | +| Keyword Spotters | N/A | 3 concurrent slots: 0="strawberry", 1="hi intel", 2="orange" | +| Keyword Control | N/A | `wov_active_slot` enum (0=Listening, 1=Slot 0, 2=Slot 1, 3=Slot 2) | +| Scheduling | Core 0 (LL 1ms) | Core 0 (LL 1ms arbiter + DP 20ms KPB + DP 10ms MWW) | +| Processing Source | ECNS Pin 1 (1-to-1 copy of 48k `dmic01`) | ECNS Pin 0 (mono Left ch of 16k `dmic16k`) via KPB & WOV Arbiter | +| D0i3 Low Power | **Yes** (`capture_compatible_d0i3: true`) | **Yes** (`capture_compatible_d0i3: true`) | + +--- + +### Architecture B: 2-Channel Direct DMIC / SSP Multi-Slot WOV + +For 2-channel capture topologies (`dmic-wov-multi-manifest.conf`, `sspX-wov-multi-manifest.conf`): + +```mermaid +graph TD + subgraph P100["Pipeline 100 — Capture & History Buffer (Core 0)"] + DAI["DAI Copier\n(48 kHz 4ch NHLT / 16 kHz SSP)"] + SRC["SRC (optional)\n(48 kHz -> 16 kHz)"] + KPB["kpb\n(16 kHz shared history ring buffer)"] + MIX["mixin\n(fan-out)"] + DAI --> SRC --> KPB --> MIX + end + + subgraph P101["Pipeline 101 — Slot 0 (Core 0)"] + MO0["mixout 0"] + D0["detect_test\nSlot 0\n(Male 80–170 Hz)"] + MO0 --> D0 + end + + subgraph P102["Pipeline 102 — Slot 1 (Core 0)"] + MO1["mixout 1"] + D1["detect_test\nSlot 1\n(Female 175–270 Hz)"] + MO1 --> D1 + end + + subgraph P103["Pipeline 103 — Slot 2 (Multi-slot) (Core 1)"] + MO2["mixout 2"] + D2["detect_test\nSlot 2\n(Child 275–500 Hz)"] + MO2 --> D2 + end + + subgraph P104["Pipeline 104 — Host Regular PCM Capture (Core 0)"] + ARB["wov_arbiter\n(3 input pins)"] + HC["host-copier\npcmC0D11c (hw:0,11)\n'DMIC Multi-WOV'"] + ARB --> HC + end + + MIX --> MO0 + MIX --> MO1 + MIX --> MO2 + + D0 --> ARB + D1 --> ARB + D2 --> ARB + + D0 -- "Notifier WOV_DETECT\n(slot_id=0)" --> ARB + D1 -- "Notifier WOV_DETECT\n(slot_id=1)" --> ARB + D2 -- "Notifier WOV_DETECT\n(slot_id=2)" --> ARB + ARB -- "Notifier WOV_CTRL\n(PAUSE/RESUME)" --> D0 + ARB -- "Notifier WOV_CTRL\n(PAUSE/RESUME)" --> D1 + ARB -- "Notifier WOV_CTRL\n(PAUSE/RESUME)" --> D2 + + style KPB fill:#1c4966,stroke:#555,color:#fff + style D0 fill:#663300,stroke:#555,color:#fff + style D1 fill:#660033,stroke:#555,color:#fff + style D2 fill:#003366,stroke:#555,color:#fff + style ARB fill:#4a235a,stroke:#555,color:#fff + style HC fill:#2d5a27,stroke:#555,color:#fff +``` + +#### 2-Channel Architecture Specifications + +| Property | Value | +|---|---| +| Audio format | 16 kHz · 2ch · S16_LE / S32_LE | +| KPB pre-roll (TigerLake) | 6 000 ms (192 000 bytes) | +| KPB pre-roll (other) | 2 100 ms | +| Max arbiter slots | 3 (topology), 8 (header constant) | +| Arbitration policy | First-wins; subsequent detections ignored until RESUME | +| Slot 2 core affinity | DSP Core 1 (cross-core scheduling validation) | +| Host capture device | card 0, device 11 — `hw:0,11` / `pcmC0D11c` (ALSA PCM) | +| Audio Delivery | Standard ALSA PCM capture stream (16 kHz, 2-channel, 16-bit / 32-bit) | +| D0i3 / S0iX | Supported — `capture_compatible_d0i3 true` on host-copier and PCM widget | + +--- + +## Signal Processing Flow + +### LL Thread Path (every 1 ms) + +```mermaid +flowchart LR + HW["HW DMA\n(DMIC interrupt)"] + DAI_COPY["dai_copier.copy()\nPipeline 100"] + SRC_COPY["src.copy()\n48k -> 16k"] + KPB_COPY["kpb.copy()\n16k ring buffer"] + MIXIN["mixin.copy()\nfan-out"] + MIXOUT["mixout_N.copy()"] + DT_COPY["detect_test.copy()\naccumulate 320 frames\nthen k_sem_give()"] + + HW --> DAI_COPY --> SRC_COPY --> KPB_COPY --> MIXIN + MIXIN --> MIXOUT --> DT_COPY +``` + +### DP Thread Path (every 20 ms per slot) + +Each slot has its own `k_thread` at `K_PRIO_PREEMPT(12)` executing batch processing. + +```mermaid +flowchart TD + SEM["k_sem_take()"] + CHECK{dp_thread_active?} + BUF["read dp_buf[read_slot]\n320 × S16_LE samples"] + DETECT["run detection algorithm\n(zero-crossing + energy)"] + FOUND{match?} + NOTIFY["detect_test_notify(dev)\n① IPC4 → host\n② KPB drain (notify_event)\n③ Notifier WOV_DETECT → arbiter"] + AUTOTRIG["auto-trigger\n(test only, limit=320 frames)"] + LOOP(["loop"]) + + SEM --> CHECK + CHECK -- "false" --> EXIT(["thread exits"]) + CHECK -- "true" --> BUF --> DETECT --> FOUND + FOUND -- "yes" --> NOTIFY --> LOOP + FOUND -- "no" --> AUTOTRIG --> LOOP + LOOP --> SEM +``` + +### KPB Drain Sequence (triggered by Notifier) + +```mermaid +flowchart LR + NOTIF_EVT["Notifier WOV_DETECT\n→ arb_on_detect()"] + DRAIN["drain KPB history ring buffer\n(up to 6 s pre-roll)\nto host capture buffer"] + LIVE["continue forwarding\nlive audio to host PCM"] + + NOTIF_EVT --> DRAIN --> LIVE +``` + +--- + +## Arbiter State Machine + +```mermaid +stateDiagram-v2 + [*] --> Idle : wov_arb_new() / prepare()\nactive_slot = NO_ACTIVE\nbroadcast RESUME + + Idle --> Active : Notifier WOV_DETECT(slot_id=N)\nactive_slot = N\nbroadcast PAUSE(N) + + Active --> Active : Notifier WOV_DETECT(slot_id=M)\n[first-wins: ignored] + + Active --> Idle : trigger(STOP or PAUSE)\nactive_slot = NO_ACTIVE\nbroadcast RESUME + + Idle --> [*] : wov_arb_free() +``` + +### `wov_arb_copy()` Routing Logic + +| Condition | Active slot buffer | Idle slot buffers | Sink output | +|---|---|---|---| +| `active_slot == NO_ACTIVE` | — | drained and discarded | filled with silence (memset 0) | +| `active_slot == N` | copied frame-aligned to sink | drained and discarded | pre-roll + live audio | + +The first-wins guard in `arb_on_detect()`: + +```c +if (cd->active_slot != WOV_ARB_NO_ACTIVE) { + comp_warn(dev, "wov_arb: slot %u fired but slot %u already active, ignoring", + det->slot_id, cd->active_slot); + return; +} +``` + +--- + +## Pipeline State Transitions & Re-Arm Cycle + +### Usage Flow (PCM Capture Stream Lifecycle) + +The PCM capture stream can be opened at startup or on-demand: + +```text +Host Kernel / ASoC Firmware +──── ───────────── ──────── +open pcmC0D11c ──► SET_PIPELINE_STATE(RUNNING) ──► KPBs: KPB_STATE_BUFFERING (filling history) + detect_tests: dp_thread running, listening + +─────────────────────── Listening / Capture ─────────────────────────── +arecord / wov_capture_app captures frames at 16 kHz 2-channel from hw:0,11 +``` + +### State Transition Summary + +| State | Transition | Trigger | PCM Capture device | +|---|---|---|---| +| Listening → Active | WOV_DETECT | detect_test fires | Stays OPEN | +| Active → Listening | STOP/PAUSE | host or driver closes/re-arms | Stays OPEN (re-armed) | +| Any → closed | close() | host exits | Closed | + +### WoV Call-State Control + +Set `DMIC WoV Call State` to `Call Active` to pause all detectors. The arbiter +acknowledges after detector callbacks complete; set it to `Listening` to resume. + +The acknowledgement confirms detector gating, not pipeline teardown. The Audio +HAL must close the WoV pipeline and wait for teardown before starting the call +path. On call end, close the call path before reopening WoV. + +--- + +## SOF Notifier Inter-Module Signaling + +The SOF Notifier system (`src/include/sof/lib/notifier.h`) is SOF's intra-DSP +publish/subscribe bus. It works on all platforms (no `CONFIG_AMS` required) and +is already used for KPB client events. Signals are delivered synchronously to +all registered listeners on the calling core. + +### Signal Catalog + +| Notifier ID | Direction | Payload struct | Purpose | +|---|---|---|---| +| `NOTIFIER_ID_WOV_DETECT` | detector → arbiter | `struct wov_detect_notif { uint8_t slot_id; }` | Announce keyword detection | +| `NOTIFIER_ID_WOV_CTRL` | arbiter → all detectors | `struct wov_ctrl_notif { uint8_t cmd; }` | Pause/resume detectors | + +`cmd` values: `WOV_ARB_CMD_PAUSE`, `WOV_ARB_CMD_RESUME` (defined in `wov_arbiter.h`). + +### Full Detect-to-Drain Sequence + +```mermaid +sequenceDiagram + autonumber + participant DMIC as DMIC (HW) + participant KPB as KPB N + participant DET as detect_test (slot N) + participant ARB as wov_arbiter + participant HOST as Host PCM (hw:0,11) + participant OTHER as detect_test (slots ≠ N) + + Note over DMIC,OTHER: Listening state — all slots accumulating pre-roll + + loop Every 1 ms (LL period) + DMIC->>KPB: DAI DMA frames + KPB->>DET: sel_sink copy + end + + loop Every 20 ms (DP batch) + DET->>DET: run algorithm on 320-frame batch + end + + Note over DET,ARB: Keyword detected on slot N + + DET->>HOST: ① IPC4 SOF_IPC4_NOTIFY_PHRASE_DETECTED\n (word_id = slot_id) + DET->>KPB: ② notifier_event(WOV_DETECT) [KPB already wired via kpb_client] + DET->>ARB: ③ notifier_event(NOTIFIER_ID_WOV_DETECT, slot_id=N) + + ARB->>ARB: active_slot = N + ARB->>OTHER: notifier_event(NOTIFIER_ID_WOV_CTRL, cmd=PAUSE) + OTHER->>OTHER: cd->paused = true\n(stops DP batching) + + KPB->>ARB: stream pre-roll (up to 6 s) via host_sink + ARB->>HOST: route slot-N audio to host PCM + + Note over HOST,ARB: Host finishes reading / closes PCM + + HOST->>ARB: trigger STOP (ALSA hw_free / snd_pcm_close) + ARB->>ARB: active_slot = NO_ACTIVE + ARB->>OTHER: notifier_event(NOTIFIER_ID_WOV_CTRL, cmd=RESUME) + ARB->>DET: notifier_event(NOTIFIER_ID_WOV_CTRL, cmd=RESUME) + OTHER->>OTHER: cd->paused = false\ncd->detected = 0\nresumed listening +``` + +--- + +## Firmware API Reference + +### IPC4 Module Parameters (`LARGE_CONFIG_SET`) + +#### `detect_test` — automatic slot assignment via pipeline ID + +Each `detect_test` instance is automatically assigned its slot ID in `test_keyword_new()` +based on its pipeline ID: + +| Pipeline ID | Target module | Core | Assigned Slot | +|---|---|---|---| +| 101 | `wov.101.1` | Core 0 | Slot 0 | +| 102 | `wov.102.1` | Core 0 | Slot 1 | +| 103 | `wov.103.1` | Core 1 | Slot 2 | + +No user-space initialization kcontrols are required. + +#### `wov_arbiter` — active slot status via `Phrase Detect ID` enum kcontrol + +The `wov_arbiter` instances expose a volatile read-only ALSA enum kcontrol named `DMIC Phrase Detect ID` +(for DMIC WoV graphs) or `Jack In Phrase Detect ID` (for SoundWire headset WoV graphs; legacy topologies +use `wov_active_slot`) that reports the current arbitration and keyword detection state: + +| Enum Index | Item Name | Meaning | +|---|---|---| +| `0` | `Listening` | No keyword detected / idle / listening | +| `1` | `Slot 1` | Slot 0 (Pipeline 101/111/201) triggered and active | +| `2` | `Slot 2` | Slot 1 (Pipeline 102/112/202) triggered and active | +| `3` | `Slot 3` | Slot 2 (Pipeline 103/113/203) triggered and active | + +When a keyword detector fires, the arbiter updates `cd->active_slot` and automatically sends an +ALSA control change notification (`SOF_IPC4_MODULE_NOTIFICATION` with `SOF_IPC4_ENUM_CONTROL_PARAM_ID`) +to notify the kernel / ALSA mixer of the state transition. When the capture stream is stopped or reset, +the arbiter transitions back to `Listening` (`0`) and sends a notification. + +Query the control from userspace: + +```bash +# For DMIC WoV: +amixer -c 0 cget name='DMIC Phrase Detect ID' + +# For SDW Headset WoV: +amixer -c 0 cget name='Jack In Phrase Detect ID' +``` + +#### `detect_test` — per-slot mute via `wov_mute_1NN` switch kcontrol + +Each `detect_test` instance also exposes a boolean switch kcontrol that gates +detection at runtime without tearing down the pipeline. + +| ALSA kcontrol name | numid (TGL) | Default | Effect when set | +|---|---|---|---| +| `wov_mute_101` | 13 | `off` | `off` = muted (no detection), `on` = detection active | +| `wov_mute_102` | 16 | `off` | `off` = muted (no detection), `on` = detection active | +| `wov_mute_103` | 19 | `off` | `off` = muted (no detection), `on` = detection active | + +The default at pipeline open is `off` (muted). Userspace must explicitly write `on` +to arm a slot. When muted, `test_keyword_copy` drains the source buffer and returns +without running the detection algorithm, keeping the LL scheduler running at zero +detection cost. When re-enabled, detection resumes immediately on the next LL tick. + +Wire format: `LARGE_CONFIG_SET` with `PARAM_ID = 200` +(`SOF_IPC4_SWITCH_CONTROL_PARAM_ID`), payload +`struct sof_ipc4_control_msg_payload { .id=0, .num_elems=1, .chanv[0].value=0|1 }`. + +```bash +# Arm slot 1 for detection (numid=16 = wov_mute_102) +amixer -c 0 cset numid=16 on + +# Mute slot 1 again +amixer -c 0 cset numid=16 off +``` + +#### `detect_test` — momentary test trigger via `wov_test_1NN` switch kcontrol + +Each `detect_test` instance exposes a momentary boolean switch kcontrol that forces an +immediate keyword detection trigger on the slot. + +| ALSA kcontrol name | numid (TGL) | Default | Effect when set | +|---|---|---|---| +| `wov_test_101` | 14 | `off` | Write `on` to trigger detection for slot 0; auto-resets to `off` | +| `wov_test_102` | 17 | `off` | Write `on` to trigger detection for slot 1; auto-resets to `off` | +| `wov_test_103` | 20 | `off` | Write `on` to trigger detection for slot 2; auto-resets to `off` | + +Wire format: `LARGE_CONFIG_SET` with `PARAM_ID = 200` (`SOF_IPC4_SWITCH_CONTROL_PARAM_ID`), +payload `struct sof_ipc4_control_msg_payload { .id=1, .num_elems=1, .chanv[0].value=1 }`. + +When `wov_test_1NN` receives a write of value `1`: +1. The firmware logs `kd_test: TEST SWITCH TRIGGER for slot N!`. +2. It sets `cd->detected = 1` and calls `detect_test_notify(dev)` to trigger KPB history buffer drain and notify the WOV arbiter. +3. The firmware sends an IPC4 module notification (`SOF_IPC4_MODULE_NOTIFICATION` with `SOF_IPC4_NOTIFY_MODULE_EVENTID_ALSA_MAGIC_VAL | SOF_IPC4_SWITCH_CONTROL_PARAM_ID`) to reset the ALSA mixer switch value back to `0` (`off`) on the host. + +```bash +# Trigger detection on slot 0 (numid=14 = wov_test_101) +amixer -c 0 cset numid=14 on + +# Trigger detection on slot 1 (numid=17 = wov_test_102) +amixer -c 0 cset numid=17 on + +# Trigger detection on slot 2 (numid=20 = wov_test_103) +amixer -c 0 cset numid=20 on +``` + + +### `wov_arbiter` — slot count from `nb_input_pins` + +The arbiter reads the number of active slots from `ipc4_base_module_cfg_ext.nb_input_pins` +(set in `wov-arbiter.conf` via `num_input_pins = 3`). + +### Notifier Registration + +A WOV detector must register for `WOV_CTRL` notifications during `prepare()`: + +```c +notifier_register(dev, NULL, NOTIFIER_ID_WOV_CTRL, on_wov_ctrl); +``` + +Unregister in `free()`: + +```c +notifier_unregister(dev, NULL, NOTIFIER_ID_WOV_CTRL); +``` + +### `detect_test_notify(dev)` — Detection Announcement + +Call this from your detection algorithm when a keyword is confirmed: + +```c +void detect_test_notify(const struct comp_dev *dev); +``` + +Internally executes three steps: +1. Sends `SOF_IPC4_NOTIFY_PHRASE_DETECTED` IPC4 notification to host +2. Sends `kpb_client` notifier event to KPB → triggers pre-roll drain on `host_sink` +3. Fires `notifier_event(NOTIFIER_ID_WOV_DETECT)` → `wov_arbiter.arb_on_detect()` activates this slot + +### DP Thread Ping-Pong Buffer Contract + +| Field | Type | Semantics | +|---|---|---| +| `dp_buf[2][320]` | `int16_t` | ping-pong accumulation buffer | +| `dp_buf_frames` | `uint32_t` | frames in write slot (0 to 319) | +| `dp_write_slot` | `uint8_t` | index (0 or 1) LL writes into | +| `dp_read_slot` | `uint8_t` | index DP thread reads from | +| `dp_sem` | `struct k_sem` | binary semaphore, max count = 1 | +| `dp_thread_active` | `bool` | false → thread exits on next wake | + +LL thread gives semaphore after every 320 accumulated frames. +DP thread takes semaphore and processes `dp_buf[dp_read_slot]`. +Missing a give (while thread is still processing) drops that batch silently +(semaphore max count = 1 prevents accumulation). + +--- + +## Linux Host API Reference + +### ALSA Regular PCM Capture + +The WOV audio is exposed as a standard **ALSA PCM** capture device (`hw:0,11` or `/dev/snd/pcmC0D11c`). +Standard tools like `arecord` and the zero-dependency C capture utility `wov_capture_app` interact directly with this endpoint: + +```text +Card: 0 PCM device: 11 Name: "DMIC Multi-WOV" (/dev/snd/pcmC0D11c) +Formats: S16_LE / S32_LE (raw PCM) +Rate: 16000 Hz +Channels: 2 (stereo) +``` + +Capture using `arecord`: + +```bash +arecord -D hw:0,11 -f S16_LE -r 16000 -c 2 -d 3 /tmp/wov_capture.wav +``` + +Zero-dependency C API flow using direct Linux ALSA kernel UAPI ioctls: + +```c +#include +#include +#include +#include + +int fd = open("/dev/snd/pcmC0D11c", O_RDWR); + +/* 1. Configure HW parameters (rate, channels, format, periods) */ +struct snd_pcm_hw_params params; +snd_pcm_hw_params_any(¶ms); +/* ... set rate=16000, channels=2, format=SNDRV_PCM_FORMAT_S16_LE ... */ +ioctl(fd, SNDRV_PCM_IOCTL_HW_PARAMS, ¶ms); + +/* 2. Configure SW parameters and prepare */ +ioctl(fd, SNDRV_PCM_IOCTL_PREPARE); + +/* 3. Start stream and capture frames via SNDRV_PCM_IOCTL_READI_FRAMES */ +struct snd_xferi xfer = { .buf = audio_buffer, .frames = period_size }; +ioctl(fd, SNDRV_PCM_IOCTL_READI_FRAMES, &xfer); + +/* 4. Stop and close */ +ioctl(fd, SNDRV_PCM_IOCTL_DROP); +close(fd); +``` + +### Voice Detection Notification from Firmware + +When a keyword is detected, the `detect_test` DP thread calls `detect_test_notify()` which: + +1. Sends `SOF_IPC4_NOTIFY_PHRASE_DETECTED` (IPC4 global notification, type=4) to the host. +2. Fires the KPB notifier to stream audio on the host capture pipeline. +3. Fires the `NOTIFIER_ID_WOV_DETECT` SOF notifier to the `wov_arbiter`. + +The `word_id` field (bits 15:0 of the primary DW) carries the `wov_slot_id` (0, 1, or 2). + +### D0i3 / S0iX Support + +The WOV capture stream supports D0i3 runtime PM autosuspend and wake-up transitions: + +```text +# dmic-wov-multi-manifest.conf +Object.Widget.host-copier."...": + capture_compatible_d0i3 true # host-copier allows D0i3 + +Object.PCM.pcm."$DMIC_PCM_ID": + capture_compatible_d0i3 true # PCM object allows D0i3 +``` + +### IPC4 Module Control via `sof-ctl` + +Override the slot assignment for a `detect_test` instance using the SOF IPC4 +LARGE_CONFIG_SET path (requires `sof-ctl` tool or equivalent hwdep ioctl): + +```bash +# Set detect_test in pipeline 102 to use slot_id = 1 +sof-ctl -c hw:0 -t large_config_set \ + -m -i \ + -p 202 -b 00000000 01 # param_id=202 (SOF_IPC4_BYTES_CONTROL_PARAM_ID), slot_id=1 +``` + +--- + +## Adding a New WOV Algorithm + +The reference implementation (`detect_test.c`) is intentionally simple — it looks for +zero-crossing rate and signal energy in fixed frequency bands. Replace it with any +algorithm by following one of the approaches below. + +### Approach A — Modify `detect_test.c` directly + +This is simplest for prototyping. The DP thread calls `default_detect_test_buf()` on +every 320-frame batch. Replace its body with your algorithm: + +```c +/* src/samples/audio/detect_test.c */ + +static void default_detect_test_buf(struct comp_dev *dev, + const int16_t *samples, uint32_t frames) +{ + struct comp_data *cd = comp_get_drvdata(dev); + + if (cd->detected || cd->paused) + return; + + /* === YOUR ALGORITHM HERE === + * Input: samples — pointer to 'frames' interleaved S16_LE samples + * frames — always KD_DP_FRAMES (320) = 20 ms @ 16 kHz + * Output: call detect_test_notify(dev) when keyword is confirmed. + * =========================== + */ + bool keyword_found = my_algorithm_process(cd->algo_state, samples, frames); + + if (keyword_found) { + comp_err(dev, "KWD detected on slot %u", cd->wov_slot_id); + if (!cd->drain_req) + cd->drain_req = cd->config.drain_req ? cd->config.drain_req : 5000; + detect_test_notify(dev); + cd->detected = 1; + } +} +``` + +Store per-slot algorithm state in `struct comp_data` (add fields to the struct). +The slot index is available as `cd->wov_slot_id` (0, 1, or 2) so each KPB pipeline's +detector can hold independent model state. + +### Approach B — New Native SOF Module + +For a production algorithm create a new SOF module following the standard +`src/audio/template/` skeleton and integrate it with the arbiter via SOF notifier: + +**Step 1: Create the module files** + +``` +src/audio/my_kwd/ +├── CMakeLists.txt +├── my_kwd.c +└── my_kwd.h +``` + +**Step 2: Implement the module driver** + +```c +/* src/audio/my_kwd/my_kwd.c */ +#include +#include +#include +#include + +struct my_kwd_data { + uint8_t wov_slot_id; + bool paused; + bool detected; + /* ... algorithm state ... */ +}; + +/* Called by arbiter when a sibling slot fires (NOTIFIER_ID_WOV_CTRL) */ +static void on_wov_ctrl(void *arg, enum notify_id id, void *data) +{ + struct comp_dev *dev = arg; + struct my_kwd_data *cd = comp_get_drvdata(dev); + const struct wov_ctrl_notif *ctrl = data; + + if (ctrl->cmd == WOV_ARB_CMD_PAUSE) + cd->paused = true; + else if (ctrl->cmd == WOV_ARB_CMD_RESUME) { + cd->paused = false; + cd->detected = 0; + } +} + +/* Notify arbiter + KPB + host that this slot fired */ +static void my_kwd_notify(struct comp_dev *dev) +{ + struct my_kwd_data *cd = comp_get_drvdata(dev); + + /* 1. IPC4 notification to host */ + struct ipc4_voice_cmd_notification notif = {}; + notif.primary.r.word_id = cd->wov_slot_id; + notif.primary.r.notif_type = SOF_IPC4_NOTIFY_PHRASE_DETECTED; + notif.primary.r.type = SOF_IPC4_GLB_NOTIFICATION; + /* ... fill in module_id / instance_id ... */ + ipc_msg_send(cd->msg, ¬if, true); + + /* 2. Tell KPB to start draining */ + /* (re-use existing kpb_client notifier path) */ + + /* 3. Tell arbiter slot fired */ + struct wov_detect_notif det = { .slot_id = cd->wov_slot_id }; + notifier_event(dev, NOTIFIER_ID_WOV_DETECT, NOTIFIER_TARGET_CORE_ALL_MASK, + &det, sizeof(det)); +} + +static int my_kwd_prepare(struct comp_dev *dev) +{ + struct my_kwd_data *cd = comp_get_drvdata(dev); + + /* Derive slot from pipeline ID */ + uint32_t ppl = dev->ipc_config.pipeline_id; + cd->wov_slot_id = (ppl == 101 || ppl == 1) ? 0 : + (ppl == 102 || ppl == 3) ? 1 : + (ppl == 103 || ppl == 4) ? 2 : WOV_SLOT_INVALID; + + if (cd->wov_slot_id != WOV_SLOT_INVALID) + notifier_register(dev, NULL, NOTIFIER_ID_WOV_CTRL, on_wov_ctrl); + + return comp_set_state(dev, COMP_TRIGGER_PREPARE); +} + +static int my_kwd_copy(struct comp_dev *dev) +{ + struct my_kwd_data *cd = comp_get_drvdata(dev); + struct comp_buffer *source = comp_dev_get_first_data_producer(dev); + + if (!audio_stream_get_avail(&source->stream)) + return PPL_STATUS_PATH_STOP; + + uint32_t frames = audio_stream_get_avail_frames(&source->stream); + uint32_t avail_b = audio_stream_get_avail_bytes(&source->stream); + buffer_stream_invalidate(source, avail_b); + + /* Pass-through to arbiter input */ + struct comp_buffer *sink = comp_dev_get_first_data_consumer(dev); + if (sink && audio_stream_get_free_bytes(&sink->stream) >= avail_b) { + audio_stream_copy(&source->stream, 0, &sink->stream, 0, + frames * audio_stream_get_channels(&source->stream)); + buffer_stream_writeback(sink, avail_b); + comp_update_buffer_produce(sink, avail_b); + } + + if (!cd->paused && !cd->detected) { + /* Run your algorithm on the frames */ + if (my_algorithm_run(cd, &source->stream, frames)) { + my_kwd_notify(dev); + cd->detected = 1; + } + } + + comp_update_buffer_consume(source, avail_b); + return 0; +} +``` + +**Step 3: Register the UUID** + +Add to `uuid-registry.txt`: + +``` +MY_KWD_UUID_HEX my_kwd +``` + +Add to `src/audio/my_kwd/CMakeLists.txt`: + +```cmake +add_local_sources(sof my_kwd.c) +``` + +Add to `src/audio/CMakeLists.txt`: + +```cmake +if(CONFIG_COMP_MY_KWD) + add_subdirectory(my_kwd) +endif() +``` + +Add `src/audio/Kconfig`: + +```kconfig +config COMP_MY_KWD + bool "My keyword detector" + depends on COMP_KPB && IPC_MAJOR_4 + # no AMS required (uses SOF notifier) +``` + +**Step 4: Update the topology** + +In `dmic-wov-multi.conf`, replace `KWD_TEST_UUID` with the UUID bytes for `my_kwd` +in the `wov.101.1`, `wov.102.1`, `wov.103.1` widgets. + +### Approach C — IADK / LLEXT loadable module + +For algorithms that must ship as separate binaries (third-party IP, updatable +without reflashing), use the SOF IADK module adapter framework. The algorithm +is compiled as an LLEXT `.so` and loaded at runtime from the kernel filesystem. +See `src/audio/module_adapter/README.md` for the full IADK API. + +The notifier signaling path (steps 2 and 3 of `my_kwd_notify`) remains the same; +only the binary delivery mechanism changes. + +### Algorithm State Isolation + +Each pipeline instance (101/102/103) creates its own `comp_dev` with independent +`comp_data`. Detector state is never shared between slots. The `wov_slot_id` field +identifies which pipeline a given instance belongs to: + +``` +Pipeline 101 → wov_slot_id=0 → kd_dp_stack_0 / kd_dp_threads[0] +Pipeline 102 → wov_slot_id=1 → kd_dp_stack_1 / kd_dp_threads[1] +Pipeline 103 → wov_slot_id=2 → kd_dp_stack_2 / kd_dp_threads[2] (Core 1) +``` + +--- + +## Topology: Build and Deploy + +### Topology Source Layout + +``` +tools/topology/topology2/ +├── platform/intel/ +│ └── dmic-wov-multi.conf ← main topology (edit here) +├── include/components/ +│ ├── wov.conf ← detect_test widget class (wov_mute + wov_test kcontrols) +│ └── wov-arbiter.conf ← wov_arbiter widget class definition +├── include/controls/ +│ └── mixer.conf ← Class.Control.mixer definition (required by wov.conf) +└── dmic-wov-multi-manifest.conf ← top-level manifest (includes above) +``` + +### Compile Topology to `.tplg` + +From the root of the SOF repository: + +```bash +# Run from the repo root (e.g. ~/work/sof-tgl/sof-wov) +TPLG2=$(pwd)/tools/topology/topology2 +ALSA_TMP=/tmp/alsa-tplg-wov + +mkdir -p $ALSA_TMP +cp /usr/share/alsa/alsa.conf $ALSA_TMP/ +ln -sf $TPLG2/include $ALSA_TMP/include +ln -sf $TPLG2/platform $ALSA_TMP/platform + +# 1. Standard 2-Channel Multi-WOV Topology (with SRC 48k -> 16k) +ALSA_CONFIG_DIR=$ALSA_TMP ALSA_TOPOLOGY_PLUGIN_DIR=/usr/lib/alsa-topology alsatplg \ + -I $TPLG2 -p \ + -c tools/topology/topology2/dmic-wov-multi-manifest.conf \ + -o /tmp/sof-tgl-dmic-wov-multi.tplg + +# 2. Native 16 kHz 4-Channel Multi-WOV Topology (No SRC, with embedded NHLT) +ALSA_CONFIG_DIR=$ALSA_TMP ALSA_TOPOLOGY_PLUGIN_DIR=/usr/lib/alsa-topology alsatplg \ + -I $TPLG2 -p \ + -c tools/topology/topology2/dmic-wov-multi-4ch-manifest.conf \ + -o /tmp/sof-tgl-dmic-wov-multi-4ch.tplg +``` + +`ALSA_CONFIG_DIR` must point to a directory that contains `alsa.conf` plus +`include/` and `platform/` symlinks into `topology2/`. `ALSA_TOPOLOGY_PLUGIN_DIR` points to +the directory containing `libalsatplg_module_nhlt.so` so the NHLT preprocessor plugin can +generate and embed the hardware ACPI NHLT table into the manifest binary. + +Copy the compiled topology to the DUT: + +```bash +scp /tmp/sof-tgl-dmic-wov-multi-4ch.tplg \ + root@:/lib/firmware/intel/sof-ipc4-tplg/sof-tgl-dmic-wov-multi-4ch.tplg +``` + +### BIOS NHLT Table Override (`sof_use_tplg_nhlt=1`) + +On development DUTs (such as Spider / Tiger Lake), the BIOS ACPI NHLT table may have +corrupted checksums or lack endpoint descriptors for non-standard DMIC clock rates +(such as opening DMIC natively at 16 kHz across 4 channels without an SRC downsampler). + +The SOF Linux kernel driver supports **overriding the BIOS NHLT table** using the NHLT +table embedded in the topology manifest binary. + +#### 1. How Topology NHLT is Embedded +In the topology manifest (`dmic-wov-multi-4ch-manifest.conf`): +- `Define { PREPROCESS_PLUGINS "nhlt" }` enables the NHLT compiler plugin. +- `Object.Dai.DMIC` defines the DAI parameters (`sample_rate 16000`, `num_pdm_active 2`, 4 active mics). +- `Object.Base.manifest.1 { nhlt "true" }` packages the NHLT table into a `SOF_MANIFEST_DATA_TYPE_NHLT` (1) TLV data block inside the compiled `.tplg` binary. + +#### 2. Enabling NHLT Override in the SOF Driver +Set `sof_use_tplg_nhlt=1` for the `snd_sof_intel_hda_common` kernel module. + +Edit `/etc/modprobe.d/sof.conf` on the DUT: + +```ini +# /etc/modprobe.d/sof.conf +options snd_sof tplg_path=intel/sof-ipc4-tplg tplg_filename=sof-tgl-dmic-wov-multi-4ch.tplg +options snd_sof_intel_hda_common sof_use_tplg_nhlt=1 +``` + +#### 3. Reloading Driver Stack with NHLT Override +Because `snd_sof_intel_hda_common` is referenced by child modules, unload the SOF stack in dependency order, then reload with `sof_use_tplg_nhlt=1`: + +```bash +ssh root@ ' + rmmod snd_sof_probes snd_sof_ipc_msg_injector snd_sof_fw_gdb \ + snd_soc_skl_hda_dsp snd_sof_pci_intel_tgl snd_sof_pci_intel_cnl \ + snd_sof_intel_hda_generic soundwire_intel snd_sof_intel_hda_sdw_bpt \ + snd_sof_intel_hda_common snd_sof_intel_hda_mlink snd_sof_intel_hda \ + snd_sof_pci snd_sof_xtensa_dsp snd_sof + modprobe snd_sof_intel_hda_common sof_use_tplg_nhlt=1 + modprobe snd_sof_pci_intel_tgl +' +``` + +#### 4. Verifying NHLT Override on DUT +```bash +# Verify kernel parameter is active +cat /sys/module/snd_sof_intel_hda_common/parameters/sof_use_tplg_nhlt +# Output: Y + +# Verify 4-channel DMIC audio capture +arecord -D hw:0,11 -c 4 -r 16000 -f S16_LE -d 3 /tmp/wov_4ch.wav +``` + +### Build Firmware with WOV Arbiter + +Configure a build directory with the required Kconfig options (see +[Build System Configuration](#build-system-configuration)), then build: + +```bash +ninja -C +``` + +Copy the firmware image to the DUT (path varies by platform): + +```bash +# TigerLake example +scp /zephyr/zephyr.ri \ + root@:/lib/firmware/intel/sof-ipc4/tgl/community/sof-tgl.ri +``` + +Reload the driver on the DUT: + +```bash +rmmod snd_sof_pci_intel_tgl && modprobe snd_sof_pci_intel_tgl +``` + +### Kernel Requirements & Build + +The Multi-Slot WOV and ALSA regular PCM pipeline requires: + +- **Kernel Repository**: `git@github.com:lgirdwood/linux.git` +- **Kernel Branch**: `feature/wov-multi-kpb-v2` +- **Firmware Repository**: `git@github.com:lgirdwood/sof.git` +- **Firmware Branch**: `feature/wov-multi-kpb-v2` + +#### Checkout and Build Kernel + +```bash +# Clone or fetch the kernel branch +git clone -b feature/wov-multi-kpb-v2 git@github.com:lgirdwood/linux.git linux-wov +cd linux-wov + +# Configure for x86_64 with SOF audio support +make x86_64_defconfig +# Ensure CONFIG_SND_SOC_SOF=m, CONFIG_SND_SOC_SOF_INTEL_TOPLEVEL=y, +# CONFIG_SND_SOC_SOF_HDA=m + +# Build kernel and modules +make -j$(nproc) bzImage modules + +# Install modules and kernel to DUT (e.g. TigerLake DUT) +INSTALL_MOD_PATH=/tmp/modules make modules_install +scp -r /tmp/modules/lib/modules/* root@:/lib/modules/ +scp arch/x86/boot/bzImage root@:/boot/vmlinuz-wov +``` + +### Topology Configuration Reference + +Key parameters in `dmic-wov-multi.conf`: + +| Constant | Default | Description | +|---|---|---| +| `DMIC_PCM_ID` | `11` | ALSA PCM device index | +| `DMIC_DAI_INDEX` | `1` | HDA DAI instance | +| `KWD_CPC` | `100000` | cycles per chunk for detector widgets | +| `WOV_ARB_CPC` | `20000` | cycles per chunk for arbiter | +| `FORMAT` | `s32le` (TGL/CAVS2.5) | audio format; `s16le` on other platforms | + +> **KPB history depth is configurable via topology.** Set `KPB_BUFF_TIME_MS` in the topology +> manifest (e.g. `dmic-wov-multi-manifest.conf`) to override `CONFIG_KPB_MAX_BUFF_TIME` at +> runtime — no firmware rebuild required. Omit the define or set it to `0` to fall back to +> the Kconfig default (6000 ms on TGL/CAVS2.5, 2100 ms on other platforms). + +Slot 2 (`Pipeline 103`) is deliberately placed on Core 1 (`core_id = 1`) to validate +cross-core scheduling. Set all three to `core_id = 0` if a single-core topology is needed. + +### Adding a Fourth Slot + +1. Add `Pipeline 104` (new KPB + detector) following the pattern of pipelines 101–103. + Route the new `wov.104.1 → wov-arbiter.105.1`. +2. Update `wov_arbiter.conf`: set `num_input_pins = 4`. +3. Update `wov_arbiter.h`: `WOV_ARB_MAX_SLOTS 8` already supports it. +4. Add the new `pipeline_id → wov_slot_id` mapping in `test_keyword_new()`. +5. Add a fourth `K_THREAD_STACK_DEFINE` and update `kd_dp_stacks[]`. + +--- + +## Build System Configuration + +### Kconfig (minimum required set) + +```kconfig +# Mandatory +CONFIG_COMP_WOV_ARBITER=y +CONFIG_COMP_KPB=y +CONFIG_COMP_MIXIN_MIXOUT=y +CONFIG_IPC_MAJOR_4=y + +# For the detect_test reference detector +CONFIG_COMP_KWD_DETECT=y + +# Multi-core scheduling (required for slot 2 on Core 1) +CONFIG_SMP=y +CONFIG_MP_MAX_NUM_CPUS=4 # TGL has 4 DSP cores +CONFIG_SCHED_CPU_MASK_PIN_ONLY=y + +# KPB history buffer length — compile-time floor; topology can override at runtime. +# Default: 6000 ms on CAVS2.5+ (TigerLake), 2100 ms on all other platforms. +CONFIG_KPB_MAX_BUFF_TIME=6000 # TGL / CAVS2.5 +``` + +The KPB history depth can be set **per-platform in the topology manifest** without a +firmware rebuild. The buffer size is computed at prepare time from whichever source wins: + +| Source | Priority | How to set | +|---|---|---| +| Topology `KPB_BUFF_TIME_MS` | **highest** | `Define { KPB_BUFF_TIME_MS "6000" }` in manifest | +| `CONFIG_KPB_MAX_BUFF_TIME` | fallback | `west build -- -DCONFIG_KPB_MAX_BUFF_TIME=4000` | + +Buffer byte formula (16 kHz S16LE mono): + +``` +buffer_bytes = 16 x 2 x buff_time_ms x channels + = 16 x 2 x 6000 x 1 = 192 000 bytes (TGL, S16LE mono, 6000 ms) + = 16 x 2 x 2100 x 1 = 67 200 bytes (other platforms, 2100 ms) +``` + +The topology kcontrol `kpb_cfg_` carries a 36-byte SOF ABI blob with +`type = KP_BUF_CFG_BUFF_TIME_MS = 2` and a 4-byte `uint32_t` payload. It is sent +automatically to the firmware LARGE_CONFIG_SET handler when the pipeline is first opened; +no userspace script is required. Supported values in `kpb.conf`: `6000`, `4000`, `2100`. +To add a new value, compute the 4-byte LE payload and add an `IncludeByKey` entry. + +To change the compile-time fallback, rebuild with `-DCONFIG_KPB_MAX_BUFF_TIME=`. + +These can be set via `west build -- -DCONFIG_...=y` or by editing the build directory's `zephyr/.config`. + +### Module UUIDs + +| Component | UUID | +|---|---| +| `detect_test` (KWD_TEST) | `1f:d5:a8:eb:27:78:b5:47:82:ee:de:6e:77:43:af:67` | +| `wov_arbiter` | `4a5b6c7d-8e9f-4a1b-2c3d-4e5f60718293` | + +--- + +## Testing and Verification + +### Quick Start (TigerLake / spider DUT) + +```bash +# 0. Load the driver with the WOV firmware and topology +rmmod snd_sof_pci_intel_tgl +modprobe snd_sof_pci_intel_tgl \ + fw_path=intel/sof-ipc4/tgl/community \ + tplg_filename=intel/sof-ipc4-tplg/sof-tgl-dmic-4ch.tplg + +# 1. Verify the PCM capture device is visible +arecord -l # expect: card 0, device 11: DMIC Multi-WOV +cat /proc/asound/card0/pcm11c/info + +# 2. Run capture test with arecord or wov_capture_app +arecord -D hw:0,11 -f S16_LE -r 16000 -c 2 -d 3 /tmp/wov_test.wav +wov_capture_app -D 0 -d 11 -r 16000 -c 2 -t 3.0 -o /tmp +``` + +--- + +### kcontrol numid reference + +After driver load with the deployed single-KPB topology (`sof-tgl-dmic-4ch.tplg` / `dmic-wov-multi-manifest.conf`), the WOV kcontrol set is: + +| numid | name | type | Purpose | +|---|---|---|---| +| 11 | `kpb_cfg_100` | bytes TLV | Shared KPB 0 buffer config in Pipeline 100 (history depth in ms) | +| 12 | `wov_mute_101` | boolean switch | Arm (`on`) / mute (`off`) detection for slot 0 (Core 0) | +| 13 | `wov_test_101` | boolean switch | Momentary trigger switch for slot 0 (auto-resets to `off`) | +| 14 | `wov_mute_102` | boolean switch | Arm (`on`) / mute (`off`) detection for slot 1 (Core 0) | +| 15 | `wov_test_102` | boolean switch | Momentary trigger switch for slot 1 (auto-resets to `off`) | +| 16 | `wov_mute_103` | boolean switch | Arm (`on`) / mute (`off`) detection for slot 2 (Core 1) | +| 17 | `wov_test_103` | boolean switch | Momentary trigger switch for slot 2 (auto-resets to `off`) | +| 18 | `wov_active_slot` | enumerated | Read-only arbiter active slot state (`Listening`, `Slot 1`, `Slot 2`, `Slot 3`) | + +> **Note:** numids are assigned in ALSA registration order. Run `amixer -c 0 controls` +> to confirm actual numids on your sound card. + +**Runtime usage summary:** + +| kcontrol | When to use | +|---|---| +| `kpb_cfg_100` (11) | Written automatically by the kernel from topology at pipeline open. Sets history depth (e.g. 6000 ms). | +| `wov_mute_1NN` (12/14/16) | Write `on` to arm a slot for detection. Default is `off` (muted). | +| `wov_test_1NN` (13/15/17) | Write `on` to immediately force a keyword trigger for testing. The control auto-resets to `off`. | +| `wov_active_slot` (18) | Query with `amixer` to check currently active slot (`Listening` or `Slot 1`..`Slot 3`). | + +--- + +### Reading Active Slot Status via `wov_active_slot` Enum Control + +The arbiter updates `wov_active_slot` to reflect the active triggered detector slot: + +```bash +# Query current state (returns 'Listening', 'Slot 1', 'Slot 2', or 'Slot 3') +amixer -c 0 cget name='wov_active_slot' +``` + +--- + +### Per-Slot Trigger Test + +The `detect_test` DP thread auto-triggers after accumulating **320 frames** (one 20 ms +batch, `frames_total >= KD_DP_FRAMES`). The first batch fires the trigger approximately +14–25 ms after pipeline RUNNING. No physical audio source is required. + +#### Test all three slots simultaneously + +```bash +dmesg -C +arecord -D hw:0,11 -r 16000 -c 2 -f S16_LE -d 10 /tmp/wov_all.wav & +AREC=$! +# Arm all three slots +amixer -c 0 cset numid=12 on # wov_mute_101 +amixer -c 0 cset numid=14 on # wov_mute_102 +amixer -c 0 cset numid=16 on # wov_mute_103 +wait $AREC +echo "rc=$?" +``` + +Expected: `rc=0`. Slot 0 fires first (timing-dependent); the arbiter pauses slots 1 and 2 +via `NOTIFIER_ID_WOV_CTRL` and sets `wov_active_slot` to `Slot 1`. + +#### Test manual trigger via `wov_test_1NN` kcontrol switch + +```bash +# Start capture without auto-trigger wait +arecord -D hw:0,11 -r 16000 -c 2 -f S16_LE -d 10 /tmp/wov_manual.wav & +AREC=$! +# Arm slots +amixer -c 0 cset numid=12 on +amixer -c 0 cset numid=14 on +amixer -c 0 cset numid=16 on + +# Force trigger Slot 1 on demand: +amixer -c 0 cset numid=15 on # wov_test_102 triggers detection and auto-resets to off + +# Check active slot in arbiter: +amixer -c 0 cget name='wov_active_slot' # Returns 'Item #1 Slot 2' + +wait $AREC +echo "rc=$?" +``` + +#### Test a single slot in isolation + +```bash +arecord -D hw:0,11 -r 16000 -c 2 -f S16_LE -d 8 /tmp/wov_s2.wav & +AREC=$! +# Arm only Slot 2 (Core 1) +amixer -c 0 cset numid=16 on # arm wov_mute_103 +wait $AREC +echo "rc=$?" +``` + +--- + +### Per-Slot Mute Test + +Verify that `wov_mute_1NN` suppresses detection when `off` and restores it when `on`. + +```bash +# Reload driver for a clean state +rmmod snd_sof_pci_intel_tgl && modprobe snd_sof_pci_intel_tgl && sleep 4 + +# Open PCM capture device (keeps DSP in D0) +arecord -D hw:0,11 -f S16_LE -r 16000 -c 2 -d 30 /dev/null & +AREC=$! +sleep 2 + +# Leave all wov_mute controls at default (off = muted) +# Arm slot 1 +amixer -c 0 cset numid=14 on +echo "Slot 1 armed for detection" + +kill $AREC +``` + +#### Multi-Slot Automated Test Suite (`wov_multi_slot_test.py`) + +`tools/wov_capture/wov_multi_slot_test.py` runs an automated multi-cycle test verifying all 3 detector slots, momentary test trigger switches (`wov_test_101`, `wov_test_102`, `wov_test_103`), automatic switch reset to `off`, and `wov_active_slot` enum transitions (`Listening` -> `Slot N` -> `Listening`): + +```bash +# Run 10-cycle automated test suite across all 3 slots +python3 tools/wov_capture/wov_multi_slot_test.py --cycles 10 +``` + +Example output: +``` +================================================================ + WOV 3-Slot Automated Trigger & Arbitration 10-Cycle Suite +================================================================ + +[Cycle 01] Testing Slot 1 (wov_test_101)... + Active Slot during trigger : 1 (Expected: 1) + Test Switch state : off (Expected: off) + Active Slot after stop : 0 (Expected: 0) + Captured WAV File : /tmp/wov_slot_test_cyc1_1.wav (192044 bytes, 3.10s) + [Cycle 01 - Slot 1] => PASSED +... +================================================================ + RESULTS: 10/10 passed (100.0%) +================================================================ +``` + +#### Verify audio content + +Silence precedes the trigger; real DMIC audio follows. +The silence-to-audio boundary marks the trigger point (∼20 ms into the file). + +```python +import struct, math, sys + +for fname in sys.argv[1:]: + data = open(fname, 'rb').read()[44:] # skip 44-byte WAV header + n = len(data) // 2 + samp = struct.unpack_from(f'<{n}h', data) + nz = next((i for i, x in enumerate(samp) if x != 0), n) + rms = math.sqrt(sum(x*x for x in samp[800:]) / max(len(samp) - 800, 1)) + print(f'{fname}: first_nz={nz*1000/16000:.1f}ms post_trigger_RMS={rms:.0f}') + +# Expected on TGL (silent room): +# first_nz=14-25 ms (arbiter activates after first DP batch) +# post_trigger_RMS > 100 (ambient DMIC noise -- not silence) +``` + +--- + +### Reading Firmware Trace (mtrace) + +The mtrace ring is at `/sys/kernel/debug/sof/mtrace/core{0,1}`. Each `dd` call +advances the FIFO read pointer; start reading **before** the arecord session to +capture pipeline-prepare and trigger messages. + +```bash +# Capture ~1 MB of firmware trace concurrently with an arecord session +dd if=/sys/kernel/debug/sof/mtrace/core0 bs=65536 count=16 of=/tmp/mt.bin & +arecord -D hw:0,11 -f S16_LE -r 16000 -c 2 -d 8 /tmp/wov.wav & +amixer -c 0 cset numid=12 on && amixer -c 0 cset numid=14 on +amixer -c 0 cset numid=13 on && amixer -c 0 cset numid=16 on +wait + +# strings works because SOF embeds full format strings in the binary +grep -a 'kd_test\|wov_arb\|AUTO-TRIGGER\|TRIGGERED' /tmp/mt.bin +``` + +--- + +### Expected Trace Events + +After opening `/dev/snd/pcmC0D11c` (`hw:0,11`) (pipeline prepare + RUNNING): + +``` +kd_test.test_keyword_prepare: comp:4 0x2000d kd_dp thread started for slot 0 +kd_test.test_keyword_prepare: comp:3 0x1000d kd_dp thread started for slot 1 +wov_arbiter.wov_arb_trigger: comp:2 0x10 wov_arb_trigger cmd 1 +``` + +On auto-trigger (slot 0 fires first): + +``` +kd_test.default_detect_test_buf: comp:4 0x2000d kd_test dp: AUTO-TRIGGER slot=0 +kd_test.notify_host: comp:4 0x2000d notify_host: WOV module_id=0x2 instance_id=0xd slot_id=0 detected +wov_arbiter.arb_on_detect: comp:2 0x10 wov_arb: activating slot 0 +kd_test.on_wov_ctrl: comp:3 0x1000d kd: paused (slot 0 active) +kd_test.on_wov_ctrl: comp:4 0x2000d kd: resumed by arbiter +``` + +On stream stop (arecord exits): + +``` +wov_arbiter.wov_arb_trigger: comp:2 0x10 wov_arb_trigger cmd 0 +kd_test.on_wov_ctrl: comp:3 0x1000d kd: resumed by arbiter +kd_test.on_wov_ctrl: comp:4 0x2000d kd: resumed by arbiter +``` + + + +--- + +### Real-Audio Frequency Sweep Test + +Inject tones at known frequencies to trigger specific slots. Run `arecord` or `wov_capture_app` on the +DUT and `speaker-test` on a test machine whose audio output is wired to the DUT mic input: + +```bash +# On the DUT: start capture and arm all slots +arecord -D hw:0,11 -f S16_LE -r 16000 -c 2 -d 8 /tmp/wov_sweep.wav & +amixer -c 0 cset numid=12 on && amixer -c 0 cset numid=14 on +amixer -c 0 cset numid=13 on && amixer -c 0 cset numid=16 on + +# On test machine: drive tone sweep (one frequency band per slot) +speaker-test -c 1 -t sine -f 120 -l 3 # -> slot 0 (Male 80-170 Hz) +speaker-test -c 1 -t sine -f 220 -l 3 # -> slot 1 (Female 175-270 Hz) +wait +``` + +--- + +### Multi-Cycle PCM Verification Daemon (`wov_daemon.py`) + +`tools/wov_capture/wov_daemon.py` runs an automated multi-cycle regular PCM capture loop on the +DUT (`hw:0,11` at 16 kHz 2-channel S16_LE) with integrated audio signal verification. + +```bash +# Basic usage — 3 cycles of 2.0s capture with audio signal analysis +python3 wov_daemon.py + +# Multi-cycle test with DSP runtime PM D3 autosuspend verification between cycles +python3 wov_daemon.py --cycles 5 --duration 3.0 --test-pm + +# Options +python3 wov_daemon.py --help +``` + +``` +usage: wov_daemon.py [-h] [--cycles CYCLES] [--duration DURATION] + [--delay DELAY] [--card CARD] [--device DEVICE] + [--rate RATE] [--channels CHANNELS] [--format FORMAT] + [--out OUT] [--test-pm] [--verify] + + --cycles N Number of capture cycles to run (0=unlimited, default: 3) + --duration S Duration per cycle in seconds (default: 2.0) + --delay S Delay between cycles in seconds (default: 0.5) + --card N Sound card number (default: 0) + --device N PCM device number (default: 11) + --rate N Sample rate in Hz (default: 16000) + --channels N Number of channels (default: 2) + --format FMT ALSA format (default: S16_LE) + --out PATH Output WAV file or pattern (default: /tmp/wov_daemon_cycle_{n}.wav) + --test-pm Sleep 3.0s between cycles to verify DSP D3 autosuspend / wake + --verify Perform deep audio signal energy analysis (default: True) +``` + +--- + +### C Host Application (`wov_capture_app`) + +`tools/wov_capture/wov_capture_app.c` is a self-contained, zero-dependency C host application +that captures regular PCM audio via direct Linux ALSA kernel UAPI ioctls (`/dev/snd/pcmC0D11c`). +It writes valid RIFF WAV files with exact byte headers and calculates per-channel DC offset, +AC RMS, Peak amplitude, and Peak dBFS metrics. + +#### Build + +```bash +cd tools/wov_capture + +# Builds wov_capture_app locally with standard GCC (no external libraries needed) +make + +# Install to DUT (scp) +make install DUT=root@spider +``` + +#### Usage + +``` +Usage: wov_capture_app [options] + +Options: + -D CARD Sound card number (default: 0) + -d DEV PCM device number (default: 11) + -r RATE Sample rate in Hz (default: 16000) + -c CHANS Number of channels (default: 2) + -f FORMAT Sample format: S16_LE (default) or S32_LE + -t DURATION Capture duration in seconds (default: 3.0, 0 = unlimited) + -n CYCLES Number of capture cycles (default: 1, 0 = unlimited) + -w DELAY Delay between cycles in seconds (default: 0.5) + -o DIR Output directory for WAV files (default: /tmp) + -F FILE Explicit output WAV file path + -v Verbose output (print extra debug info) + -h Show help +``` + +**Quick start on spider:** + +```bash +# Capture 3 seconds of 16 kHz stereo audio to /tmp +wov_capture_app -D 0 -d 11 -r 16000 -c 2 -t 3.0 -o /tmp + +# Multi-cycle repeat test (5 consecutive cycles with 1s delay) +wov_capture_app -D 0 -d 11 -n 5 -t 2.0 -w 1.0 +``` + +#### Log Format + +All output is prefixed with a timestamp tag: + +``` +[YYYY-MM-DD HH:MM:SS.mmm] [INFO ] Starting WOV PCM Capture App (Card=0, Dev=11, Rate=16000, Ch=2, Format=S16_LE) +[YYYY-MM-DD HH:MM:SS.mmm] [STATE] Cycle 1: Opening capture device /dev/snd/pcmC0D11c (rate=16000, ch=2) +[YYYY-MM-DD HH:MM:SS.mmm] [STATE] Cycle 1: Capturing audio -> /tmp/wov_20260905_120000_cyc001.wav +[YYYY-MM-DD HH:MM:SS.mmm] [STATE] Cycle 1: Captured 48000 frames (3.00s, 192000 bytes) -> /tmp/wov_20260905_120000_cyc001.wav +[YYYY-MM-DD HH:MM:SS.mmm] [INFO ] Channel 0: Min=-1245 Max=1432 DC=-12.4 RMS=432.1 (-37.6 dBFS) Peak=1432.0 (-27.2 dBFS) +[YYYY-MM-DD HH:MM:SS.mmm] [INFO ] Channel 1: Min=-1180 Max=1390 DC=-10.1 RMS=418.6 (-37.9 dBFS) Peak=1390.0 (-27.4 dBFS) +``` + diff --git a/src/audio/wov_arbiter/wov_arbiter.c b/src/audio/wov_arbiter/wov_arbiter.c new file mode 100644 index 000000000000..35cb315ed9b5 --- /dev/null +++ b/src/audio/wov_arbiter/wov_arbiter.c @@ -0,0 +1,813 @@ +// SPDX-License-Identifier: BSD-3-Clause +// +// Copyright(c) 2026 Intel Corporation +// +// WOV Arbiter -- routes the drain output of one-of-N KPB host sinks to the +// single host PCM copier, while silencing the idle inputs and coordinating +// pause/resume of sibling WOV detectors via the SOF notifier system. +// +// Topology connectivity (per KPB slot i): +// KPB_i host_sink (output pin 1) --> wov_arbiter input pin i +// wov_arbiter output pin 0 --> host copier +// +// Notifier events: +// Subscribes to NOTIFIER_ID_WOV_DETECT (detector -> arbiter on keyword) +// Publishes NOTIFIER_ID_WOV_CTRL (arbiter -> detectors: pause/resume) + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +LOG_MODULE_REGISTER(wov_arbiter, CONFIG_SOF_LOG_LEVEL); + +SOF_DEFINE_REG_UUID(wov_arbiter); +DECLARE_TR_CTX(wov_arbiter_tr, SOF_UUID(wov_arbiter_uuid), LOG_LEVEL_INFO); + +/* Private runtime data. */ +struct wov_arb_data { + struct ipc4_base_module_cfg base_cfg; + /* + * Index of the currently active KPB slot (0..num_slots-1). + * WOV_ARB_NO_ACTIVE when no drain is in progress. + * Protected by the scheduler; no extra lock needed. + */ + uint8_t active_slot; + atomic_t call_active; + /* Number of input pins (= KPB slots); read from nb_input_pins at init. */ + uint8_t num_slots; + uint16_t active_slot_ctl_id; + uint16_t call_state_ctl_id; + uint32_t copy_count; + uint32_t drain_frames_copied; + uint32_t drain_frames_total; +#if CONFIG_IPC_MAJOR_4 + /* Notification messages, allocated on first use and reused */ + struct ipc_msg *ctl_msg; + struct ipc_msg *detect_msg; +#endif +}; + +/* + * Only one WOV graph (DMIC or headset) may be active at a time: detectors + * share NOTIFIER_ID_WOV_DETECT and DSP memory only fits one detector set. + * IPC handling is serialized, so no lock is needed. + */ +static unsigned int wov_arb_instances; + +#if CONFIG_IPC_MAJOR_4 +static void notify_control_change(const struct comp_dev *dev, struct wov_arb_data *cd, + uint16_t control_id, uint32_t val) +{ + struct sof_ipc4_notify_module_data *msg_module_data; + struct sof_ipc4_control_msg_payload *msg_payload; + struct ipc_msg *msg; + uint32_t data_size = sizeof(struct sof_ipc4_notify_module_data) + + sizeof(struct sof_ipc4_control_msg_payload) + + sizeof(struct sof_ipc4_ctrl_value_chan); + struct ipc4_voice_cmd_notification notif; + + if (!cd->ctl_msg) { + memset_s(¬if, sizeof(notif), 0, sizeof(notif)); + notif.primary.r.notif_type = SOF_IPC4_MODULE_NOTIFICATION; + notif.primary.r.type = SOF_IPC4_GLB_NOTIFICATION; + notif.primary.r.rsp = SOF_IPC4_MESSAGE_DIR_MSG_REQUEST; + notif.primary.r.msg_tgt = SOF_IPC4_MESSAGE_TARGET_FW_GEN_MSG; + + cd->ctl_msg = ipc_msg_w_ext_init(NULL, notif.primary.dat, 0, data_size); + if (!cd->ctl_msg) + return; + } + msg = cd->ctl_msg; + + msg_module_data = (struct sof_ipc4_notify_module_data *)msg->tx_data; + msg_module_data->instance_id = IPC4_INST_ID(dev->ipc_config.id); + msg_module_data->module_id = IPC4_MOD_ID(dev->ipc_config.id); + msg_module_data->event_id = SOF_IPC4_NOTIFY_MODULE_EVENTID_ALSA_MAGIC_VAL | + SOF_IPC4_ENUM_CONTROL_PARAM_ID; + msg_module_data->event_data_size = sizeof(struct sof_ipc4_control_msg_payload) + + sizeof(struct sof_ipc4_ctrl_value_chan); + + msg_payload = (struct sof_ipc4_control_msg_payload *)msg_module_data->event_data; + msg_payload->id = control_id; + msg_payload->num_elems = 1; + msg_payload->chanv[0].channel = 0; + msg_payload->chanv[0].value = val; + + ipc_msg_send(msg, NULL, true); +} + +/* Wake the host: a blocking read() on the WOV capture PCM has no other way + * to learn that a detection just pushed a burst of drained KPB data into the + * host DMA buffer (the stream runs with SNDRV_PCM_INFO_NO_PERIOD_WAKEUP so + * ALSA's normal period-elapsed IRQ path is not relied on here). This mirrors + * detect_test.c's notify_host() so the kernel's sof_ipc4_rx_msg() can key off + * SOF_IPC4_NOTIFY_PHRASE_DETECTED and call snd_sof_pcm_period_elapsed(). + * Sent once per detection (from arb_on_detect()), not repeated per copy(): + * it is a one-shot simulated interrupt, not a substitute for the host's own + * period-elapsed mechanism on streams that never requested no-period-wakeup. + */ +static void notify_host_detect(const struct comp_dev *dev, struct wov_arb_data *cd, + uint32_t slot_id) +{ + struct ipc4_voice_cmd_notification notif; + + memset_s(¬if, sizeof(notif), 0, sizeof(notif)); + notif.primary.r.word_id = slot_id; + notif.primary.r.notif_type = SOF_IPC4_NOTIFY_PHRASE_DETECTED; + notif.primary.r.type = SOF_IPC4_GLB_NOTIFICATION; + notif.primary.r.rsp = SOF_IPC4_MESSAGE_DIR_MSG_REQUEST; + notif.primary.r.msg_tgt = SOF_IPC4_MESSAGE_TARGET_FW_GEN_MSG; + + notif.extension.r.sv_score = (uint16_t)(dev_comp_id(dev) & 0xffff); + notif.extension.r.rsvd1 = (uint32_t)(dev_comp_id(dev) >> 16); + + if (!cd->detect_msg) { + cd->detect_msg = ipc_msg_w_ext_init(NULL, notif.primary.dat, + notif.extension.dat, 0); + if (!cd->detect_msg) + return; + } + /* The header carries the slot, update it for each detection */ + cd->detect_msg->header = notif.primary.dat; + + ipc_msg_send(cd->detect_msg, NULL, true); +} +#endif + +/* ------------------------------------------------------------------------- + * Notifier callbacks + * ---------------------------------------------------------------------- */ + +/* Notifier callback: a WOV detector has fired. Activates the winning slot + * and broadcasts PAUSE to all detectors via NOTIFIER_ID_WOV_CTRL. */ +static void arb_on_detect(void *arg, enum notify_id id, void *data) +{ + struct comp_dev *dev = arg; + struct wov_arb_data *cd = comp_get_drvdata(dev); + const struct wov_detect_notif *det = data; + + if (det->slot_id >= cd->num_slots) { + comp_err(dev, "wov_arb: bad slot_id %u num_slots=%u", + det->slot_id, cd->num_slots); + return; + } + + if (atomic_read(&cd->call_active)) { + comp_dbg(dev, "wov_arb: ignoring slot %u detection while call is active", + det->slot_id); + return; + } + + /* First-wins: ignore if another slot is already draining. */ + if (cd->active_slot != WOV_ARB_NO_ACTIVE) { + comp_warn(dev, "wov_arb: slot %u detected but slot %u active, ignoring", + det->slot_id, cd->active_slot); + return; + } + + comp_info(dev, "wov_arb: activating slot %u", det->slot_id); + cd->active_slot = det->slot_id; + +#if CONFIG_IPC_MAJOR_4 + /* Notify host ALSA enum control: 1..N corresponds to Slot 1..N (0 is Listening) */ + notify_control_change(dev, cd, cd->active_slot_ctl_id, (uint32_t)cd->active_slot + 1); + /* Wake a blocking read() on the host WOV capture PCM - see notify_host_detect(). */ + notify_host_detect(dev, cd, det->slot_id); +#endif + + /* Broadcast PAUSE to all detectors. The winning slot continues draining + * its KPB history buffer; all others suspend detection until RESUME. */ + struct wov_ctrl_notif ctrl = { .cmd = WOV_ARB_CMD_PAUSE, .slot_id = det->slot_id }; + notifier_event(dev, NOTIFIER_ID_WOV_CTRL, NOTIFIER_TARGET_CORE_ALL_MASK, + &ctrl, sizeof(ctrl)); +} + +/* ------------------------------------------------------------------------- + * Component lifecycle + * ---------------------------------------------------------------------- */ + +static struct comp_dev *wov_arb_new(const struct comp_driver *drv, + const struct comp_ipc_config *config, + const void *spec) +{ + struct comp_dev *dev; + struct wov_arb_data *cd; + + comp_cl_info(drv, "wov_arb_new"); + + if (wov_arb_instances) { + comp_cl_err(drv, "wov_arb_new: another WOV PCM is already active"); + return NULL; + } + + dev = comp_alloc(drv, sizeof(*dev)); + if (!dev) + return NULL; + dev->ipc_config = *config; + + cd = rzalloc(SOF_MEM_FLAG_USER, sizeof(*cd)); + if (!cd) { + comp_free_device(dev); + return NULL; + } + + const struct ipc4_base_module_cfg *base_cfg = spec; + memcpy_s(&cd->base_cfg, sizeof(cd->base_cfg), base_cfg, sizeof(*base_cfg)); + + /* Detection notifications arrive via notifier bus across pipelines, so support up to MAX_SLOTS */ + cd->num_slots = WOV_ARB_MAX_SLOTS; + cd->active_slot_ctl_id = WOV_ARB_ACTIVE_SLOT_CONTROL_ID; + + /* Start with no active slot; first WOV_DETECT notifier will activate one. */ + cd->active_slot = WOV_ARB_NO_ACTIVE; + + comp_set_drvdata(dev, cd); + /* Arbiter produces a capture stream that feeds the host PCM copier. */ + dev->direction = SOF_IPC_STREAM_CAPTURE; + dev->direction_set = true; + dev->state = COMP_STATE_READY; + +#if CONFIG_IPC_MAJOR_4 + struct ipc_comp_dev *ipc_pipe; + struct ipc *ipc = ipc_get(); + + ipc_pipe = ipc_get_comp_by_ppl_id(ipc, COMP_TYPE_PIPELINE, config->pipeline_id, + IPC_COMP_IGNORE_REMOTE); + if (ipc_pipe && ipc_pipe->pipeline) { + dev->pipeline = ipc_pipe->pipeline; + if (dev->ipc_config.proc_domain == COMP_PROCESSING_DOMAIN_LL || !dev->period) + dev->period = ipc_pipe->pipeline->period; + } + + if (!dev->period) + dev->period = 10000; + + component_set_nearest_period_frames(dev, cd->base_cfg.audio_fmt.sampling_frequency); + if (!dev->frames) + dev->frames = 160; +#endif + + comp_info(dev, "wov_arb_new: num_slots=%u, ppl=%u, period=%u, frames=%u", + cd->num_slots, config->pipeline_id, dev->period, dev->frames); + + wov_arb_instances++; + + return dev; +} + +static void wov_arb_free(struct comp_dev *dev) +{ + comp_info(dev, "wov_arb_free"); + + struct wov_arb_data *cd = comp_get_drvdata(dev); + + if (cd && cd->active_slot != WOV_ARB_NO_ACTIVE) { + cd->active_slot = WOV_ARB_NO_ACTIVE; + struct wov_ctrl_notif c = { .cmd = WOV_ARB_CMD_RESUME }; + notifier_event(dev, NOTIFIER_ID_WOV_CTRL, + NOTIFIER_TARGET_CORE_ALL_MASK, + &c, sizeof(c)); + } + + notifier_unregister(dev, NULL, NOTIFIER_ID_WOV_DETECT); + +#if CONFIG_IPC_MAJOR_4 + if (cd) { + ipc_msg_free(cd->ctl_msg); + ipc_msg_free(cd->detect_msg); + } +#endif + rfree(cd); + comp_free_device(dev); + + if (wov_arb_instances) + wov_arb_instances--; +} + +static int wov_arb_params(struct comp_dev *dev, + struct sof_ipc_stream_params *params); + +static int wov_arb_prepare(struct comp_dev *dev) +{ + struct wov_arb_data *cd = comp_get_drvdata(dev); + + comp_info(dev, "wov_arb_prepare: period=%u, frames=%u", dev->period, dev->frames); + + cd->active_slot = WOV_ARB_NO_ACTIVE; + cd->copy_count = 0; + cd->drain_frames_copied = 0; + cd->drain_frames_total = 0; + +#if CONFIG_IPC_MAJOR_4 + notify_control_change(dev, cd, cd->active_slot_ctl_id, 0); + if (cd->call_state_ctl_id) + notify_control_change(dev, cd, cd->call_state_ctl_id, + atomic_read(&cd->call_active) ? + WOV_ARB_CALL_STATE_ACTIVE : WOV_ARB_CALL_STATE_LISTENING); +#endif + + if (!dev->frames) { + component_set_nearest_period_frames(dev, cd->base_cfg.audio_fmt.sampling_frequency); + if (!dev->frames) + dev->frames = 160; + } + + struct comp_buffer *sink = comp_dev_get_first_data_consumer(dev); + if (sink) { +#if CONFIG_IPC_MAJOR_4 + ipc4_update_buffer_format(sink, &cd->base_cfg.audio_fmt); +#else + struct sof_ipc_stream_params p; + wov_arb_params(dev, &p); + buffer_set_params(sink, &p, true); +#endif + } + + struct comp_buffer *source; + struct list_item *src_item; + list_for_item(src_item, &dev->bsource_list) { + source = list_item(src_item, struct comp_buffer, sink_list); + if ((buf_get_id(source) >> 16) == 0) { + /* Pin 0 is audio from KPB: 1ch mono S32_LE */ +#if CONFIG_IPC_MAJOR_4 + ipc4_update_buffer_format(source, &cd->base_cfg.audio_fmt); +#else + struct sof_ipc_stream_params p; + wov_arb_params(dev, &p); + buffer_set_params(source, &p, true); +#endif + } + } + + /* Subscribe to keyword-detected events from any WOV detector. */ + notifier_unregister(dev, NULL, NOTIFIER_ID_WOV_DETECT); + notifier_register(dev, NULL, NOTIFIER_ID_WOV_DETECT, arb_on_detect); + + /* Preserve the call gate if the host re-prepares the pipeline. */ + struct wov_ctrl_notif ctrl = { + .cmd = atomic_read(&cd->call_active) ? WOV_ARB_CMD_PAUSE : WOV_ARB_CMD_RESUME, + .slot_id = WOV_ARB_NO_ACTIVE, + }; + notifier_event(dev, NOTIFIER_ID_WOV_CTRL, NOTIFIER_TARGET_CORE_ALL_MASK, + &ctrl, sizeof(ctrl)); + + return comp_set_state(dev, COMP_TRIGGER_PREPARE); +} + +static int wov_arb_reset(struct comp_dev *dev) +{ + struct wov_arb_data *cd = comp_get_drvdata(dev); + + comp_info(dev, "wov_arb_reset"); + + if (cd && cd->active_slot != WOV_ARB_NO_ACTIVE) { + cd->active_slot = WOV_ARB_NO_ACTIVE; + if (!atomic_read(&cd->call_active)) { + struct wov_ctrl_notif c = { .cmd = WOV_ARB_CMD_RESUME }; + + notifier_event(dev, NOTIFIER_ID_WOV_CTRL, + NOTIFIER_TARGET_CORE_ALL_MASK, + &c, sizeof(c)); + } + } + + cd->drain_frames_copied = 0; + cd->drain_frames_total = 0; + + notifier_unregister(dev, NULL, NOTIFIER_ID_WOV_DETECT); + + return comp_set_state(dev, COMP_TRIGGER_RESET); +} + +static int wov_arb_trigger(struct comp_dev *dev, int cmd) +{ + struct wov_arb_data *cd = comp_get_drvdata(dev); + int ret; + + comp_info(dev, "wov_arb_trigger cmd %d", cmd); + + ret = comp_set_state(dev, cmd); + if (ret) + return ret; + + /* + * Stream stopped or paused: deactivate the active slot and resume + * all detectors so they return to listening mode. + */ + if (cmd == COMP_TRIGGER_STOP || cmd == COMP_TRIGGER_PAUSE) { + cd->drain_frames_copied = 0; + cd->drain_frames_total = 0; + if (cd->active_slot != WOV_ARB_NO_ACTIVE) { + comp_info(dev, "wov_arb: stream stopped, resuming all slots"); + cd->active_slot = WOV_ARB_NO_ACTIVE; +#if CONFIG_IPC_MAJOR_4 + notify_control_change(dev, cd, cd->active_slot_ctl_id, 0); +#endif + struct wov_ctrl_notif c = { .cmd = WOV_ARB_CMD_RESUME }; + notifier_event(dev, NOTIFIER_ID_WOV_CTRL, + NOTIFIER_TARGET_CORE_ALL_MASK, + &c, sizeof(c)); + } + } + + return 0; +} + +static int wov_arb_params(struct comp_dev *dev, + struct sof_ipc_stream_params *params) +{ + struct wov_arb_data *cd = comp_get_drvdata(dev); + +#if CONFIG_IPC_MAJOR_4 + ipc4_base_module_cfg_to_stream_params(&cd->base_cfg, params); +#else + /* Translate IPC4 base_cfg audio_fmt to IPC3-style stream params. */ + memset(params, 0, sizeof(*params)); + params->channels = cd->base_cfg.audio_fmt.channels_count; + params->rate = cd->base_cfg.audio_fmt.sampling_frequency; + params->sample_container_bytes = cd->base_cfg.audio_fmt.depth / 8; + params->sample_valid_bytes = + cd->base_cfg.audio_fmt.valid_bit_depth / 8; + params->buffer_fmt = cd->base_cfg.audio_fmt.interleaving_style; +#endif + component_set_nearest_period_frames(dev, params->rate); + + return 0; +} + +/* ------------------------------------------------------------------------- + * IPC4 large-config: allow host to force-select a slot (debug/test use). + * ---------------------------------------------------------------------- */ + +static int wov_arb_set_large_config(struct comp_dev *dev, + uint32_t param_id, + bool first_block, + bool last_block, + uint32_t data_offset, + const char *data) +{ + struct wov_arb_data *cd = comp_get_drvdata(dev); + + switch (param_id) { + case SOF_IPC4_ENUM_CONTROL_PARAM_ID: { + const struct sof_ipc4_control_msg_payload *cp = + (const struct sof_ipc4_control_msg_payload *)data; + + if (cp->id == WOV_ARB_CALL_STATE_CONTROL_ID) { + cd->call_state_ctl_id = cp->id; + if (cp->num_elems > 0) { + uint32_t val = cp->chanv[0].value; + + if (val != WOV_ARB_CALL_STATE_LISTENING && + val != WOV_ARB_CALL_STATE_ACTIVE) + return -EINVAL; + + bool call_active = val == WOV_ARB_CALL_STATE_ACTIVE; + + atomic_set(&cd->call_active, call_active); + cd->active_slot = WOV_ARB_NO_ACTIVE; + struct wov_ctrl_notif c = { + .cmd = call_active ? WOV_ARB_CMD_PAUSE : WOV_ARB_CMD_RESUME, + .slot_id = WOV_ARB_NO_ACTIVE, + }; + notifier_event(dev, NOTIFIER_ID_WOV_CTRL, + NOTIFIER_TARGET_CORE_ALL_MASK, + &c, sizeof(c)); + notify_control_change(dev, cd, cp->id, val); + comp_info(dev, "wov_arb: call state %s; detector control complete", + call_active ? "active" : "listening"); + } + return 0; + } + + if (cp->id != WOV_ARB_ACTIVE_SLOT_CONTROL_ID) + return -EINVAL; + + cd->active_slot_ctl_id = cp->id; + if (cp->num_elems > 0) { + uint32_t val = cp->chanv[0].value; + + if (atomic_read(&cd->call_active)) + return -EBUSY; + + if (val > cd->num_slots) + return -EINVAL; + + if (val == 0) { + comp_info(dev, "wov_arb: reset active_slot to listening (0)"); + cd->active_slot = WOV_ARB_NO_ACTIVE; + struct wov_ctrl_notif c = { .cmd = WOV_ARB_CMD_RESUME }; + notifier_event(dev, NOTIFIER_ID_WOV_CTRL, + NOTIFIER_TARGET_CORE_ALL_MASK, + &c, sizeof(c)); + } else { + uint8_t selected_slot = (uint8_t)(val - 1); + + comp_info(dev, "wov_arb: filter listening to slot=%u via kcontrol", + selected_slot); + /* Keep listening mode while pausing all but the selected slot. */ + cd->active_slot = WOV_ARB_NO_ACTIVE; + struct wov_ctrl_notif r = { .cmd = WOV_ARB_CMD_RESUME }; + notifier_event(dev, NOTIFIER_ID_WOV_CTRL, + NOTIFIER_TARGET_CORE_ALL_MASK, + &r, sizeof(r)); + struct wov_ctrl_notif p = { + .cmd = WOV_ARB_CMD_PAUSE, + .slot_id = selected_slot, + }; + notifier_event(dev, NOTIFIER_ID_WOV_CTRL, + NOTIFIER_TARGET_CORE_ALL_MASK, + &p, sizeof(p)); + } + } + return 0; + } + case SOF_IPC4_BYTES_CONTROL_PARAM_ID: + case IPC4_WOV_ARB_GET_ACTIVE_SLOT: + return 0; + case IPC4_WOV_ARB_SET_ACTIVE_SLOT: + cd->active_slot = *(const uint8_t *)data; + comp_info(dev, "wov_arb: force active_slot=%u", cd->active_slot); + return 0; + default: + return -EINVAL; + } +} + +static int wov_arb_get_attribute(struct comp_dev *dev, + uint32_t type, void *value) +{ + struct wov_arb_data *cd = comp_get_drvdata(dev); + + if (type == COMP_ATTR_BASE_CONFIG) { + *(struct ipc4_base_module_cfg *)value = cd->base_cfg; + return 0; + } + return -EINVAL; +} + +/* ------------------------------------------------------------------------- + * copy() -- main audio processing + * + * For the active input pin: forward frames to the output. + * For all other input pins: consume and discard to prevent buffer stalls. + * + * Input buffers are ordered by connection order in bsource_list. + * Slot 0 = first connected source, etc. + * ---------------------------------------------------------------------- */ +static int wov_arb_copy(struct comp_dev *dev) +{ + struct wov_arb_data *cd = comp_get_drvdata(dev); + struct comp_buffer *sink; + struct comp_buffer *source; + struct list_item *src_item; + uint32_t sink_free; + uint32_t active_avail = 0; + + comp_dbg(dev, "wov_arb_copy active=%u", cd->active_slot); + + sink = comp_dev_get_first_data_consumer(dev); + if (!sink) + return 0; + + sink_free = audio_stream_get_free_bytes(&sink->stream); + + uint32_t num_sources = 0; + uint32_t num_kpb_sources = 0; + list_for_item(src_item, &dev->bsource_list) { + source = list_item(src_item, struct comp_buffer, sink_list); + num_sources++; + if (source->source && dev_comp_type(source->source) == SOF_COMP_KPB) + num_kpb_sources++; + } + + /* + * Do NOT force a lone source "active" while listening: the host PCM must + * stay silent/idle (no data, no host-copier IRQs) until a real WOV + * detection (or the fake-wake test path) sets cd->active_slot via + * on_wov_detect(). That is what lets the host block in read() and the + * platform actually reach D0i3/suspend instead of being kept awake by a + * continuous keep-alive stream. + */ + uint32_t eff_active_slot = cd->active_slot; + struct comp_buffer *active_source = NULL; + + /* Find active audio source buffer if a slot is triggered */ + if (eff_active_slot != WOV_ARB_NO_ACTIVE) { + list_for_item(src_item, &dev->bsource_list) { + source = list_item(src_item, struct comp_buffer, sink_list); + if ((source->source && (source->source->drv->type == SOF_COMP_KPB || + dev_comp_type(source->source) == SOF_COMP_KPB)) || + (buf_get_id(source) >> 16) == 0) { + active_source = source; + break; + } + } + + if (active_source) + active_avail = audio_stream_get_avail_bytes(&active_source->stream); + } + + uint32_t copied_dst_bytes = 0; + + /* Second pass: copy active audio slot, silently drain idle/detector slots. */ + list_for_item(src_item, &dev->bsource_list) { + source = list_item(src_item, struct comp_buffer, sink_list); + + if (source == active_source) { + if (active_avail > 0 && sink_free > 0) { + uint32_t src_frame_bytes = audio_stream_frame_bytes(&source->stream); + uint32_t dst_frame_bytes = audio_stream_frame_bytes(&sink->stream); + if (!src_frame_bytes) + src_frame_bytes = cd->base_cfg.audio_fmt.depth ? + (cd->base_cfg.audio_fmt.channels_count * cd->base_cfg.audio_fmt.depth / 8) : 4; + if (!dst_frame_bytes) + dst_frame_bytes = cd->base_cfg.audio_fmt.depth ? + (cd->base_cfg.audio_fmt.channels_count * cd->base_cfg.audio_fmt.depth / 8) : 4; + + uint32_t src_frames = active_avail / src_frame_bytes; + uint32_t dst_frames = sink_free / dst_frame_bytes; + uint32_t frames = MIN(src_frames, dst_frames); + + if (frames > 0) { + uint32_t src_bytes = frames * src_frame_bytes; + uint32_t dst_bytes = frames * dst_frame_bytes; + uint32_t src_ch = audio_stream_get_channels(&source->stream); + uint32_t dst_ch = audio_stream_get_channels(&sink->stream); + uint32_t src_sb = audio_stream_sample_bytes(&source->stream); + uint32_t dst_sb = audio_stream_sample_bytes(&sink->stream); + + buffer_stream_invalidate(source, src_bytes); + + if (src_ch == 1 && dst_ch == 2) { + for (uint32_t i = 0; i < frames; i++) { + int32_t s = (src_sb == sizeof(int32_t)) ? + *(int32_t *)audio_stream_read_frag_s32(&source->stream, i) : + (((int32_t)*(int16_t *)audio_stream_read_frag_s16(&source->stream, i)) << 16); + if (dst_sb == sizeof(int32_t)) { + *(int32_t *)audio_stream_write_frag_s32(&sink->stream, 2 * i) = s; + *(int32_t *)audio_stream_write_frag_s32(&sink->stream, 2 * i + 1) = s; + } else { + int16_t s16 = (int16_t)(s >> 16); + *(int16_t *)audio_stream_write_frag_s16(&sink->stream, 2 * i) = s16; + *(int16_t *)audio_stream_write_frag_s16(&sink->stream, 2 * i + 1) = s16; + } + } + } else if (src_sb != dst_sb) { + if (src_sb == sizeof(int32_t) && dst_sb == sizeof(int16_t)) { + for (uint32_t i = 0; i < frames * src_ch; i++) { + int32_t s = *(int32_t *)audio_stream_read_frag_s32(&source->stream, i); + *(int16_t *)audio_stream_write_frag_s16(&sink->stream, i) = (int16_t)(s >> 16); + } + } else if (src_sb == sizeof(int16_t) && dst_sb == sizeof(int32_t)) { + for (uint32_t i = 0; i < frames * src_ch; i++) { + int16_t s = *(int16_t *)audio_stream_read_frag_s16(&source->stream, i); + *(int32_t *)audio_stream_write_frag_s32(&sink->stream, i) = ((int32_t)s) << 16; + } + } else { + audio_stream_copy(&source->stream, 0, + &sink->stream, 0, + frames * src_ch); + } + } else { + audio_stream_copy(&source->stream, 0, + &sink->stream, 0, + frames * src_ch); + } + + comp_update_buffer_consume(source, src_bytes); + buffer_stream_writeback(sink, dst_bytes); + comp_update_buffer_produce(sink, dst_bytes); + copied_dst_bytes = dst_bytes; + + cd->drain_frames_total += frames; + } + } + } else { + uint32_t avail = audio_stream_get_avail_bytes(&source->stream); + + if (avail > 0) + comp_update_buffer_consume(source, avail); + } + } + + cd->copy_count++; + if ((cd->copy_count % 100) == 1) { + comp_dbg(dev, "wov_arb_copy #%u: active=%u, num_src=%u, act_avail=%u, copied=%u, sink_free=%u", + cd->copy_count, cd->active_slot, num_sources, active_avail, copied_dst_bytes, sink_free); + } + + return 0; +} + +/* ------------------------------------------------------------------------- + * IPC4 large-config (get): expose active slot to userspace as a volatile + * RO enum kcontrol; the host reads this via GET_MODULE_LARGE_CONFIG. + * ---------------------------------------------------------------------- */ + +static int wov_arb_get_large_config(struct comp_dev *dev, + uint32_t param_id, + bool first_block, + bool last_block, + uint32_t *data_offset, + char *data) +{ + struct wov_arb_data *cd = comp_get_drvdata(dev); + + switch (param_id) { + case SOF_IPC4_ENUM_CONTROL_PARAM_ID: { + struct sof_ipc4_control_msg_payload *cp = + (struct sof_ipc4_control_msg_payload *)data; + uint16_t ctl_id = cp->id; + uint32_t resp_size = sizeof(struct sof_ipc4_control_msg_payload) + + sizeof(struct sof_ipc4_ctrl_value_chan); + + if (resp_size > *data_offset) { + comp_err(dev, "wrong enum control response size %u vs %u", + resp_size, *data_offset); + return -EINVAL; + } + + cd->active_slot_ctl_id = ctl_id; + *data_offset = resp_size; + memset_s(cp, resp_size, 0, resp_size); + cp->id = ctl_id; + cp->num_elems = 1; + cp->chanv[0].channel = 0; + /* 0 for Listening, 1..N for triggered slots */ + if (cd->active_slot == WOV_ARB_NO_ACTIVE) + cp->chanv[0].value = 0; + else + cp->chanv[0].value = (uint32_t)cd->active_slot + 1; + return 0; + } + case IPC4_WOV_ARB_GET_ACTIVE_SLOT: + *(uint32_t *)data = (uint32_t)cd->active_slot; + *data_offset = sizeof(uint32_t); + return 0; + default: + return -EINVAL; + } +} + +/* ------------------------------------------------------------------------- + * Component driver registration + * ---------------------------------------------------------------------- */ + +static const struct comp_driver wov_arbiter_drv = { + .type = SOF_COMP_KEYWORD_DETECT, + .uid = SOF_RT_UUID(wov_arbiter_uuid), +#if !CONFIG_ZEPHYR_LOG + .tctx = &wov_arbiter_tr, +#endif + .ops = { + .create = wov_arb_new, + .free = wov_arb_free, + .params = wov_arb_params, + .trigger = wov_arb_trigger, + .copy = wov_arb_copy, + .prepare = wov_arb_prepare, + .reset = wov_arb_reset, + .set_large_config = wov_arb_set_large_config, + .get_large_config = wov_arb_get_large_config, + .get_attribute = wov_arb_get_attribute, + }, +}; + +static struct comp_driver_info wov_arbiter_info = { + .drv = &wov_arbiter_drv, +}; + +UT_STATIC void sys_comp_wov_arbiter_init(void) +{ + comp_register(&wov_arbiter_info); +} + +DECLARE_MODULE(sys_comp_wov_arbiter_init); +SOF_MODULE_INIT(wov_arbiter, sys_comp_wov_arbiter_init); diff --git a/src/audio/wov_arbiter/wov_arbiter.toml b/src/audio/wov_arbiter/wov_arbiter.toml new file mode 100644 index 000000000000..9a7251627ab8 --- /dev/null +++ b/src/audio/wov_arbiter/wov_arbiter.toml @@ -0,0 +1,19 @@ + [[module.entry]] + name = "WOVARB" + uuid = UUIDREG_STR_WOV_ARBITER + affinity_mask = "0x1" + instance_count = "3" + domain_types = "0" + load_type = "0" + module_type = "0xB" + auto_start = "0" + sched_caps = [1, 0x00008000] + + REM # pin = [dir, type, sample rate, size, container, channel-cfg] + pin = [0, 0, 0xfeef, 0xf, 0xf, 0x45ff, + 1, 0, 0xfeef, 0xf, 0xa, 0x45ff] + + REM # mod_cfg [PAR_0 PAR_1 PAR_2 PAR_3 IS_BYTES CPS IBS OBS MOD_FLAGS CPC OBLS] + mod_cfg = [0, 0, 0, 0, 14400, 1114000, 32, 32, 0, 0, 0] + + index = __COUNTER__ diff --git a/src/include/sof/audio/component.h b/src/include/sof/audio/component.h index e879888053b0..729fe470dde9 100644 --- a/src/include/sof/audio/component.h +++ b/src/include/sof/audio/component.h @@ -886,6 +886,7 @@ void sys_comp_dai_init(void); void sys_comp_host_init(void); void sys_comp_kpb_init(void); void sys_comp_selector_init(void); +void sys_comp_wov_arbiter_init(void); /* Start of modules in alphabetical order */ void sys_comp_module_aria_interface_init(void); diff --git a/tools/rimage/config/nvl.toml.h b/tools/rimage/config/nvl.toml.h index e1f4ebfb6336..fd530d561258 100644 --- a/tools/rimage/config/nvl.toml.h +++ b/tools/rimage/config/nvl.toml.h @@ -189,5 +189,9 @@ index = __COUNTER__ #include