XiAlgo · API Reference

XiAlgo API 文档 v1.0

C ABI · Python SDK · XiParam · .xipkg · Sign CLI

文档编号：D2-P5-TECH-002 · 版本：v1.0 · 发布：2026-05-05

每一个算法块都有契约 · 每一条参数都有范围

ABI v1.0

二进制接口

C/Python

SDK 语言

.xipkg

交付格式

XiAlgo API 文档 v1.0

摘要

本文档定义 XiAlgo 算法库的完整对外编程接口：C ABI（算法块生命周期）、Python SDK（上位机打包与调试）、XiParam 协议（参数元数据）、.xipkg 包结构、签名 CLI（xi-algo-sign）。 目标读者：算法工程师（写算法块）、XiStudio 后端工程师（加载算法）、Tier1 集成工程师（调用 SDK）、IDM 客户 DSP 移植团队。

稳定性契约

• C ABI 在同一 ABI 大版本内（v1.x）二进制向后兼容
• XiParam 协议字段仅允许新增，不允许修改 / 删除
• Python SDK 遵循 SemVer：主版本号变更可能破坏源码兼容
• .xipkg Manifest JSON Schema 必须匹配 manifest_schema_version

---

1. C ABI（算法块接口）

1.1 ABI 版本

ABI 版本	发布	目标 XiDSP	状态
v1.0	2026-Q4	D1 / D2	当前
v2.0	2028-Q2（规划）	D2 / D3 / A1	规划中 · 破坏性变更

1.2 核心数据结构

// xi_algo.h

#define XI_ABI_VERSION 0x00010000  // v1.0

typedef enum {
    XI_OK              = 0,
    XI_ERR_PARAM       = -1,
    XI_ERR_NOT_READY   = -2,
    XI_ERR_NO_MEM      = -3,
    XI_ERR_TIMEOUT     = -4,
    XI_ERR_ABI_MISMATCH= -5,
    XI_ERR_SIGNATURE   = -6,
    XI_ERR_INTERNAL    = -99,
} XiStatus;

typedef struct XiParam XiParam;  // 见 §3
typedef struct XiCtx   XiCtx;    // 算法块私有上下文（不透明）

typedef struct XiAlgoBlock {
    /* ---- 元数据 ---- */
    uint32_t abi_version;           // 必须 = XI_ABI_VERSION
    const char* name;               // "PEQ_5band"
    const char* version;            // "1.0.0"

    /* ---- 形状 ---- */
    uint32_t input_channels;
    uint32_t output_channels;
    uint32_t sample_rate;           // e.g. 48000
    uint32_t frame_size;             // 典型 48

    /* ---- 资源估算 ---- */
    uint32_t mips_estimate;         // 每秒百万条指令
    uint32_t memory_bytes;          // 静态内存需求
    uint32_t param_count;

    /* ---- 生命周期 ---- */
    XiStatus (*init)(XiCtx* ctx, const XiParam* params);
    XiStatus (*process)(XiCtx* ctx,
                        const float* const* in,
                        float* const* out,
                        uint32_t frames);
    XiStatus (*update_param)(XiCtx* ctx, const XiParam* p);
    XiStatus (*destroy)(XiCtx* ctx);
} XiAlgoBlock;

1.3 生命周期调用约定

graph LR
    Host[XiCore 宿主] --> InitCall[init ctx params]
    InitCall --> Loop[帧循环]
    Loop --> ProcessCall[process ctx in out frames]
    ProcessCall --> Loop
    Loop --> UpdateCall[update_param ctx p · 可选]
    UpdateCall --> Loop
    Loop --> DestroyCall[destroy ctx]

    class Host xyL5
    class InitCall,DestroyCall xyL4
    class ProcessCall xyL3
    class UpdateCall xyWarn
    class Loop xyL2

1.4 process() 硬实时契约

