Skip to content

kernel/user partition, Phase 5 part 1: KPB draining requests without the notifier - #11497

Draft
lgirdwood wants to merge 6 commits into
thesofproject:mainfrom
lgirdwood:kernel-user/phase5a
Draft

lgirdwood wants to merge 6 commits into
thesofproject:mainfrom
lgirdwood:kernel-user/phase5a

Conversation

@lgirdwood

@lgirdwood lgirdwood commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Phase 5 of #11306 (kernel / user-space partition), first part: KPB client events no longer go through the notifier. Key phrase detectors request the draining of the KPB history buffer with a syscall that user space can call. This changes behaviour, see below.

Background

A detector tells the KPB to drain its history buffer to the host. There were three transports:

  • The notifier: NOTIFIER_ID_KPB_CLIENT_EVT, on by default. The detect test without AMS, the hotword detector and the KPB service bridge used it. The notifier is not usable from user space, and Phase 5 removes it.
  • AMS: used by the detect test on TGL, MTL and LNL. Unchanged.
  • The client queue (CONFIG_KPB_CLI_Q, off by default): a k_msgq and a thread that kpb_new() creates. It has three limits:
    • it supports only one KPB instance;
    • creating a kernel thread in kpb_new() does not work when components are created in a user thread, as with user-space LL;
    • it costs a 4 KiB stack.

What changes

  • Draining requests: a request is a single atomic word: the client ID, the draining length and a sequence number.
    • Posting: the kpb_request_draining() syscall posts a request by bumping the sequence number. It replaces kpb_notifier_schedule(), and its kernel half is in the new src/kernel/audio/kpb-kernel.c.
    • Taking: each KPB instance takes the request at the start of its next copy, in its own LL thread.
    • Which requests: an instance records the sequence number when it is prepared, so it only takes requests posted since, as with the notifier, which a KPB registered for in prepare.
    • Reach: every KPB instance gets every request, on any core, as with the notifier's broadcast.
  • Producers: the detect test (without AMS), the hotword detector and the KPB service bridge use kpb_request_draining().
  • Removed:
    • the KPB notifier transport, with the KPB_NOTIFIER and KPB_CLI_Q options;
    • NOTIFIER_ID_KPB_CLIENT_EVT;
    • the KPB event types that were the notifier payload;
    • the client queue and its thread.
  • AMS: the KPB now registers for AMS messages whether or not the request word is used. Before, the client queue and AMS were exclusive.

Behaviour changes

  • Timing: draining starts in the KPB's next copy, so up to one LL period (1 ms) after the request. With the notifier on the same core, kpb_init_draining() ran in the detector's own call.
  • Draining setup context: kpb_init_draining() runs inside kpb_copy(), so it no longer races with the copy. The client queue needed a scheduler lock for that.
  • Client registration: the KPB service bridge no longer sends client registration and unregistration events. The draining never depended on them: kpb_init_draining() only uses the client ID and draining length of the request.
  • Feedback: kpb_request_draining() returns -EINVAL for an invalid client ID or draining length, and the inline stub returns -ENODEV in builds without a KPB. Like the notifier, it does not report whether a KPB took the request. The client queue's -ENODEV (no instance) and -ENOMSG (queue full) cases go away.
  • Memory: no thread or stack.

Patches

  1. kpb: take draining requests from a request word in the copy. This replaces the client queue, renames the syscall, adds the kernel half, lets the KPB register for AMS with the request word, and switches the KPB service bridge over.
  2. samples: detect_test: use kpb_request_draining().
  3. google: hotword: use kpb_request_draining().
    • The component does not build on main: it uses an older audio stream API and a UUID that is not in the registry. So this change is compile-checked against a stand-in for the library header. It adds no errors to the five the file already has.
  4. kpb: remove the notifier transport.
  5. userspace: doc: update the syscall table.
  6. test: ztest: unit tests of the kernel half: the posted fields, the sequence number including its wrap, the limits, and the rejection of invalid requests.

