6 Platform API 参考
6.1 platform_32k_rc_auto_tune
自动调谐内部的 32k RC 时钟，得到调谐参数。
6.1.2 参数表
无。
6.1.3 返回值
16 比特调谐参数。
6.1.4 备注
本操作需要花费 ~250ms。建议只调用一次本函数，记录调谐参数以备使用。
6.2 platform_32k_rc_tune
使用给定参数调谐内部的 32k RC 时钟。
6.2.2 参数表
uint16_t value调谐参数 (从
platform_32k_rc_auto_tune得到)
6.2.3 返回值
无。
6.2.4 备注
void.
6.3 platform_config
配置平台功能。
6.3.2 参数表
const platform_cfg_item_t item指定要配置的项。可以是下列值：
PLATFORM_CFG_LOG_HCI: HCI 消息的 printf 打印。默认值：关闭。PLATFORM_CFG_POWER_SAVING: 省电功能。默认值：关闭。PLATFORM_CFG_TRACE_MASK: Trace 数据项的比特图。默认值：0。PLATFORM_CFG_RC32K_EN: 使能/禁用内部 32k RC 时钟。默认值：使能。PLATFORM_CFG_OSC32K_EN: 使能/禁用外部 32k 晶体。默认值：使能。PLATFORM_CFG_32K_CLK: 32k 时钟源选择。参数为platform_32k_clk_src_t类型。默认值：PLATFORM_32K_RCtypedef enum { PLATFORM_32K_OSC, // 外部 32k 晶体 PLATFORM_32K_RC // 内部 32k RC 时钟 } platform_32k_clk_src_t;当修改本配置时，RC32K 和 OSC32K 必须同时处理使能、运行状态：
- 对于 OSC32K，等待直到 OSC32K 的状态变为 OK；
- 对于 RC32K，使能后等待 100us。
提示：在关闭不用的时钟前再等待 100us。
PLATFORM_CFG_32K_CLK_ACC: 声明 32k 时钟的精度（ppm）。PLATFORM_CFG_32K_CALI_PERIOD: 32k 时钟的校准间隔（秒）。默认值：3600 * 2 (2 小时)。PLATFORM_CFG_DEEP_SLEEP_TIME_REDUCTION: 睡眠时间预留量（深睡眠模式）（微秒）。默认值：~550us。PLATFORM_CFG_SLEEP_TIME_REDUCTION: 睡眠时间预留量（其它睡眠模式）（微秒）。默认值： ~450us.PLATFORM_CFG_LL_DBG_FLAGS: 链路层标志位，是ll_cfg_flag_t中各比特的组合。PLATFORM_CFG_LL_LEGACY_ADV_INTERVAL: 链路层 legacy 广播内部间隔（微秒），其中高 16 比特用于高频度广播 （high duty cycle），低 16 比特用于正常频度广播（normal duty cycle）。高频度广播的默认值：1250， 正常频度的默认值：1500。
const uint32_t flag对于可以使能、禁用的配置，用下面的值进行控制：
PLATFORM_CFG_ENABLEPLATFORM_CFG_DISABLE
6.3.3 返回值
无。
6.3.4 备注
无。
6.4 platform_get_heap_status
得到堆当前的状态信息，如剩余空间等。
6.4.2 参数表
platform_heap_status_t *status堆的状态。
6.4.3 返回值
无。
6.4.4 备注
堆的状态定义如下：
6.5 platform_get_us_time
读取内部计时器的时间。该计时器从 BLE 初始化之后开始计时。
6.5.2 参数表
无。
6.5.3 返回值
内部计时器的微秒计数值。
6.5.4 备注
关机后该计时器会归零，而 RTC 计时器则不会。
6.6 platform_get_version
得到 platform 的版本号。
6.6.2 参数表
无。
6.6.3 返回值
指向 platform_ver_t 的指针。
6.6.4 备注
Platform 版本号包含 3 个部分，major，minor 和 patch：
6.7 platform_hrng
使用硬件真随机数发生器产生任意长度的随机数。
6.7.2 参数表
uint8_t *bytes随机数输出。
const uint32_t len要产生的字节数。
6.7.3 返回值
无。
6.7.4 备注
产生一定长度的随机数所需要的时间是不确定的。
6.8 platform_install_isr_stack
为中断服务程序安装新的栈。
6.8.2 参数表
void *top新栈的栈顶，必须为 4 字节对齐。
6.8.3 返回值
无。
6.8.4 备注
当 app 需要使用比默认 ISR 栈更大的栈时，可以使用这个 API 安装一个新的栈，替换掉旧的。
这个函数只允许在 app_main 里调用。新栈在 app_main 函数返回后启用。
6.9 platform_printf
Platform 内部的 printf 函数。
6.9.2 参数表
const char *format格式字符串。
...变长参数。
6.9.3 返回值
无。
6.9.4 备注
使用这个函数既有优点也有缺点：
优点：
- 这个函数位于 platform 内部，可以节省 app 程序空间
缺点：
- 输出被定向到
PLATFORM_CB_EVT_PUTC事件，所以必须为该事件设立回调。
6.10 platform_raise_assertion
抛出软件断言。
6.10.2 参数表
const char *file_name断言发生的文件名。
int line_no断言发生的代码行。
6.10.3 返回值
无。
6.10.4 备注
无。
6.11 platform_rand
使用 platform 内的伪随机数发生器（PRNG）生成伪随机整数。
6.11.2 参数表
无。
6.11.3 返回值
一个在 0 和 RAND_MAX 之间均匀分布的随机数。
6.11.4 备注
上电时用硬件随机数发生数发生器为 PRNG 生成了种子。
6.12 platform_read_info
读取 platform 信息。
6.12.2 参数表
const platform_info_item_t item信息项：
6.12.3 返回值
信息项的值。
6.12.4 备注
无。
6.13 platform_read_persistent_reg
读取持久化寄存器的值。参考
platform_write_persistent_reg。
6.13.2 参数表
无。
6.13.3 返回值
用 platform_write_persistent_reg 写入的 4 个比特。
6.13.4 备注
无。
6.14 platform_reset
复位整个系统（SoC）。
6.14.2 参数表
无。
6.14.3 返回值
无。
6.14.4 备注
在这个函数之后的代码不会被执行。
6.15 platform_set_evt_callback
为 platform 事件设置回调函数。
6.15.1 原型
6.15.2 参数表
platform_evt_callback_type_t type事件的类型。可以是下列值：
PLATFORM_CB_EVT_PUTC: ASCII 字符输出事件当 platform 要输出字符串日志时会触发该事件。传递到回调函数的参数
void *data是从char *转换得来。用
ingWizard创建新项目时，如果在Common Function页面选择了Print to UART， 会自动生成相关代码。PLATFORM_CB_EVT_PROFILE_INIT: BLE GATT profile 初始化事件当 Host 初始化时会触发该事件要求 app 初始化 GATT profile。
用
ingWizard创建新项目时，会自动生成相关代码。PLATFORM_CB_EVT_ON_DEEP_SLEEP_WAKEUP: 深睡眠唤醒事件深睡眠中唤醒时触发该事件。在深睡眠时，外部接口（如 UART,，I2C 等）都已掉电，所以当唤醒时， 可能需要再次初始化。
用
ingWizard创建新项目时，如果在Common Function页面选择了Deep Sleep， 会自动生成相关代码。PLATFORM_CB_EVT_QUERY_DEEP_SLEEP_ALLOWED: 深睡眠许可查询事件当 platform 准备进入深睡眠时，会触发该事件询问 app 当前是否允许进入深睡眠。 事件回调函数可通过返回
0拒绝，返回非0允许。用
ingWizard创建新项目时，如果在Common Function页面选择了Deep Sleep， 会自动生成相关代码。PLATFORM_CB_EVT_HARD_FAULT: Hard fault 事件Hard fault 发生时触发该事件。传入回调函数的
void *data参数是从hard_fault_info_t *转换得来。 如果未定义该回调，当事件发生时，CPU 进入死循环。PLATFORM_CB_EVT_ASSERTION: Software assertion fails软件断言失败时触发该事件。传入回调函数的
void *data参数是从assertion_info_t *转换得来。 如果未定义该回调，当事件发生时，CPU 进入死循环。PLATFORM_CB_EVT_LLE_INIT: 链路层引擎初始化完成事件每当链路层引擎初始化完成时触发该事件。
PLATFORM_CB_EVT_HEAP_OOM: 堆空间用完事件在堆上分配内存失败时触发该事件。 如果未定义该回调，当事件发生时，CPU 进入死循环。
PLATFORM_CB_EVT_TRACE: Trace 输出事件当有 trace 数据项要输出时，触发该事件。 Apps 可以为该事件设置回调函数以保存或者输出 trace 数据。传人回调函数的
void *data参数是从platform_trace_evt_t *转换得来（参见 Debugging & Tracing）。typedef struct { const void *data1; const void *data2; uint16_t len1; uint16_t len2; } platform_evt_trace_t;一个 trace 数据项由
data1和data2组成。说明：len1或者len2可能为0，但不会同时为0；如果回调函数发现无法存储或者输出长度为
len1+len2的数据，那么应该同时丢弃data1和data2以防 trace 数据结构混乱。
f_platform_evt_cb f注册到事件
type的回调函数。f_platform_evt_cb的类型为：void *user_data这个参数将原封不动地作为
user_data传递给回调函数。
6.15.3 返回值
无。
6.15.4 备注
并不要求给所有事件都设置回调函数。
如果未给 PLATFORM_CB_EVT_PUTC 事件设置回调，所有用平台 printf 日志都会丢弃。
如果未给PLATFORM_CB_EVT_PROFILE_INIT 事件设置回调，BLE profile 为空。
如果未给 PLATFORM_CB_EVT_ON_DEEP_SLEEP_WAKEUP 事件设置回调，从深睡眠唤醒时 app 无法获得通知。
如果未给 PLATFORM_CB_EVT_QUERY_DEEP_SLEEP_ALLOWED 事件设置回调，深睡眠模式为 禁用 状态。
6.16 platform_set_irq_callback
为中断请求设置回调函数。
开发者不需要定义 IRQ 处理函数，而是通过设置回调实现。两种芯片系列的中断请求总结于表 6.1 和表 6.2。
| 外设类型 | 数量 | 备注 |
|---|---|---|
| RTC | 1 | Real Time Clock |
| TIMER | 3 | Timer |
| GPIO | 1 | General Purpose Input/Output |
| SPI | 2 | Serial Peripheral Interface |
| UART | 2 | Universal Asynchronous Receiver-Transmitter |
| I2C | 2 | Inter-Integrated Circuit |
| 外设类型 | 数量 | 备注 |
|---|---|---|
| RTC | 1 | Real Time Clock |
| GPIO | 2 | General Purpose Input/Output |
| TIMER | 3 | Timer |
| WDT | 1 | Watch dog |
| PDM | 1 | Pulse Density Modulation |
| APBSPI | 1 | Serial Peripheral Interface on APB |
| QSPI | 1 | Quad serial peripheral interface |
| I2S | 1 | Inter-IC Sound |
| UART | 2 | Universal Asynchronous Receiver-Transmitter |
| I2C | 2 | Inter-Integrated Circuit |
| DMA | 1 | Direct Memory Access |
| KEYSCAN | 1 | Key Scanner |
| PWM | 1 | Pulse Width Modulation |
| IR INT | 1 | Infrared Interrupt |
| IR WAKEUP | 1 | Infrared Wake-up Interrupt |
| USB | 1 | Universal Serial Bus |
6.16.1 原型
6.16.2 参数表
platform_irq_callback_type_t type中断类型。
对于 ING918xx，中断类型如下：
对于 ING916xx，中断类型如下：
PLATFORM_CB_IRQ_RTC, PLATFORM_CB_IRQ_GPIO0, PLATFORM_CB_IRQ_GPIO1, PLATFORM_CB_IRQ_TIMER0, PLATFORM_CB_IRQ_TIMER1, PLATFORM_CB_IRQ_TIMER2, PLATFORM_CB_IRQ_WDT, PLATFORM_CB_IRQ_PDM, PLATFORM_CB_IRQ_APBSPI, PLATFORM_CB_IRQ_QSPI, PLATFORM_CB_IRQ_SADC, PLATFORM_CB_IRQ_I2S, PLATFORM_CB_IRQ_UART0, PLATFORM_CB_IRQ_UART1, PLATFORM_CB_IRQ_I2C0, PLATFORM_CB_IRQ_I2C1, PLATFORM_CB_IRQ_DMA, PLATFORM_CB_IRQ_KEYSCAN, PLATFORM_CB_IRQ_PWM, PLATFORM_CB_IRQ_IR_INT, PLATFORM_CB_IRQ_IR_WAKEUP, PLATFORM_CB_IRQ_IR_USB,
f_platform_irq_cb f注册到中断
type的回调函数。f_platform_irq_cb的类型为：void *user_data这个参数将原封不动地作为
user_data传递给回调函数。
6.16.3 返回值
无。
6.16.4 备注
当为中断配置了回调函数后，对应的 IRQ 自动使能。
6.17 platform_shutdown
将整个系统（SoC）置于关机状态，并在一段指定时间后重新启动。可选地， 可以指定保持一段内存，重启之后，app 可继续使用其中的数据。
需要注意这个函数不会返回，除非无法进入关机状态。可能导致无法进入关机状态的原因有：
- 外部唤醒信号有效；
- 输入参数有误；
- 内部设备正忙。
6.17.1 原型
6.17.2 参数表
const uint32_t duration_cycles关机状态的持续时间（以 32k 时钟周期数表示），超时后重启。 最小时间为 825 个周期（大约 25.18ms）。如果该参数为
0，则系统将一直保持关机状态，直到出现外部唤醒信号。const void *p_retention_data指向需要保持的内存数据的地址。只有 SYSTEM 内存区域允许保持（ING918xx）。 当
data_size为0时，该参考可以为NULL。data_size需要保持的内存数据的长度。如果不需要保存数据，将此参数设为
0。
6.17.3 返回值
无。
6.17.4 备注
无。
6.18 platform_switch_app
切换到辅 app。
6.18.2 参数表
const uint32_t app_addr辅 app 的入口地址。
6.18.3 返回值
无。
6.18.4 备注
本函数之后的代码不会被执行。
6.19 platform_write_persistent_reg
将值写入持久化寄存器。这个值在省电、关机、辅app切换等过程或者状态下都保持不变。
6.19.2 参数表
const uint8_t value值。
6.19.3 返回值
无。
6.19.4 备注
只会保存 4 个比特。
6.20 sysSetPublicDeviceAddr
设置设备的公共地址（public address）.
BLE 设备的公共地址是 48 比特的唯一标识（EUI-48），遵照 IEEE 802-2014 standard19 创建。
6.20.2 参数表
const unsigned char *addr新的公共地址。
6.20.3 返回值
无。
6.20.4 备注
为了避免产生问题，本函数应该先于任何 GAP 函数调用。建议在 app_main 或者 PLATFORM_CB_EVT_PROFILE_INIT
事件的回调里使用。