MIGRATED

XiDSP API 文档 v1.0

摘要

本文档定义 XiDSP 芯片所有对外可编程接口：寄存器映射 / ISA 指令集 / Bus 协议 / Driver SDK / JTAG 调试 / Secure Boot。目标读者：固件工程师、板级驱动工程师、Tier1 集成工程师、XiStudio 后端开发。本文与 tech-arch.md 互为参照：tech-arch 说"芯片长什么样"，api 说"芯片怎么用"。

稳定性契约

寄存器地址 + 字段语义 一旦 Datasheet 发布后保证向后兼容（同 Die Family 内）
ISA 指令编码在同一 ISA 大版本内向后兼容
Driver SDK 遵循 SemVer：主版本号变更可能破坏源码兼容
Reserved 位段必须读作 0 / 写 0，未来可能启用

1. 寄存器 API

1.1 寄存器地址空间

区段	基址	大小	总线	说明
DSP Core Ctrl	0x4000_0000	4 KB	APB	核心控制 / 状态
Audio IF	0x4001_0000	8 KB	APB	I²S / TDM / PDM / ASRC
DMA	0x4002_0000	4 KB	APB	Audio DMA 16-channel
CAN-FD × 2	0x4003_0000	8 KB	APB	每个 CAN 4KB
UART × 2	0x4004_0000	2 KB	APB
SPI × 2	0x4005_0000	2 KB	APB
I²C × 2	0x4006_0000	2 KB	APB
GPIO	0x4007_0000	4 KB	APB	32 位
Security Engine	0x4008_0000	16 KB	APB	含 Key Vault
PMU	0x4009_0000	4 KB	APB	功耗 / 唤醒
PLL / CGU	0x400A_0000	4 KB	APB	时钟配置
WDT	0x400B_0000	1 KB	APB	看门狗

1.2 寄存器访问约定

所有寄存器 32-bit 对齐，不支持 byte / halfword 部分访问（除非字段标注）
读-改-写：对多字段寄存器必须用 RMW 或专用 Set/Clear 寄存器
Reserved 位段写 0，读忽略

1.3 DSP Core Control（0x4000_0000）示例

偏移	名称	访问	复位值	说明
0x00	CORE_ID	RO	0xD1A0_0001	Die ID + Revision
0x04	CORE_CTRL	RW	0x0000_0000	使能 / 复位 / 调试
0x08	CORE_STATUS	RO	0x0000_0000	运行 / Stall / Fault
0x0C	CORE_CLK_CFG	RW	0x0000_0001	PLL 选择 / 分频
0x10	CORE_PC	RO	—	当前 PC
0x14	CORE_IRQ_EN	RW	0x0000_0000	32 级中断使能
0x18	CORE_IRQ_STAT	R/W1C	0x0000_0000	中断状态（写 1 清）
0x1C	CORE_FAULT	R/W1C	0x0000_0000	ECC / 总线错误标志

CORE_CTRL 位字段

 31                                                                 0
+-----+-----+-----+-----+-----+-----+-----+-----+--------------------+
| RSV | DBG | BPT | STP | HLT | SWR | RST |  EN | Reserved           |
+-----+-----+-----+-----+-----+-----+-----+-----+--------------------+

位	名称	访问	说明
[31:8]	Reserved	—	写 0
[7]	DBG_MODE	RW	进入 JTAG 调试
[6]	BPT_EN	RW	硬件断点使能
[5]	STP_MODE	RW	单步执行
[4]	HLT	RW	停机
[3]	SW_RST	W1S	软复位（自动清零）
[2]	RST	RW	同步复位保持
[1]	Reserved	—
[0]	EN	RW	Core 使能

2. ISA 指令集（XiDSP-ISA v1.0）

2.1 指令格式

VLIW Bundle（128-bit = 4× 32-bit slot）:
+-------------+-------------+-------------+-------------+
| Slot 0 ALU  | Slot 1 ALU  | Slot 2 MAC  | Slot 3 MEM  |
+-------------+-------------+-------------+-------------+

每 cycle 发射 1 个 bundle（4 指令并行）
Slot 空闲用 NOP 填充
汇编器自动打包

2.2 指令分类

