Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions src/audio/volume/Kconfig
Original file line number Diff line number Diff line change
Expand Up @@ -79,4 +79,33 @@ config COMP_GAIN
This option enables gain to change volume. It works
as peak volume without updating peak vol to host

config COMP_GAIN_FAULT_INJECT
bool "DEBUG: inject a CPU exception in gain process() on one core"
default y
depends on COMP_GAIN
help
Debug-only fault injection. After COMP_GAIN_FAULT_INJECT_PERIODS
calls to the gain module's process() on a gain instance created
on core COMP_GAIN_FAULT_INJECT_CORE, execute an illegal
instruction ("ill" on Xtensa) from the LL thread context to
raise an IllegalInstruction CPU exception. Never enable in
production builds.

config COMP_GAIN_FAULT_INJECT_CORE
int "Core on which gain instances fault"
default 1
depends on COMP_GAIN_FAULT_INJECT
help
Only gain instances whose IPC4 core_id equals this value
inject the fault; gain instances on other cores run normally.

config COMP_GAIN_FAULT_INJECT_PERIODS
int "Number of process() calls before the fault"
default 1000
depends on COMP_GAIN_FAULT_INJECT
help
Number of process() invocations per gain instance before the
exception is raised. With a 1 ms LL period, 1000 is about 1 s
of streaming, so the stream is fully running when it faults.

endif # volume
2 changes: 1 addition & 1 deletion src/audio/volume/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ graph LR

## Configuration and Scripts

- **Kconfig**: Extensive tuning for the standard volume framework (`COMP_VOLUME`), selecting underlying algorithms (e.g., `COMP_VOLUME_WINDOWS_FADE`, `COMP_VOLUME_LINEAR_RAMP`). Manages sub-settings like querying host telemetry (`COMP_PEAK_VOL`, `PEAK_METER_UPDATE_PERIOD_CHOICE`).
- **Kconfig**: Extensive tuning for the standard volume framework (`COMP_VOLUME`), selecting underlying algorithms (e.g., `COMP_VOLUME_WINDOWS_FADE`, `COMP_VOLUME_LINEAR_RAMP`). Manages sub-settings like querying host telemetry (`COMP_PEAK_VOL`, `PEAK_METER_UPDATE_PERIOD_CHOICE`). The debug-only `COMP_GAIN_FAULT_INJECT` option makes the `GAIN` module's `process()` (`gain_process()`, a wrapper around `volume_process()`) execute an illegal instruction after `COMP_GAIN_FAULT_INJECT_PERIODS` calls on gain instances created on core `COMP_GAIN_FAULT_INJECT_CORE`, raising a CPU exception from that core's LL thread.
- **CMakeLists.txt**: Extremely versatile linkage resolving general pathways (`volume_generic.c`), custom optimized builds across HIFI pipelines (`volume_hifi3.c`, `volume_hifi4.c`, `volume_hifi5.c`), and dual-path execution logic (`*_with_peakvol.c`).
- **volume.toml**: Registers independent modules `PEAKVOL` (`UUIDREG_STR_VOLUME4`) and `GAIN` (`UUIDREG_STR_GAIN`), outlining explicit memory mapping parameters via platform-dependent constraints.
- **Topology (.conf)**: Derived from `tools/topology/topology2/include/components/volume.conf`, configuring a standard `pga` widget (UUID `7e:67:7e:b7:f4:5f:88:41:af:14:fb:a8:bd:bf:86:82`). Outlines parameters for ramp steps interpolation methods and binds specific ALSA interface elements.
48 changes: 48 additions & 0 deletions src/audio/volume/volume.c
Original file line number Diff line number Diff line change
Expand Up @@ -897,10 +897,58 @@ static const struct module_interface volume_interface = {
};

#if CONFIG_COMP_GAIN
#if CONFIG_COMP_GAIN_FAULT_INJECT
/**
* \brief DEBUG: gain process() with CPU exception fault injection.
*
* Wraps volume_process(). On gain instances created on core
* CONFIG_COMP_GAIN_FAULT_INJECT_CORE, after
* CONFIG_COMP_GAIN_FAULT_INJECT_PERIODS calls it executes an illegal
* instruction ("ill" on Xtensa), raising an IllegalInstruction CPU
* exception from the LL thread of that core.
* The core is taken from the IPC4 module init request (dev->ipc_config.core)
* rather than read from the CPU, so it is safe in user-space LL threads.
*
* \param[in,out] mod Gain processing module handle
* \param[in] sources Source buffers
* \param[in] num_of_sources Number of sources
* \param[in,out] sinks Sink buffers
* \param[in] num_of_sinks Number of sinks
* \return Error code from volume_process(); does not return when faulting.
*/
static int gain_process(struct processing_module *mod,
struct sof_source **sources, int num_of_sources,
struct sof_sink **sinks, int num_of_sinks)
{
struct vol_data *cd = module_get_private_data(mod);

if (mod->dev->ipc_config.core == CONFIG_COMP_GAIN_FAULT_INJECT_CORE &&
++cd->fault_inject_cnt >= CONFIG_COMP_GAIN_FAULT_INJECT_PERIODS) {
comp_err(mod->dev, "FAULT INJECT: gain 0x%x pipe %u core %u, raising exception",
mod->dev->ipc_config.id, mod->dev->ipc_config.pipeline_id,
mod->dev->ipc_config.core);
#if defined(__XTENSA__)
/* IllegalInstruction exception (EXCCAUSE 0). __builtin_trap() is not
* used: on Xtensa GCC emits "break 1, 15" (a debug exception) first.
*/
__asm__ volatile("ill");
#else
__builtin_trap();
#endif
}

return volume_process(mod, sources, num_of_sources, sinks, num_of_sinks);
}
#endif /* CONFIG_COMP_GAIN_FAULT_INJECT */

static const struct module_interface gain_interface = {
.init = volume_init,
.prepare = volume_prepare,
#if CONFIG_COMP_GAIN_FAULT_INJECT
.process = gain_process,
#else
.process = volume_process,
#endif
.set_configuration = volume_set_config,
.get_configuration = volume_get_config,
.reset = volume_reset,
Expand Down
3 changes: 3 additions & 0 deletions src/audio/volume/volume.h
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,9 @@ struct vol_data {
uint32_t attenuation; /**< peakmeter adjustment in range [0 - 31] */
bool is_passthrough; /**< is passthrough or do gain multiplication */
uint32_t ramp_channel_counter; /**< channels need new ramp volume */
#if CONFIG_COMP_GAIN_FAULT_INJECT
uint32_t fault_inject_cnt; /**< DEBUG: process() calls so far */
#endif
};

/** \brief Volume processing functions map. */
Expand Down
4 changes: 4 additions & 0 deletions src/include/sof/schedule/zephyr_ll.h
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,10 @@ int zephyr_ll_task_cancel(void *data, struct task *task);
extern struct k_mutex *zephyr_ll_locks[CONFIG_CORE_COUNT];

struct k_thread *zephyr_ll_init_context(void *data, struct task *task);

/* fatal error handling, see zephyr_ll.c and zephyr_ll-kernel.c */
void zephyr_ll_lock_shadow_reset(int core);
int zephyr_ll_release_locks_of_current(void);
#endif

struct zephyr_domain_thread {
Expand Down
49 changes: 49 additions & 0 deletions src/kernel/schedule/zephyr_ll-kernel.c
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,55 @@ void user_ll_grant_access(struct k_thread *thread, int core)

k_thread_access_grant(thread, zephyr_ll_klocks[core]);
}

/**
* @brief Release all LL scheduler locks held by the faulting thread.
*
* Zephyr does not release mutexes when a thread is aborted. If a user-space
* LL thread faults while running a module, it still holds its core's LL
* scheduler lock (zephyr_ll_run() keeps it locked while running tasks), and
* every later user_ll_lock_sched() on that core, e.g. from the IPC user
* thread triggering a pipeline, pends forever.
*
* Must only be called from k_sys_fatal_error_handler(), before
* z_fatal_error() aborts _current. The current thread is the mutex owner
* there, so the regular unlock path is used to hand the lock over to the
* first waiter. Rescheduling is deferred until the exception returns.
*
* Uses the kernel-only zephyr_ll_klocks[] copy: zephyr_ll_locks[] is
* user-writable and must not be trusted here.
*
* @note The scheduler state protected by the lock is not repaired: tasks
* run in the interrupted tick stay on the dead thread's temporary list
* and no further LL ticks happen on that core.
*
* @return Number of LL scheduler locks released.
*/
int zephyr_ll_release_locks_of_current(void)
{
struct k_thread *thread = k_current_get();
int released = 0;
int core;

for (core = 0; core < CONFIG_CORE_COUNT; core++) {
struct k_mutex *m = zephyr_ll_klocks[core];

if (!m || m->owner != thread)
continue;

/* before unlocking: the new owner counts depth from 0 */
zephyr_ll_lock_shadow_reset(core);

/* the mutex is recursive, drop every level */
while (m->owner == thread)
if (z_impl_k_mutex_unlock(m))
break;

released++;
}

return released;
}
#endif /* CONFIG_SOF_USERSPACE_LL */

#if CONFIG_SOF_BOOT_TEST_STANDALONE || CONFIG_LIBRARY
Expand Down
12 changes: 12 additions & 0 deletions src/schedule/zephyr_ll.c
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,18 @@ static inline void zephyr_ll_lock_releasing(int core)
zephyr_ll_lock_owner[core] = NULL;
}

/*
* Forget the recorded owner of the core's LL lock. Only for
* zephyr_ll_release_locks_of_current(), when the owner is dying and its lock
* is about to be force-released on its behalf. Must be called before the
* unlock: the new owner's zephyr_ll_lock_acquired() counts depth from 0.
*/
void zephyr_ll_lock_shadow_reset(int core)
{
zephyr_ll_lock_owner[core] = NULL;
zephyr_ll_lock_depth[core] = 0;
}

#ifdef CONFIG_ASSERT
void user_ll_assert_locked(int core)
{
Expand Down
54 changes: 54 additions & 0 deletions zephyr/wrapper.c
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@
#include <sof/kernel/drivers/interrupt-map.h>
#include <sof/lib/dma.h>
#include <sof/schedule/schedule.h>
#if CONFIG_SOF_USERSPACE_LL
#include <sof/schedule/zephyr_ll.h>
#endif
#include <sof/lib/io.h>
#include <sof/lib/memory.h>
#include <sof/kernel/platform.h>
Expand All @@ -30,6 +33,10 @@

/* Zephyr includes */
#include <zephyr/arch/cpu.h>
#if defined(CONFIG_XTENSA) && defined(CONFIG_USERSPACE)
/* Zephyr arch-internal header, from zephyr/arch/xtensa/include */
#include <xtensa_internal.h>
#endif
#include <zephyr/device.h>
#include <zephyr/fatal.h>
#include <zephyr/kernel_structs.h>
Expand Down Expand Up @@ -352,6 +359,28 @@ static bool sof_boot_test_fault_expected(void)
}
#endif

#if defined(CONFIG_XTENSA) && defined(CONFIG_USERSPACE)
/**
* @brief Release kernel resources the faulting user thread still holds.
*
* Called from k_sys_fatal_error_handler() before returning to
* z_fatal_error(), which then aborts only the faulting user thread.
* Zephyr does not release mutexes of aborted threads, so locks the thread
* holds, e.g. the per-core LL scheduler lock, must be released here or
* their waiters pend forever.
*
* @return Number of locks released.
*/
static int sof_user_fault_release_locks(void)
{
#if CONFIG_SOF_USERSPACE_LL
return zephyr_ll_release_locks_of_current();
#else
return 0;
#endif
}
#endif

void k_sys_fatal_error_handler(unsigned int reason,
const struct arch_esf *esf)
{
Expand All @@ -363,7 +392,32 @@ void k_sys_fatal_error_handler(unsigned int reason,
return;
}
#endif
#if defined(CONFIG_XTENSA) && defined(CONFIG_USERSPACE)
/*
* A kernel oops raised from a syscall verifier (K_OOPS) or
* k_oops() arrives with a syscall stack frame, not an exception
* frame, so xtensa_exception_is_user() cannot validate it and
* would wrongly halt the system. If the faulting thread is a
* user thread, the oops is the user thread's fault: just abort
* that thread (z_fatal_error() does so once we return).
*/
if (reason == K_ERR_KERNEL_OOPS && _current &&
k_thread_is_user_thread(_current)) {
int n = sof_user_fault_release_locks();

LOG_ERR("ERROR: kernel oops from user thread %p; released %d locks; "
"aborting thread.", _current, n);
return;
}

if (reason != K_ERR_KERNEL_PANIC && xtensa_exception_is_user(esf)) {
int n = sof_user_fault_release_locks();

LOG_ERR("ERROR: Unexpected fatal error %u in Xtensa user mode; "
"released %d locks; aborting thread.", reason, n);
return;
}
#endif
/* flush and switch to immediate mode */
LOG_PANIC();

Expand Down