• 输入：in[c][s] · c 为通道索引 0..input_channels-1，s 为采样点索引 0..frames-1
• 输出：out[c][s] 同上
• Budget：frames × 1000 / sample_rate 毫秒内必须返回（典型 1 ms）
• 返回值：XI_OK 正常；其他值触发 XiCore Fault 降级
• 禁用：malloc / free / printf / sleep / 阻塞 IO
• 允许：算数 / XiCore memory pool API / 原子操作

1.5 算法块注册宏

// 每个 .xo 块必须定义的导出符号
XI_EXPORT const XiAlgoBlock xi_block = {
    .abi_version = XI_ABI_VERSION,
    .name = "PEQ_5band",
    .version = "1.0.0",
    .input_channels = 1,
    .output_channels = 1,
    .sample_rate = 48000,
    .frame_size = 48,
    .mips_estimate = 10,
    .memory_bytes = 1024,
    .param_count = 15,
    .init = peq5_init,
    .process = peq5_process,
    .update_param = peq5_update,
    .destroy = peq5_destroy,
};

---

2. XiParam 参数协议

2.1 参数定义

typedef enum {
    XI_PARAM_FLOAT  = 0,
    XI_PARAM_INT    = 1,
    XI_PARAM_ENUM   = 2,
    XI_PARAM_BOOL   = 3,
    XI_PARAM_STRING = 4,
} XiParamType;

struct XiParam {
    const char*   param_id;       // "peq.band1.freq"
    XiParamType   type;

    union {
        float  f;
        int32_t i;
        int32_t enum_val;
        bool   b;
        const char* s;
    } value;

    union {
        struct { float min, max; } f_range;
        struct { int32_t min, max; } i_range;
    } range;

    const char* unit;             // "Hz"
    float       ramp_ms;          // 0 = 立即生效
    const char* display_name;     // "1 段频率"
};

2.2 参数 ID 命名规范

<block>.<scope>.<attribute>
  例：peq.band1.freq
      peq.band1.gain
      peq.band1.q
      drc.attack
      drc.release
      drc.threshold
      zone.front_left.gain

2.3 参数 JSON 序列化

{
  "param_id": "peq.band1.freq",
  "type": "float",
  "value": 1000.0,
  "range": {"min": 20.0, "max": 20000.0},
  "unit": "Hz",
  "ramp_ms": 20.0,
  "display_name": "1 段频率"
}

2.4 参数更新 API

// 单个参数更新
XiStatus xi_block_set_param(XiAlgoBlock* blk, XiCtx* ctx,
                            const XiParam* p);

// 批量原子更新（v1.0 尽力而为 · v2.0 事务级）
XiStatus xi_block_set_params_bulk(XiAlgoBlock* blk, XiCtx* ctx,
                                  const XiParam* params,
                                  uint32_t count);

---

3. .xipkg 包结构

3.1 Manifest JSON

{
  "manifest_schema_version": "1.0",
  "name": "XiAlgo-FX",
  "version": "1.0.0",
  "abi": "v1.0",
  "target_dsp": ["D1", "D2"],
  "tier": "pro",
  "license": "XiAlgo-Pro-Subscription",
  "signature_algo": "rsa-2048-sha256",
  "blocks": [
    {
      "name": "PEQ_5band",
      "file": "blocks/peq_5band_d1.xo",
      "target_dsp": "D1",
      "version": "1.0.0"
    },
    {
      "name": "DRC_multiband",
      "file": "blocks/drc_multi_d1.xo",
      "target_dsp": "D1",
      "version": "1.0.0"
    }
  ],
  "default_params": "params/default.xiparam",
  "ui_manifest": "ui/ui.json"
}

3.2 目录结构

MyPackage.xipkg (ZIP)
├── manifest.json          # 元数据（见 §3.1）
├── signature.bin          # RSA-2048 签名
├── blocks/
│   ├── peq_5band_d1.xo
│   ├── peq_5band_d2.xo
│   └── drc_multi_d1.xo
├── params/
│   └── default.xiparam    # 默认参数快照
├── ui/
│   ├── ui.json            # 面板定义
│   ├── peq.svg
│   └── drc.svg
└── examples/
    └── demo_fx.xiproj     # 示例工程（可选）