类	数量	示例	说明
ALU 算术	32	ADD / SUB / AND / OR / XOR	整数定点
MAC 乘加	16	MAC / MSU / MULH / DOT4	包含 SIMD
移位 / 截位	12	SHL / SHR / SAT / TRUNC	Q-Format 友好
存储	16	LD / ST / LDX / STX	圆形寻址 / Bit-rev
分支	10	BEQ / BNE / JAL / RET	硬件 loop
系统	8	MFSR / MTSR / WFI / ERET	特权态
音频专用	12	FIR4 / IIR2 / BITREV_LD	复合指令

2.3 寻址模式

模式	语法	说明
直接	`LD R1, [0x1000]`	立即地址
寄存器间接	`LD R1, [R2]`
偏移	`LD R1, [R2, #8]`
后递增	`LD R1, [R2]+, #4`	步长 4
圆形	`LD R1, [R2]%BUF_LEN`	FIR / 延迟线核心
Bit-reverse	`LD R1, [R2]~FFT_N`	FFT 核心

2.4 典型音频算法指令示例

; 8-tap FIR 滤波（圆形寻址 + DOT4 SIMD）
; R2 = 输入指针，R3 = 系数指针，R4 = 累加器
; 每 cycle 处理 4 个 tap
fir_loop:
    DOT4    R4, [R2]+%8, [R3]+       ; 4-way MAC，圆形步进
    DOT4    R4, [R2]+%8, [R3]+       ; 4-way MAC
    SAT     R5, R4, #24              ; 饱和到 24-bit
    ST      R5, [R6]+                ; 输出
    BNZ     LOOP_CTR, fir_loop       ; 硬件 loop

2.5 寄存器规范

寄存器	数量	用途	调用约定
R0-R7	8	通用 + 参数传递	Caller-save
R8-R23	16	通用	Callee-save
R24-R31	8	特殊（SP / LR / FP 等）	ABI 指定
ACC0-ACC7	8	累加器（72-bit）	Caller-save
SR	1	状态寄存器	—
IPC	1	中断 PC	—

3. Bus 协议

3.1 I²S

LRCLK     _|‾‾‾‾‾‾‾‾‾‾‾‾‾|_____________|‾‾‾‾
BCLK      _| |_| |_| |_| |_| |_| |_| |_| |_
DATA      ---<D23><D22>...<D0 ><D23>...------
           ← 左声道(24-bit) ←→ 右声道 ←

模式	支持
Standard I²S	✅
Left-Justified	✅
Right-Justified	✅
DSP / PCM Mode A/B	✅
TDM-4 / TDM-8 / TDM-16	✅

寄存器：I2S_CTRL（0x4001_0000）/ I2S_CLK_CFG / I2S_FMT / I2S_FIFO_STAT。

3.2 TDM

参数	范围
Slot 数	4 / 8 / 16
Slot 位宽	16 / 24 / 32
帧同步	短帧 / 长帧可配
时钟极性	BCLK 上升沿 / 下降沿

3.3 PDM

4 路 PDM 输入（支持 1-bit 差分或单端）
集成 CIC Decimator（5 阶）+ 可编程补偿 FIR
输出采样率：16 / 32 / 48 / 96 kHz
SNR 目标：> 85 dB（A-weighted，PDM 信源 64× 过采样）

3.4 SPI

参数	规格
模式	Master / Slave
时钟	≤ 50 MHz（Master）
极性 / 相位	CPOL/CPHA 四模式
位宽	4-32 bit
FIFO	16 深 × Tx/Rx
DMA	支持

3.5 I²C

Fast+ Mode（1 MHz）、Fast Mode（400 kHz）、Standard（100 kHz）
7-bit / 10-bit 地址
Multi-master（冲突检测）
时钟拉伸支持

3.6 UART

波特率：300 - 6,000,000
数据位：⅚/⅞/9
校验：无 / 奇 / 偶 / Stick
流控：RTS/CTS
FIFO：16 深 × Tx/Rx
DMA：支持

4. Driver SDK

4.1 SDK 分层