Testing

  • Unit tests: the new sof.unit.kpb_request ZTest passes, run as in CI (native_sim, ASan and LSan).
  • Per commit, compared with main:
    • Builds: tgl, tgl-h, mtl, lnl, ptl, wcl, nvl, imx8, imx8x, imx8m, imx8m_cm7, imx8ulp, imx95 and qemu_xtensa, and the extra CI configurations:

      • native_sim IPC3/IPC4 stub builds;
      • imx93 64-bit;
      • PTL with each userspace overlay, including user-space LL, which builds the KPB;
      • PTL with CONFIG_SOF_USERSPACE_PROXY=n;
      • PTL and MTL with os_linux_overlay.conf;llext_relocatable.conf;
      • PTL and TGL with app/debug_stream_overlay.conf, and PTL with that overlay and user-space LL.
    • Object changes: as expected, and nothing else:

      • kpb.c (patches 1 and 4);
      • detect_test.c in the builds without AMS (patch 2);
      • notifier.c (patch 4).

      In the images, the DAI functions that use the notifier change only in their notifier ID constants: removing NOTIFIER_ID_KPB_CLIENT_EVT renumbers the IDs after it, which are internal to the firmware.

    • Signing: rimage runs for every Intel platform.

    • Cadence xt-clang (RI-2022.10): MTL, PTL and NVL compile.

    • ZTest: the unit tests pass, run as in CI, apart from sof.unit.audio.buffer, which does not build on main either. It was added after kernel/user partition, Phase 4 part 6: move kernel-only headers to sof/kernel #11487 and lacks the src/kernel/include directory; test: ztest: audio: buffer: add the kernel include directory #11498 fixes it. With test: ztest: audio: buffer: add the kernel include directory #11498 applied, all unit tests pass.

    • Host: the host library and the cmocka unit tests build and pass.

  • At the tip:
    • the testbench and the tools pass;
    • the host library and the cmocka unit tests pass for all nine defconfigs and the library config;
    • the include checker passes with --strict, for the builds and for the sources;
    • the platforms that already fail on main (acp_6_0, acp_7_0, acp_7_x, mt8186, mt8188, mt8195, mt8196, mt8365) have unchanged error sets.

All of the above was run on 9a990f5 (current main).

Changes since the last push

Not tested on hardware yet

The draining path has not run on hardware yet. Main has no production topology with the WOV capture (INCLUDE_WOV is off in every target), so testing needs a custom topology, such as cavs-nocodec with its DMIC WOV capture, and a board whose firmware has no AMS (PTL, WCL or NVL, or TGL built with CONFIG_AMS=n), so that the request word is the path used.

🤖 Generated with Claude Code

lrgirdwo and others added 6 commits November 20, 2026 14:01
CONFIG_KPB_CLI_Q delivers draining requests through a message queue
and a thread that kpb_new() creates for them. That has three limits:
- only one KPB instance is supported,
- kpb_new() creates a kernel thread, which does not work when
  components are created in a user thread, as with user-space LL,
- each KPB instance costs a 4 KiB thread stack.

Replace the queue and the thread with a single atomic request word:
the client ID, the draining length and a sequence number. The
kernel half of the syscall, now named kpb_request_draining() and
moved to src/kernel/audio/kpb-kernel.c, posts the request by bumping
the sequence number. Each KPB instance takes it at the start of its
next copy, in its own LL thread, so the draining starts within one
LL period, and the scheduler lock around kpb_init_draining() is no
longer needed. An instance records the sequence number when it is
prepared, so it only takes requests posted since, as with the
notifier. Requests reach every KPB instance, on any core.

The request word is always built with the KPB, so the option goes,
and the KPB now registers for AMS messages also when the request word
is used. The KPB service bridge requests draining with the new
syscall; the client registration events it sent are not needed, the
draining does not depend on them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Without AMS, the detect test tells the KPB to drain its history
buffer with a notifier event. Use kpb_request_draining() instead:
it can be called from user space, and reaches every KPB instance
without the notifier. The AMS path is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
As for the detect test, request the draining of the KPB history
buffer with kpb_request_draining() instead of a notifier event.

The component does not build on main, it uses an older audio stream
API, so this change is only compile-checked: it adds no errors to the
ones the file already has.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
The detect test, the hotword detector and the KPB service bridge now
request draining with kpb_request_draining(), so nothing sends KPB
client events through the notifier anymore. Remove the KPB notifier
registration and its event handler, the client registration that
only that handler used, the KPB_NOTIFIER option, the
NOTIFIER_ID_KPB_CLIENT_EVT notifier ID, and the KPB event types that
were the notifier payload.

The KPB takes draining requests from kpb_request_draining() and, with
AMS, from AMS key phrase detected messages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Update the syscall table: the KPB draining request syscall is now
kpb_request_draining(), with its kernel half in
src/kernel/audio/kpb-kernel.c.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Test the kernel half of kpb_request_draining(): the posted request
carries the client ID and the draining length, every request changes
the sequence number, also when it wraps, the largest client ID and
draining length fit, and invalid requests are rejected without being
posted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>

@lgirdwood lgirdwood left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review Summary