3.3 签名覆盖范围

签名对象 = SHA-256（manifest.json 正规化 + 所有 blocks 二进制 + params + ui）。 signature.bin 自身不参与哈希计算（先计算其他所有内容，再生成签名）。

---

4. Python SDK（上位机）

4.1 SDK 概览

from xialgo import Package, Block, Param, Signer

# 1. 读取已有包
pkg = Package.open("XiAlgo-FX-1.0.0.xipkg")
print(pkg.manifest)             # dict
print(pkg.blocks)               # list[Block]

# 2. 提取某个算法块信息
peq = pkg.get_block("PEQ_5band")
print(peq.params_schema)        # list[Param]

# 3. 打开 + 修改默认参数 + 重打包
pkg.set_default_param("peq.band1.freq", 1200.0)
pkg.save_as("XiAlgo-FX-1.0.0-custom.xipkg")

# 4. 签名
signer = Signer.load_key("customer_private.pem")
signer.sign(pkg)
pkg.save_as("XiAlgo-FX-1.0.0-signed.xipkg")

# 5. 验签
pkg2 = Package.open("XiAlgo-FX-1.0.0-signed.xipkg")
print(pkg2.verify("xisound_pubkey.pem"))  # True / False

4.2 SDK 常用 API

类 / 方法	说明
Package.open(path)	打开 .xipkg
Package.new(name, version)	创建空包
pkg.add_block(xo_path, target_dsp)	添加算法块
pkg.remove_block(name)	删除
pkg.set_default_param(id, value)	修改默认参数
pkg.save_as(path)	保存
pkg.verify(pubkey_pem)	验签
Signer.load_key(pem_path)	载私钥
Signer.sign(pkg)	对包签名
Block(xo_path)	读单个 .xo
block.params_schema	参数清单
Param.from_dict(d)	从 JSON dict 构造

4.3 SDK 兼容性

Python SDK	ABI	兼容 XiStudio	Python
v1.0.x	v1.0	v1.0+	3.9+
v1.1.x	v1.0	v1.0+	3.9+
v2.0.x	v2.0	v2.0+	3.10+（破坏性）

---

5. xi-algo-sign CLI

5.1 命令总览

# 签名
xi-algo-sign sign XiAlgo-FX.xipkg \
    --key customer_private.pem \
    --out XiAlgo-FX-signed.xipkg

# 验签
xi-algo-sign verify XiAlgo-FX-signed.xipkg \
    --pubkey xisound_pubkey.pem

# 查看元数据
xi-algo-sign info XiAlgo-FX-signed.xipkg

# 提取算法块
xi-algo-sign extract XiAlgo-FX-signed.xipkg \
    --block PEQ_5band --out peq.xo

# 校验 Manifest Schema
xi-algo-sign lint XiAlgo-FX.xipkg

5.2 退出码

Code	含义
0	成功
1	签名校验失败
2	Manifest 格式错误
3	ABI 不兼容
4	文件 IO 错误
5	密钥错误
99	内部错误

---

6. XiStudio 调用 XiAlgo 流程

6.1 加载时机

graph LR
    Launch[XiStudio 启动] --> Scan[扫描 packages 目录]
    Scan --> Load[逐个加载 .xipkg]
    Load --> Verify[签名校验]
    Verify -- OK --> Parse[解析 manifest]
    Verify -- Fail --> Skip[跳过并警告]
    Parse --> Register[注册块到 Palette]

    class Launch xyL0
    class Scan,Load,Parse xyL2
    class Verify xyWarn
    class Register xySuccess
    class Skip xyError

6.2 编译时机

graph LR
    Proj[xiproj 工程] --> Compile[XiStudio Compile]
    Compile --> Resolve[算法图拓扑解析]
    Resolve --> SelectBlocks[选择对应 target_dsp 的 .xo]
    SelectBlocks --> MipsCheck[MIPS 预算核查]
    MipsCheck -- 超预算 --> Warn[警告 + 用户确认]
    MipsCheck -- OK --> LinkFW[链接到 .xifw 固件]
    LinkFW --> Flash[烧录到 XiDSP]

    class Proj xyL0
    class Compile,Resolve xyL3
    class SelectBlocks xyL2
    class MipsCheck xyWarn
    class LinkFW,Flash xySuccess