graph TB
    App[客户应用 C 代码]
    App --> XiAlgoLib[XiAlgo 算法库]
    XiAlgoLib --> XiCore[XiCore 运行时<br/>调度 / 内存 / IPC]
    XiCore --> XiHAL[XiHAL 硬件抽象<br/>Audio / Comm / Sec]
    XiHAL --> Reg[寄存器 Poke/Peek]
    Reg --> HW[XiDSP 硬件]

    class App xyL5
    class XiAlgoLib xyL4
    class XiCore xyL3
    class XiHAL xyL2
    class Reg xyL1
    class HW xyL0

4.2 HAL C API 示例

// xi_i2s.h
typedef struct {
    uint8_t  channel_id;        // 0..7
    uint32_t sample_rate;       // 48000 etc.
    uint8_t  bit_width;         // 16/24/32
    uint8_t  mode;              // I2S / TDM / PDM
    bool     is_master;
} xi_i2s_config_t;

xi_status_t xi_i2s_init(const xi_i2s_config_t *cfg);
xi_status_t xi_i2s_start(uint8_t ch);
xi_status_t xi_i2s_stop(uint8_t ch);
xi_status_t xi_i2s_register_cb(uint8_t ch, xi_i2s_cb_t cb, void *user);

// 错误码
typedef enum {
    XI_OK              = 0,
    XI_ERR_PARAM       = -1,
    XI_ERR_NOT_READY   = -2,
    XI_ERR_TIMEOUT     = -3,
    XI_ERR_HW_FAULT    = -4,
    XI_ERR_NO_MEM      = -5,
} xi_status_t;

4.3 Audio DMA 使用范式

// 1. 配置双缓冲 DMA
xi_dma_desc_t desc[2];
desc[0].src = I2S0_RX_FIFO;
desc[0].dst = buffer_A;
desc[0].len = 256 * sizeof(int32_t);
desc[0].next = &desc[1];
desc[0].irq_on_complete = true;

desc[1] = desc[0];
desc[1].dst = buffer_B;
desc[1].next = &desc[0];  // 形成环

// 2. 注册完成回调
xi_dma_register_cb(DMA_CH_AUDIO_IN, on_audio_buffer_ready, NULL);

// 3. 启动
xi_dma_start(DMA_CH_AUDIO_IN, &desc[0]);

4.4 Python Host Tools（上位机）

from xidsp import XiDevice

dev = XiDevice.open(port="COM7", baud=921600)

# 读寄存器
core_id = dev.read_reg(0x40000000)
print(f"CORE_ID = 0x{core_id:08X}")

# 烧录固件
dev.flash("firmware.xifw", verify=True)

# 实时 Scope
with dev.scope(ch=[0, 1], sample_rate=48000) as scope:
    samples = scope.capture(duration_s=2.0)
    # samples: np.ndarray shape=(2, 96000)

4.5 SDK 版本与兼容性

SDK 版本	目标固件	目标芯片 Rev	Python	备注
v1.0.x	固件 v1.0+	A0 / B0	3.9+	首发
v1.1.x	固件 v1.1+	B0+	3.9+	新增 PDM Host 模拟
v2.0.x	固件 v2.0+	B1+（规划）	3.10+	破坏性变更（合并 API）

5. JTAG 调试 API

5.1 JTAG 信号

信号	方向	说明
TCK	In	测试时钟（≤ 20 MHz）
TMS	In	状态机控制
TDI	In	串行输入
TDO	Out	串行输出
TRST_n	In	异步复位（可选）

5.2 TAP 指令

指令	IR 编码	说明
IDCODE	0x01	读 32-bit Die ID
BYPASS	0xFF	1-bit 旁路
EXTEST	0x02	边界扫描
SAMPLE	0x03	采样 Pad 值
DEBUG	0x08	进入 DSP Debug 模式
SCAN	0x0A	Scan Chain 测试（量产）
IJTAG_GATE	0x20	IJTAG 网络入口

5.3 Debug 模式命令（通过 DEBUG 指令进入后）

READ_REG <addr> — 读任意寄存器
WRITE_REG <addr> <val> — 写寄存器
READ_MEM <addr> <len> — 读内存
HALT / RESUME — 控制 Core
STEP — 单步
SET_BP <addr> / CLR_BP <id> — 硬件断点
LOCK — 一次性锁定 JTAG（量产）

