xt_audio_dev_drv - 音频驱动接口

版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_audio/

---

一、概述

xt_audio_dev_drv 是音频驱动接口，面向平台移植开发者。移植者实现 5 个 ops 函数并注册驱动描述符后，xt_audio_dev 即可通过统一的抽象层调用具体硬件。本模块不面向应用用户。

1.1 设计原则

• 最小接口 ：ops 仅要求 5 个函数（ open / close / write / read / ctrl ），所有扩展能力通过 ctrl 命令实现
• ctx 隔离 ：每个驱动实例绑定私有 ctx 指针，避免全局变量
• 开关独立 ：设备开关（ struct xt_audio_dev_sw_desc ）独立于驱动 ops ，支持 GPIO 或回调控制

1.2 依赖

依赖	用途
xt_audio_types.h	音频句柄、模式、格式类型

---

二、核心概念

2.1 驱动 ops

struct xt_audio_dev_ops 是移植者必须实现的接口，共 5 个函数指针：

ops 函数	签名	说明
open	xt_err_t (*open)(void *ctx, struct xt_audio_format *fmt, xt_audio_dev_drv_cb_t cb, void *cb_ctx)	打开设备，传入格式、回调
close	xt_err_t (*close)(void *ctx)	关闭设备
write	int (*write)(void *ctx, uint8_t *data, uint32_t size)	写入数据，正数返回实际写入量，负数返回错误码
read	int (*read)(void *ctx, uint8_t *data, uint32_t size)	读取数据，正数返回实际读取量，负数返回错误码
ctrl	xt_err_t (*ctrl)(void *ctx, int cmd, union xt_audio_dev_ctrl_arg *arg)	控制命令（音量、休眠、参数等）

所有 ops 的 ctx 参数均由注册时传入的 struct xt_audio_dev_drv.ctx 提供。

2.2 驱动描述符

struct xt_audio_dev_drv 是注册时传入的结构体：

字段	类型	说明
name	const char *	驱动逻辑名（如 "codec" 、 "dac" ），用于 setup 时匹配
ops	struct xt_audio_dev_ops *	驱动的 ops 实现
ctx	void *	驱动的板级私有数据（传给所有 ops）

2.3 ctrl 命令

ctrl ops 通过 cmd 参数区分操作，通过 union xt_audio_dev_ctrl_arg 传递参数：

命令	说明	使用场景
XT_AUDIO_DEV_CTRL_ACTIVE	idle→active 状态切换	开始传输前激活硬件
XT_AUDIO_DEV_CTRL_IDLE	active→idle 状态切换	停止传输后释放硬件
XT_AUDIO_DEV_CTRL_SLEEP	深休眠	低功耗场景
XT_AUDIO_DEV_CTRL_RESUME	从深休眠恢复	唤醒
XT_AUDIO_DEV_CTRL_SET_WRITE_LEVEL	设置写方向音量	用户调用 write 时
XT_AUDIO_DEV_CTRL_SET_READ_LEVEL	设置读方向音量	用户调用 read 时
XT_AUDIO_DEV_CTRL_GET_WRITE_LEVEL	获取写方向默认音量	设备层初始化查询
XT_AUDIO_DEV_CTRL_GET_READ_LEVEL	获取读方向默认音量	设备层初始化查询
XT_AUDIO_DEV_CTRL_SET_PARAM	设置单个参数	调试用
XT_AUDIO_DEV_CTRL_GET_PARAM	获取单个参数	调试用
XT_AUDIO_DEV_CTRL_SET_PARAM_LIST	设置参数等级列表	音量等步进参数
XT_AUDIO_DEV_CTRL_GET_PARAM_LIST	获取参数等级列表	查询已注册的参数

2.4 设备开关

struct xt_audio_dev_sw_desc 配置设备的硬件开关（功放使能等）， 建议使用 CB 模式，仅在没有 CB 时使用 IO 模式：

字段	类型	说明
cb	函数指针	开关回调（非 NULL 时优先）
cb_arg	void *	回调参数
io	uint8_t	GPIO 编号（ IO 模式）
active_level	uint8_t	使能电平
on_delay_ms	uint16_t	开启后延时（ms）
off_delay_ms	uint16_t	关闭前延时（ms）

