API约定¶
本文介绍了 CI-SDK 应用程序编程接口 (API) 中常见的约定和假设。
CI-SDK 提供了几种编程接口：
- 在 CI-SDK 组件的公共头文件中声明的 C 函数、结构体、枚举、类型定义和预处理器宏。软件开发的 API参考 部分描述了这些函数、结构体和类型和使用方法。
1. 命名规则¶
CI14LP 系列 SDK 的接口命名遵循以下约定：
| 前缀/风格 | 所属层 | 说明 |
|---|---|---|
scu_* |
芯片驱动 | 系统时钟、电源、IO 复用（SCU）管理接口 |
gpio_* / uart_* / iic_* / iis_* / spi_* |
芯片驱动 | 外设驱动接口，均为小写下划线风格 |
timer_* / pwm_* / dma_* / flash_* |
芯片驱动 | 定时器、PWM、DMA、FLASH 控制接口 |
madc_* / dcodec_* / avad_* |
芯片驱动 | MIC ADC、内部 CODEC、语音活动检测接口 |
cm_* |
SDK 组件 | 音频系统管理（codec_manager）接口 |
cmd_info_* |
SDK 组件 | 命令词信息表接口 |
prompt_* |
SDK 组件 | 提示音播放器接口 |
cinv_* |
SDK 组件 | NV 数据管理接口 |
ciss_* |
SDK 组件 | 跨核状态共享接口 |
asrtop_* |
算法库 | 语音识别引擎接口（预编译库） |
ci_* |
算法组件 | 语音前端算法（降噪/AEC/DOA 等）接口 |
注意
CI14LP SDK 与 CI13xx 系列 SDK 的系统管理接口命名不同：本 SDK 使用 scu_set_device_clock_en()、scu_set_pad_reuse() 等接口完成外设时钟门控与 IO 复用，不存在 scu_set_device_gate()、dpmu_set_io_reuse() 等旧接口。
2. 通用返回值¶
SDK 通用返回值类型为 ci_retval（定义于 system\ci_system.h）：
| 返回值 | 宏名 | 说明 |
|---|---|---|
| 0 | RETURN_OK / RET_SUCCESS | 操作成功 |
| -1 | PARA_ERROR / RET_INVALIDARGMENT | 参数错误 |
| -2 | RETURN_ERR / RET_FAIL | 操作失败 |
| -3 | RET_MOMEM | 内存不足 |
| -4 | RET_READONLY | 只读错误 |
| -5 | RET_OUTOFRANGE | 参数越界 |
| -6 | RET_TIMEOUT | 超时 |
| INT32_MIN | RET_UNKNOW | 未知错误 |
3. 通用使能参数¶
SDK 中大量接口使用 functional_state_t 类型的 cmd 或 en 参数控制开关：
typedef enum { DISABLE = 0, ENABLE = !DISABLE } functional_state_t;
4. 双核架构说明¶
CI14LP 芯片包含两个处理器核心：
| 核心编号 | 宏名 | 职责 |
|---|---|---|
| 0 | NPU_CORE | 主核，运行 FreeRTOS、ASR 引擎、播放器等主要业务 |
| 1 | AON_CORE | 常开核，负责低功耗状态机、AVAD 唤醒检测、看门狗喂狗 |
5. 头文件引用路径¶
- 芯片外设驱动头文件：
driver\ci14lp_chip_driver\inc\ - 组件头文件：
components\<组件名>\ - 系统级头文件：
system\ - 工程配置头文件：
projects\offline_asr_sample\src\user_config.h、system\sdk_default_config.h、driver\boards\<板级配置文件>.h