5.4 Secure Debug

JTAG 锁定不可逆

量产阶段通过写 OTP 的 JTAG_LOCK bit（一次性熔丝）永久锁定 JTAG。仅保留 IDCODE / BYPASS，禁止 DEBUG / SCAN。开发阶段可用 密码解锁模式：写入 256-bit 挑战 + Xisound 签名返回 → 临时解锁，断电后恢复锁定。

6. Secure Boot API

6.1 启动流程

graph LR
    POR[POR 上电] --> ROM[片内 ROM<br/>Bootloader]
    ROM --> VerifyKey[读 OTP Root Key]
    VerifyKey --> ReadFW[读 Flash 固件头]
    ReadFW --> VerifySig{RSA-2048<br/>签名校验}
    VerifySig -- OK --> Exec[跳转固件执行]
    VerifySig -- Fail --> Fallback[进入 Recovery Mode]

    class POR xyL0
    class ROM xyL3
    class VerifyKey,ReadFW xyL2
    class VerifySig xyWarn
    class Exec xySuccess
    class Fallback xyError

6.2 固件镜像格式

+----------------------+  0x0000
| Magic "XIFW"         |  4 bytes
+----------------------+
| Version (major/minor)|  4 bytes
+----------------------+
| Image Size           |  4 bytes
+----------------------+
| Image Load Addr      |  4 bytes
+----------------------+
| Image Entry Point    |  4 bytes
+----------------------+
| SHA-256 of Image     |  32 bytes
+----------------------+
| RSA-2048 Signature   |  256 bytes
+----------------------+
| Reserved             |  padding to 0x200
+----------------------+  0x0200
| Image Body           |  Image Size
+----------------------+

6.3 OTP 布局（4 KB）

偏移	大小	用途
0x000	256 B	Xisound Root Public Key
0x100	128 B	客户 Public Key（可选）
0x180	16 B	Device UUID（唯一）
0x190	32 B	出厂校准数据
0x1B0	16 B	Feature Flags（启用/禁用 IP）
0x1C0	16 B	Lock Bits（JTAG / 国密 / 客户锁）
0x1D0 - 0xFFF	3632 B	客户 OEM 区

6.4 FOTA 升级

双分区（A/B）设计：当前分区运行，对侧分区升级
升级包加密：AES-128-GCM（Key 由客户 Public Key 包裹）
签名：RSA-2048
Rollback 保护：OTP 存 Version Counter，禁止降级

7. 中断向量表

编号	向量	触发源	优先级（默认）
0	Reset	POR / 软复位	—
1	NMI	ECC 双位 / 总线 Fault	最高
2	HardFault	指令异常	最高
3	SVC	系统调用	中
4-11	Audio IF	I²S/TDM/PDM 完成	高
12-27	DMA 各通道	DMA 完成	高
28-29	CAN-FD × 2	收 / 发	中
30-31	UART × 2	RX / TX	中
32-33	SPI × 2		中
34-35	I²C × 2		中
36	GPIO 边沿		低
37	SecEng 完成		中
38	WDT	看门狗	最高
39-63	Reserved		—

8. 与其他 API 的关系

关联	交互方式
XiStudio	通过 Python Host Tools + XiFlash USB 烧录
XiAlgo	C API + ABI v1.0（固化至 XiDSP 运行时）
XiAmp	通过 I²S / TDM 输出连接
XiTest	JTAG IJTAG + Python Scan 脚本
XiMind	上位机工具调用 SDK 生成 Trace，AI 辅助分析

9. 附录

9.1 寄存器完整表

完整寄存器表（超过 400 条）以独立附录 D3-execution/xidsp-d1-regmap.csv + xidsp-d1-regmap.html 发布（Phase 3 后续批次）。

9.2 ISA 完整编码表

完整指令编码表（二进制 bit pattern）以独立附录 D3-execution/xidsp-isa-encoding.pdf 发布。

9.3 关联文档

9.4 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · 寄存器 + ISA + Bus 协议 + Driver SDK + JTAG + Secure Boot

api.md · D2-P2-TECH-002 · v1.0 · 2026-05-05 · Xisound 研发中心 · 芯片团队 + 固件团队