2.5 驱动→设备层回调

驱动通过 open 时传入的 xt_audio_dev_drv_cb_t 回调通知上层事件：

事件	说明
XT_AUDIO_DEV_DRV_EVT_TX_IDLE	写方向 ring buffer 排空（可通知上层停止写入）
XT_AUDIO_DEV_DRV_EVT_RX_IDLE	读方向（预留）

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_audio_dev_drv（音频设备驱动） 。

3.1 驱动注册

函数签名	说明
xt_err_t xt_audio_dev_register_drv(struct xt_audio_dev_drv *drv)	注册音频驱动

3.2 ops 类型

类型签名	说明
struct xt_audio_dev_ops	驱动 ops（5 个函数指针： open / close / write / read / ctrl ）
struct xt_audio_dev_drv	驱动描述符（ name + ops + ctx ）
union xt_audio_dev_ctrl_arg	ctrl 命令参数联合体

3.3 事件类型

类型签名	说明
enum xt_audio_dev_drv_evt	驱动→dev 回调事件（ TX_IDLE / RX_IDLE ）
void (*xt_audio_dev_drv_cb_t)(int evt, void *user_data)	驱动回调函数类型

---

四、常见模式

4.1 注册自定义驱动

#include "xt_audio_dev_drv.h"
 
static xt_err_t _my_open(void *ctx, struct xt_audio_format *fmt,
                         xt_audio_dev_drv_cb_t cb, void *cb_ctx)
{
    /* 初始化硬件，配置 DMA/I2S ，启动传输 */
    return XT_EOK;
}
 
static xt_err_t _my_close(void *ctx)
{
    /* 停止硬件，释放资源 */
    return XT_EOK;
}
 
static int _my_write(void *ctx, uint8_t *data, uint32_t size)
{
    /* 将数据送入硬件发送缓冲区，返回实际写入量 */
    return (int)size;
}
 
static int _my_read(void *ctx, uint8_t *data, uint32_t size)
{
    /* 从硬件接收缓冲区读取数据，返回实际读取量 */
    return 0;
}
 
static xt_err_t _my_ctrl(void *ctx, int cmd, union xt_audio_dev_ctrl_arg *arg)
{
    switch (cmd) {
    case XT_AUDIO_DEV_CTRL_SET_WRITE_LEVEL:
        /* 设置音量 arg->set_level.val */
        break;
    case XT_AUDIO_DEV_CTRL_SLEEP:
        /* 硬件休眠 */
        break;
    default:
        break;
    }
    return XT_EOK;
}
 
static struct xt_audio_dev_ops s_my_ops = {
    .open  = _my_open,
    .close = _my_close,
    .write = _my_write,
    .read  = _my_read,
    .ctrl  = _my_ctrl,
};
 
void register_my_drv(void *board_ctx)
{
    struct xt_audio_dev_drv drv = {
        .name = "my_audio",
        .ops  = &s_my_ops,
        .ctx  = board_ctx,
    };
    xt_audio_dev_register_drv(&drv);
}

注册后，用户可通过 drv_name = "my_audio" 在 xt_audio_dev_setup() 中使用此驱动。

4.2 注册顺序要求

int main(void)
{
    register_my_drv(board_ctx);          /* 1. 先注册驱动 */
    xt_audio_dev_setup(&cfg, &dev);      /* 2. 再创建设备（匹配 drv_name） */
}

---

五、已知行为与限制

行为	说明
open 时传入格式	设备层将用户配置的 struct xt_audio_format 传给 ops ，驱动需根据格式配置硬件
write/read 区分方向	根据 setup 时的 mode 决定调 write 还是 read（全双工时两者都调）
ctrl 命令可能交叉调用	ACTIVE/IDLE 与 SLEEP/RESUME 状态机由驱动自行维护
on_delay_ms/off_delay_ms	仅 IO 模式下生效， CB 模式 下延时由回调自行处理
驱动需在 setup 前注册	否则 setup 时无法匹配驱动