---

7. C 调用示例

7.1 Host 加载并运行一个算法块

#include "xi_algo.h"
#include "xi_pkg.h"

int main() {
    /* 1. 打开 .xipkg */
    XiPackage* pkg = xi_pkg_open("XiAlgo-FX.xipkg");
    if (!pkg) return -1;

    /* 2. 验签 */
    if (xi_pkg_verify(pkg, "xisound_pubkey.pem") != XI_OK) {
        xi_pkg_close(pkg);
        return -2;
    }

    /* 3. 找到 PEQ_5band 块 */
    const XiAlgoBlock* blk = xi_pkg_get_block(pkg, "PEQ_5band", "D1");
    if (!blk) { xi_pkg_close(pkg); return -3; }

    /* 4. 分配上下文 */
    XiCtx* ctx = (XiCtx*)xi_mem_pool_alloc(blk->memory_bytes);

    /* 5. 初始化 */
    XiParam init_params[] = {
        { "peq.band1.freq",  XI_PARAM_FLOAT, .value.f = 1000.0f,
          .range.f_range = {20.0f, 20000.0f}, .unit = "Hz", .ramp_ms = 20.0f },
        // ... 其他 14 个参数
    };
    if (blk->init(ctx, init_params) != XI_OK) return -4;

    /* 6. 帧循环（简化示例，只跑 1 帧） */
    float in_buf[48], out_buf[48];
    const float* in[]  = { in_buf };
    float*       out[] = { out_buf };
    blk->process(ctx, in, out, 48);

    /* 7. 销毁 */
    blk->destroy(ctx);
    xi_mem_pool_free(ctx);
    xi_pkg_close(pkg);
    return 0;
}

7.2 动态更新参数

XiParam new_gain = {
    .param_id = "peq.band1.gain",
    .type = XI_PARAM_FLOAT,
    .value.f = 3.0f,
    .ramp_ms = 30.0f,
};
xi_block_set_param(blk, ctx, &new_gain);

---

8. 错误码与调试

8.1 错误码速查

错误码	含义	常见原因
XI_OK	成功	—
XI_ERR_PARAM	参数无效	param 为 NULL / 超范围 / 未知 ID
XI_ERR_NOT_READY	未就绪	init 未完成就 process
XI_ERR_NO_MEM	内存不足	内存池耗尽
XI_ERR_TIMEOUT	超时	process 超 Budget
XI_ERR_ABI_MISMATCH	ABI 版本不匹配	新算法块加载到旧 XiCore
XI_ERR_SIGNATURE	签名失败	.xipkg 未签或被篡改
XI_ERR_INTERNAL	内部错误	Bug · 请联系 FAE

8.2 Trace / Telemetry API

// 启用帧级 Trace（仅开发阶段）
xi_trace_enable(XI_TRACE_LEVEL_DEBUG);

// 查询当前 MIPS 利用率
float mips_util = xi_telemetry_mips_util();

// 查询某个算法块 process 耗时
float us = xi_telemetry_block_latency("PEQ_5band");

---

9. 附录

9.1 完整 Header 清单

头文件	用途
xi_algo.h	核心 ABI（XiAlgoBlock / XiParam / XiStatus）
xi_pkg.h	.xipkg 加载与验签
xi_mem.h	内存池 API
xi_trace.h	Trace / Telemetry
xi_util.h	工具宏

9.2 关联文档

• XiAlgo 产品规格书
• XiAlgo 技术架构
• XiAlgo 用户手册
• XiDSP API 文档
• XiStudio API 文档
• 软件开发规范
• 算法开发规范

9.3 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · C ABI + XiParam + .xipkg + Python SDK + xi-algo-sign CLI

---

api.md · D2-P5-TECH-002 · v1.0 · 2026-05-05 · Xisound 研发中心 · 算法团队 + 工具链团队