Clean, well-structured 6-commit series replacing CONFIG_KPB_NOTIFIER (NOTIFIER_ID_KPB_CLIENT_EVT) and CONFIG_KPB_CLI_Q (4 KiB stack + kernel thread in kpb_new()) with a lock-free atomic request word (kpb_drain_request in src/kernel/audio/kpb-kernel.c) polled in kpb_copy():

  • Multi-core & MMU coherence verified: On Intel CAVS (xtensa-cavs-linker.ld) and ACE (ace-link-mirrored.ld + xtensa_mmu.h), both APP_SYSUSER_BSS (app_smem.ld under SEGSTART_UNCACHED, XTENSA_MMU_PERM_W | XTENSA_MMU_MAP_USER without XTENSA_MMU_CACHED_WB) and .bss (>ucram) sit in uncached/coherent SRAM, so atomic_cas() / atomic_get() operate coherently across DSP cores.
  • Userspace boundary verified: z_impl_kpb_request_draining() only reads KPB_DRAIN_REQ_SEQ(old) (& 0xff) from APP_SYSUSER_BSS, EXPORT_SYMBOL(z_impl_kpb_request_draining) preserves LLEXT calls when CONFIG_USERSPACE=n, and omitting SOF_SYSCALL_CALLER_CHECK() in zephyr/syscall/kpb.c matches src/include/sof/userspace/README.md (Any user thread, including DP module threads).

No blocking issues found — 1 design/behavior note on concurrent multi-detector requests within one LL period and 2 minor cleanup/SPDX nits inline.

Comment on lines +274 to 282
* \brief Request draining of the KPB history buffers.
*
* Callable from user space. The request is handled asynchronously by the
* KPB client queue thread.
* Callable from user space. Every KPB instance that has been prepared takes
* the request in its next copy, so the draining starts within one LL period.
*
* \param[in] id Client ID, i.e. the KPB output pin.
* \param[in] drain_req Requested draining length in milliseconds.
* \return 0 on success, -EINVAL on invalid arguments, -ENODEV if no KPB
* instance exists, -ENOMSG if the queue is full.
* \return 0 on success, -EINVAL on invalid arguments.
*/

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Design / multi-detector note: Because kpb_drain_request is a single global word shared across all client IDs (0 .. KPB_MAX_NO_OF_CLIENTS - 1) and all KPB instances (unlike kpb_cli_msgq's KPB_MAX_NO_OF_CLIENTS FIFO slots or synchronous notifier_event()), if two detectors call kpb_request_draining() within the same 1 ms LL tick before kpb_copy() runs (e.g., lock-step DP keyword detectors at 10–20 ms period), the second call increments seq again and overwrites the first.

For a single KPB with one host_sink, "latest wins" within 1 ms is fine — worth noting in this doc comment that a newer request posted before kpb_copy() runs supersedes an untaken one (or making kpb_drain_request per-client atomic_t kpb_drain_request[KPB_MAX_NO_OF_CLIENTS] if independent per-pin/multi-KPB requests shouldn't clobber each other).

Comment thread src/audio/kpb.c
Comment on lines 91 to +92
uint32_t kpb_no_of_clients; /**< number of registered clients */
uint8_t drain_seq; /**< sequence number of the last draining request taken */

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up / dead state: After Commit 4 removes kpb_register_client() and KPB_EVENT_UNREGISTER_CLIENT, several client-registration items have zero remaining readers in the tree:

  • kpb->clients[KPB_MAX_NO_OF_CLIENTS] (line 88, written at 875–876, 1007–1008) and kpb->kpb_no_of_clients (line 91, zeroed at 535, 846), plus #include <rtos/symbol.h> (line 28, previously used for EXPORT_SYMBOL(z_impl_kpb_notifier_schedule)).
  • enum kpb_client_state (src/include/sof/audio/kpb.h:100-105) and state / r_ptr / sink in struct kpb_client (kpb_ams_kpd_notification() only reads cli_data->id and cli_data->drain_req).

Comment on lines 104 to 106
#if CONFIG_AMS
uint32_t kpd_uuid_id;
#else
struct kpb_event_data event_data;
#endif /* CONFIG_AMS */

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: struct kpb_client client_data; (line 91 above) is now only used by ams_notify_kpb(), so it can move inside #if CONFIG_AMS alongside kpd_uuid_id.

@@ -0,0 +1,33 @@
cmake_minimum_required(VERSION 3.20.0)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: Add SPDX license header to match testcase.yaml and sibling ZTest suites:

Suggested change
cmake_minimum_required(VERSION 3.20.0)
# SPDX-License-Identifier: BSD-3-Clause
#
# Copyright(c) 2026 Intel Corporation.
cmake_minimum_required(VERSION 3.20.0)

@@ -0,0 +1,2 @@
CONFIG_ZTEST=y

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: Add SPDX license header:

Suggested change
CONFIG_ZTEST=y
# SPDX-License-Identifier: BSD-3-Clause
CONFIG_ZTEST=y

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants