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
2 changes: 2 additions & 0 deletions include/sound/sof/ipc4/header.h
Original file line number Diff line number Diff line change
Expand Up @@ -651,6 +651,8 @@ struct sof_ipc4_notify_resource_data {
#define SOF_IPC4_DEBUG_SLOT_GDB_STUB 0x42444700
#define SOF_IPC4_DEBUG_SLOT_TELEMETRY 0x4c455400
#define SOF_IPC4_DEBUG_SLOT_BROKEN 0x44414544
#define SOF_IPC4_DEBUG_SLOT_SHELL 0x73686c6c /* 'shll' Zephyr winstream shell */
#define SOF_IPC4_DEBUG_SLOT_LLEXT_LOAD 0x4C454C44 /* 'LELD' shell llext_load rendezvous */

/**
* struct sof_ipc4_notify_module_data - payload for module notification
Expand Down
258 changes: 258 additions & 0 deletions include/uapi/sound/sof/cdev.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,258 @@
/* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) */
/*
* This file is provided under a dual BSD/GPLv2 license. When using or
* redistributing this file, you may do so under either license.
*
* Copyright(c) 2026 Intel Corporation. All rights reserved.
*
* Sound Open Firmware (SOF) Character Device UAPI (/dev/sof-dspN)
*/

#ifndef __INCLUDE_UAPI_SOUND_SOF_CDEV_H
#define __INCLUDE_UAPI_SOUND_SOF_CDEV_H

#include <linux/types.h>
#include <linux/ioctl.h>

#define SOF_CDEV_IOC_MAGIC 'S'
#define SOF_CDEV_ABI_VERSION 0x00010000

/*
* SRAM Memory Window Selectors
* Used in struct sof_cdev_win_io.win_id and mmap() page offset (win_id << 20)
*/
#define SOF_CDEV_WIN_FW_REGS 0 /* Window 0: FW Regs (0x0..0xfff) + Inbox (+0x1000) */
#define SOF_CDEV_WIN_OUTBOX 1 /* Window 1: Host Downlink Outbox */
#define SOF_CDEV_WIN_DEBUG 2 /* Window 2: Debug Window (16 x 4 KB pages) */
#define SOF_CDEV_WIN_PERF 3 /* Window 3: Performance Measurements Window (ADSP_PMW) */
#define SOF_CDEV_WIN_BY_SLOT_TYPE 0xFF /* Select Window 2 slot by slot_type + slot_index */

#define SOF_CDEV_MAX_WINDOWS 4
#define SOF_CDEV_MAX_DEBUG_SLOTS 16

/* Standard IPC4 Window 2 Debug Slot Types */
#define SOF_CDEV_SLOT_UNUSED 0x00000000U
#define SOF_CDEV_SLOT_CRITICAL_LOG 0x54524300U
#define SOF_CDEV_SLOT_DEBUG_LOG 0x474f4c00U
#define SOF_CDEV_SLOT_GDB_STUB 0x42444700U
#define SOF_CDEV_SLOT_TELEMETRY 0x4c455400U
#define SOF_CDEV_SLOT_BROKEN 0x44414544U
#define SOF_CDEV_SLOT_SHELL 0x73686c6cU /* 'shll' Zephyr winstream shell */
#define SOF_CDEV_SLOT_LLEXT_LOAD 0x4c454c44U /* 'LELD' Shell LLEXT load shm */

/**
* struct sof_cdev_slot_desc - Window 2 debug slot descriptor
* @slot_index: Slot index (0..14 for full 4 KB pages, 15 for partial page 0)
* @res_id: Resource / owner ID reported by firmware
* @type: Slot type magic (e.g. SOF_CDEV_SLOT_TELEMETRY)
* @vma: DSP virtual memory address of the slot
* @win_offset: Byte offset of the slot payload relative to Window 2 start
* @bar_offset: Byte offset of the slot payload relative to DSP BAR
* @size: Usable byte capacity of the slot (4096 for 0..14, 3072 for 15)
* @reserved: Reserved for alignment
*/
struct sof_cdev_slot_desc {
__u32 slot_index;
__u32 res_id;
__u32 type;
__u32 vma;
__u32 win_offset;
__u32 bar_offset;
__u32 size;
__u32 reserved;
};

/**
* struct sof_cdev_win_desc - SRAM Window descriptor
* @win_id: Window index (0..3)
* @bar_offset: Byte offset relative to DSP BAR (sdev->mailbox_bar)
* @size: Window byte size
* @flags: Access flags (bit 0 = valid/mapped)
*/
struct sof_cdev_win_desc {
__u32 win_id;
__u32 bar_offset;
__u32 size;
__u32 flags;
};

/**
* struct sof_cdev_info - Device, firmware, and window capability summary
*/
struct sof_cdev_info {
__u32 abi_version;
__u32 ipc_type; /* 0 = IPC3, 1 = IPC4 */
__u32 fw_state; /* enum sof_fw_state */
__u32 dsp_power_state; /* enum sof_dsp_power_states (0=U0, 1=D0, 2=D1, 3=D2, 4=D3) */
__u32 pm_runtime_active; /* 1 if PCI/ACPI device is currently in D0 */
__u32 num_cores; /* Total DSP cores on platform */
__u32 enabled_cores_mask; /* Bitmask of currently enabled DSP cores */
__u32 max_payload_size; /* Max IPC mailbox payload size in bytes */
__u16 fw_ver_major;
__u16 fw_ver_minor;
__u16 fw_ver_micro;
__u16 fw_ver_build;
__u32 hw_ip_version; /* enum sof_intel_hw_ip_version */
char platform[32]; /* Platform / driver identifier */
char fw_filename[64]; /* Loaded firmware file path */
struct sof_cdev_win_desc windows[SOF_CDEV_MAX_WINDOWS];
struct sof_cdev_slot_desc debug_slots[SOF_CDEV_MAX_DEBUG_SLOTS];
};

/*
* Power Management Control Commands (SOF_IOC_PM_CTL)
*/
#define SOF_PM_OP_QUERY 0 /* Query current power & core state without waking */
#define SOF_PM_OP_WAKE_HOLD 1 /* Resume DSP to D0 and hold PM reference on this fd */
#define SOF_PM_OP_RELEASE_HOLD 2 /* Release PM reference held on this fd */
#define SOF_PM_OP_BOOT_DSP 3 /* Ensure DSP firmware is booted (sof_client_boot_dsp) */
#define SOF_PM_OP_CORE_GET 4 /* Power up specific DSP core (core_id) */
#define SOF_PM_OP_CORE_PUT 5 /* Power down specific DSP core (core_id) */

struct sof_cdev_pm_ctl {
__u32 op; /* SOF_PM_OP_* */
__u32 core_id; /* Used for CORE_GET / CORE_PUT */
__u32 fw_state; /* Out: current enum sof_fw_state */
__u32 dsp_power_state; /* Out: current DSP power state */
__u32 pm_runtime_active; /* Out: 1 if runtime PM is active (D0) */
__u32 enabled_cores_mask; /* Out: current enabled_cores_mask */
__u32 fd_holding_d0; /* Out: 1 if this fd currently holds a D0 reference */
__u32 reserved;
};

/*
* Atomic IPC Transaction (SOF_IOC_IPC_TX)
*/
#define SOF_CDEV_IPC_FL_NO_REPLY (1U << 0) /* Do not expect payload reply */

struct sof_cdev_ipc_msg {
__u32 primary; /* In: IPC4 primary header (or IPC3 cmd) */
__u32 extension; /* In: IPC4 extension header */
__u32 tx_size; /* In: TX payload byte length */
__u32 rx_size; /* In: RX buffer capacity; Out: bytes received */
__u32 reply_primary; /* Out: IPC4 reply primary header */
__u32 reply_extension; /* Out: IPC4 reply extension header */
__s32 ipc_status; /* Out: Firmware reply status (0 = success) */
__u32 flags; /* In: SOF_CDEV_IPC_FL_* */
__u64 tx_data_ptr; /* In: Userspace pointer to TX payload (or 0) */
__u64 rx_data_ptr; /* In: Userspace pointer to RX buffer (or 0) */
};

/*
* IPC4 Large Config Get / Set (SOF_IOC_IPC_LARGE_CFG)
*/
#define SOF_CDEV_LARGE_CFG_GET 0
#define SOF_CDEV_LARGE_CFG_SET 1

struct sof_cdev_large_cfg {
__u32 module_id; /* 0 for BaseFW, or target module_id */
__u32 instance_id; /* 0 for BaseFW, or target instance_id */
__u32 param_id; /* IPC4 param ID (e.g. 14=MEMORY_STATE, 15=POWER_STATE) */
__u32 set_get; /* SOF_CDEV_LARGE_CFG_GET (0) or SET (1) */
__u32 data_size; /* In: buffer size; Out: actual bytes read/written */
__u32 flags;
__u64 data_ptr; /* Userspace buffer pointer */
};

/*
* Memory Window & Debug Slot I/O (SOF_IOC_WIN_INFO, SOF_IOC_WIN_READ, SOF_IOC_WIN_WRITE)
*/
#define SOF_CDEV_WIN_FL_WAKE_DSP (1U << 0) /* Wake DSP to D0 if currently suspended */

struct sof_cdev_win_info {
struct sof_cdev_win_desc windows[SOF_CDEV_MAX_WINDOWS];
struct sof_cdev_slot_desc debug_slots[SOF_CDEV_MAX_DEBUG_SLOTS];
};

struct sof_cdev_win_io {
__u32 win_id; /* SOF_CDEV_WIN_0..3 or SOF_CDEV_WIN_BY_SLOT_TYPE */
__u32 slot_type; /* Used when win_id == SOF_CDEV_WIN_BY_SLOT_TYPE */
__u32 slot_index; /* Match Nth slot of slot_type (0 = first match) */
__u32 offset; /* Byte offset within window or slot */
__u32 size; /* Bytes to read or write */
__u32 flags; /* SOF_CDEV_WIN_FL_* */
__u64 data_ptr; /* Userspace buffer pointer */
};

/*
* Zephyr Winstream Slot I/O (SOF_IOC_WINSTREAM_IO)
* Used for ADSP_DW_SLOT_SHELL (0x73686c6c) and GDB stub (0x42444700)
*/
struct sof_cdev_winstream_io {
__u32 slot_type; /* Default: SOF_CDEV_SLOT_SHELL (0x73686c6c) */
__u32 rx_win_size; /* Host->DSP winstream region size (default 256) */
__u32 tx_len; /* Bytes to write from tx_ptr to DSP (0 = read only) */
__u32 rx_buf_len; /* Max bytes to read into rx_ptr (0 = write only) */
__u32 rx_bytes_read; /* Out: Actual bytes read from DSP winstream */
__u32 seq_in_out; /* In/Out: Host reader sequence number */
__u64 tx_ptr; /* Userspace pointer to TX data */
__u64 rx_ptr; /* Userspace pointer to RX buffer */
};

/*
* Atomic LLEXT Module Loading (SOF_IOC_LLEXT_LOAD)
*/
#define SOF_LLEXT_MODE_SHELL_SHM 0 /* 2-step handshake via SOF_CDEV_SLOT_LLEXT_LOAD */
#define SOF_LLEXT_MODE_IPC4_DIRECT 1 /* Direct IPC4 LOAD_LIBRARY with explicit/auto lib_id */

struct sof_cdev_llext_load {
__u32 mode; /* SOF_LLEXT_MODE_* */
__u32 lib_id; /* In/Out: Library slot ID (1..15; 0 = from shm or auto) */
__u32 data_size; /* Size of .ri / .llext binary in bytes */
__s32 fw_state; /* Out: Final slot state or IPC status */
__u64 data_ptr; /* Userspace pointer to library binary */
};

/*
* SOF Probes Control (SOF_IOC_PROBE_CTL)
*/
#define SOF_PROBE_OP_INIT 1
#define SOF_PROBE_OP_DEINIT 2
#define SOF_PROBE_OP_INFO_ACTIVE 3
#define SOF_PROBE_OP_INFO_AVAILABLE 4
#define SOF_PROBE_OP_POINTS_ADD 5
#define SOF_PROBE_OP_POINTS_REMOVE 6

struct sof_cdev_probe_point {
__u32 buffer_id; /* Probe point ID (mod_id, inst_id, type, idx) */
__u32 purpose; /* 0 = EXTRACTION, 1 = INJECTION */
__u32 stream_tag; /* HDA stream tag (or 0 if disconnected) */
__u32 reserved;
char widget_name[32]; /* Resolved topology widget name (output on INFO) */
};

struct sof_cdev_probe_ctl {
__u32 op; /* SOF_PROBE_OP_* */
__u32 stream_tag; /* Used for SOF_PROBE_OP_INIT */
__u32 dma_buffer_size; /* Used for SOF_PROBE_OP_INIT */
__u32 num_points; /* In: capacity / count; Out: returned count */
__u64 points_ptr; /* Userspace pointer to struct sof_cdev_probe_point[] */
};

/*
* Async Event Notification Record read() from /dev/sof-dspN
*/
#define SOF_CDEV_EVT_FW_STATE 1
#define SOF_CDEV_EVT_IPC_NOTIFICATION 2

struct sof_cdev_event {
__u64 timestamp_ns; /* ktime_get_ns() */
__u32 event_type; /* SOF_CDEV_EVT_* */
__u32 fw_state; /* Current enum sof_fw_state */
__u32 primary; /* IPC4 notification primary header */
__u32 extension; /* IPC4 notification extension header */
};

/* IOCTL Definitions */
#define SOF_IOC_GET_INFO _IOR(SOF_CDEV_IOC_MAGIC, 0x01, struct sof_cdev_info)
#define SOF_IOC_PM_CTL _IOWR(SOF_CDEV_IOC_MAGIC, 0x02, struct sof_cdev_pm_ctl)
#define SOF_IOC_IPC_TX _IOWR(SOF_CDEV_IOC_MAGIC, 0x10, struct sof_cdev_ipc_msg)
#define SOF_IOC_IPC_LARGE_CFG _IOWR(SOF_CDEV_IOC_MAGIC, 0x11, struct sof_cdev_large_cfg)
#define SOF_IOC_WIN_INFO _IOR(SOF_CDEV_IOC_MAGIC, 0x20, struct sof_cdev_win_info)
#define SOF_IOC_WIN_READ _IOWR(SOF_CDEV_IOC_MAGIC, 0x21, struct sof_cdev_win_io)
#define SOF_IOC_WIN_WRITE _IOW(SOF_CDEV_IOC_MAGIC, 0x22, struct sof_cdev_win_io)
#define SOF_IOC_WINSTREAM_IO _IOWR(SOF_CDEV_IOC_MAGIC, 0x23, struct sof_cdev_winstream_io)
#define SOF_IOC_LLEXT_LOAD _IOWR(SOF_CDEV_IOC_MAGIC, 0x30, struct sof_cdev_llext_load)
#define SOF_IOC_PROBE_CTL _IOWR(SOF_CDEV_IOC_MAGIC, 0x40, struct sof_cdev_probe_ctl)

#endif /* __INCLUDE_UAPI_SOUND_SOF_CDEV_H */
10 changes: 10 additions & 0 deletions sound/soc/sof/Kconfig
Original file line number Diff line number Diff line change
Expand Up @@ -271,6 +271,16 @@ config SND_SOC_SOF_DEBUG_FW_GDB
socket, to which GDB can then connect.
If unsure, select "N".

config SND_SOC_SOF_CLIENT_CDEV
tristate "SOF character device client (/dev/sof-dspN)"
depends on SND_SOC_SOF && SND_SOC_SOF_IPC4
select SND_SOC_SOF_CLIENT
help
This enables the SOF character device client driver (/dev/sof-dspN)
exposing ioctls for atomic IPC transactions, SRAM memory window I/O
and mmap, LLEXT module loading, Zephyr winstream shell/GDB access,
and SOF probe point control.

config SND_SOC_SOF_DEBUG_RETAIN_DSP_CONTEXT
bool "SOF retain DSP context on any FW exceptions"
help
Expand Down
2 changes: 2 additions & 0 deletions sound/soc/sof/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ ifneq ($(CONFIG_SND_SOC_SOF_IPC4),)
snd-sof-probes-y += sof-client-probes-ipc4.o
endif
snd-sof-fw-gdb-objs := sof-client-fw-gdb.o
snd-sof-client-cdev-y := sof-client-cdev.o

snd-sof-nocodec-y := nocodec.o

Expand All @@ -55,6 +56,7 @@ obj-$(CONFIG_SND_SOC_SOF_DEBUG_IPC_MSG_INJECTOR) += snd-sof-ipc-msg-injector.o
obj-$(CONFIG_SND_SOC_SOF_DEBUG_IPC_KERNEL_INJECTOR) += snd-sof-ipc-kernel-injector.o
obj-$(CONFIG_SND_SOC_SOF_DEBUG_PROBES) += snd-sof-probes.o
obj-$(CONFIG_SND_SOC_SOF_DEBUG_FW_GDB) += snd-sof-fw-gdb.o
obj-$(CONFIG_SND_SOC_SOF_CLIENT_CDEV) += snd-sof-client-cdev.o

obj-$(CONFIG_SND_SOC_SOF_INTEL_TOPLEVEL) += intel/
obj-$(CONFIG_SND_SOC_SOF_IMX_TOPLEVEL) += imx/
Expand Down
88 changes: 88 additions & 0 deletions sound/soc/sof/ipc4-loader.c
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,94 @@ static int sof_ipc4_load_library(struct snd_sof_dev *sdev, unsigned long lib_id,
return ret;
}

/**
* snd_sof_ipc4_load_library_from_buf - load an IPC4 library from an in-memory buffer
* @sdev: SOF device
* @lib_id: target library slot [1 .. max_libs_count - 1]
* @buf: raw library binary (rimage format with ext-manifest header)
* @size: size of the binary in bytes
*
* Return: 0 on success, negative errno on error.
*/
int snd_sof_ipc4_load_library_from_buf(struct snd_sof_dev *sdev, u32 lib_id,
const void *buf, size_t size)
{
struct sof_ipc4_fw_data *ipc4_data = sdev->private;
struct sof_ipc4_fw_library *old_lib;
struct sof_ipc4_fw_library *fw_lib;
struct firmware *fake_fw;
ssize_t payload_offset;
int i, ret;

if (!ipc4_data || !ipc4_data->load_library) {
dev_err(sdev->dev, "Library loading not supported on this platform\n");
return -EOPNOTSUPP;
}

if (!lib_id || lib_id >= ipc4_data->max_libs_count) {
dev_err(sdev->dev, "Invalid lib_id %u (max %u)\n",
lib_id, ipc4_data->max_libs_count - 1);
return -EINVAL;
}

fake_fw = devm_kzalloc(sdev->dev, sizeof(*fake_fw), GFP_KERNEL);
if (!fake_fw)
return -ENOMEM;
fake_fw->data = buf;
fake_fw->size = size;

fw_lib = devm_kzalloc(sdev->dev, sizeof(*fw_lib), GFP_KERNEL);
if (!fw_lib) {
devm_kfree(sdev->dev, fake_fw);
return -ENOMEM;
}

fw_lib->sof_fw.fw = fake_fw;
fw_lib->name = "cdev-llext";

payload_offset = sof_ipc4_fw_parse_ext_man(sdev, fw_lib);
if (payload_offset <= 0) {
ret = payload_offset ? (int)payload_offset : -EINVAL;
goto free_fw_lib;
}

fw_lib->sof_fw.payload_offset = payload_offset;
fw_lib->id = lib_id;

for (i = 0; i < fw_lib->num_modules; i++)
fw_lib->modules[i].man4_module_entry.id |=
(lib_id << SOF_IPC4_MOD_LIB_ID_SHIFT);

ret = ipc4_data->load_library(sdev, fw_lib, false);
if (ret)
goto free_modules;

/* Allow replacing a previously purged interactive library in the same slot */
old_lib = xa_erase(&ipc4_data->fw_lib_xa, lib_id);
if (old_lib) {
devm_kfree(sdev->dev, old_lib->modules);
devm_kfree(sdev->dev, old_lib);
}

ret = xa_insert(&ipc4_data->fw_lib_xa, lib_id, fw_lib, GFP_KERNEL);
if (unlikely(ret)) {
dev_err(sdev->dev, "Library ID %u already registered\n", lib_id);
goto free_modules;
}

dev_info(sdev->dev, "LLEXT library loaded as lib_id=%u (%zu bytes)\n",
lib_id, size);
return 0;

free_modules:
devm_kfree(sdev->dev, fw_lib->modules);
free_fw_lib:
devm_kfree(sdev->dev, fw_lib);
devm_kfree(sdev->dev, fake_fw);
return ret;
}
EXPORT_SYMBOL_NS_GPL(snd_sof_ipc4_load_library_from_buf, "SND_SOC_SOF");

/**
* sof_ipc4_complete_split_release - loads the library parts of a split firmware
* @sdev: SOF device
Expand Down
Loading
Loading