TXW81x SDK快速入门手册

责任与版权

责任限制

由于产品版本升级或者其他原因，本文档会不定期更新。除非另行约定，泰芯半导体有限公司对本文档所有内容不提供任何担保或授权。

客户应在遵守法律、法规和安全要求的前提下进行产品设计，并做充分验证。泰芯半导体有限公司对应用帮助或客户产品设计不承担任何义务。客户应对其使用泰芯半导体有限公司的产品和应用自行负责。

在适用法律允许的范围内，泰芯半导体有限公司在任何情况下，都不对因使用本文档相关内容及本文档描述的产品而产生的损失和损害进行超过购买支付价款的赔偿（除在涉及人身伤害的情况中根据适用的法律规定的损害赔偿外）。

版权申明

泰芯半导体有限公司保留随时修改本文档中任何信息的权利，无需提前通知且不承担任何责任。

未经泰芯半导体有限公司书面同意，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。除非获得相关权利人的许可，否则，任何人不能以任何形式对前述软件进行复制、分发、修改、摘录、反编译、反汇编、解密、反向工程、出租、转让、分许可等侵犯本文档描述的享有版权的软件版权的行为，但是适用法禁止此类限制的除外。

修订记录

1. 概述

本文为使用方案软件设计开发人员而写，目的帮助您快速入门SDK。

本文档主要适用于以下工程师：

• 技术支持工程师
• 方案软件开发工程师

本文档适用的产品范围：

2. 集成开发环境

2.1. CKLink调试器

CKLink Lite是TXW81x芯片/模组的SDK的调试工具，可以在平头哥的淘宝官方店购买。

图2.1.1 - 调试器

2.2. CDK开发环境

CDK是平头哥CPU的集成开发环境，可以从平头哥官方网站进行下载安装。本SDK基于CDK v2.8.8版本研发，建议使用此版本或者更高版本进行开发。

如果下载不了请联系我司FAE。

2.3. 编译和调试

2.3.1. 编译

CDK安装好后，到SDK project路径下双击打开工程 *.cdkproj，在CDK菜单点击编译或者快捷键F7执行编译。

2.3.2. 调试

调试时建议设置设置ICE Clock 120Khz，并且勾选reset after connect,使用softreset。断点调试时请关闭代码中的看门狗。具体操作步骤如下（如图2.3.2.1所示）：

1. 进入project setting / debug，选中Use ICE；
2. 进入setting，如果调试板可以正确被连上，在Connected Debug Target框里就可以读到Target chip Info；
3. 设置ICE Clock为120Khz（如果需要调试器设置频率更高，请参考FAQ），然后点击OK保存。

设置好后，将CKLink的调试线连到板子的调试口，点击CDK的调试按钮或CTRL+F5，CDK会启动调试。

图2.3.2.1 - 调试设置

2.3.3. 中途插入调试

有时候需要中途插入调试器进行调试。此时不能按照普通的调试方式进行操作（会复位，破坏现场）。需要如下配置SDK，然后再插入调试器调试：

1. 在Project Settings窗口中（可以使用ALT+F7快捷键打开），取消“Load Application to Target”的勾选。

1. 继续在Project Settings窗口中，点击ICE左边的Settings，在弹出的ICE Configuration窗口中，勾上“Download to Flash”，去除“Reset After Connect”的勾选状态。另外可以根据系统时钟的频率，设置一下ICE Clock的值（只要不高于1/2系统时钟即可）。最后按OK退出窗口。

1. 回到Project Settings窗口，点击Init File最右边的放大镜图案，修改gdb.init内容。此时可以按OK，退出Project Settings窗口。

1. 根据实际修改gdb.init。如果要调试的程序没有开看门狗，则可以将gdb.init里面的内容全部删除；如果开了看门狗，则gdb.init需要留下如下2条语句。

上述步骤完成后，可以插入调试器，点击进入调试模式。

2.4. 固件烧录

2.4.1. CDK下载代码

CDK代码编译成功后可以通过菜单“Flash”->“Download”进行下载，此方式下载会保留非代码区的的配置信息；如果需求清除配置信息，可以选择“Chip Erase”方式进行下载。

2.4.2. CKLink烧写

烧录工具为：CSKY-FlashProgrammer-windows，平头哥官方网站进行下载安装。建议使用V1.0.14及以上版本。具体烧写步骤为：

1. 执行CSKYFlashProgrammer.exe
2. 在advance TargetConfig中设置Program Algorithm File和Script
3. 根据需要勾选是否下载完立即运行代码
4. 在advance LocalJTAG中设置ICE CLK：12Mhz
5. 回到主界面添加下载文件并点击start按钮下载。

2.4.3. UART烧写

SDK集成了串口升级功能，如果已经打开，可以通过串口命令“TX+OTA”进行升级。具体方法请咨询我司FAE。

2.4.4. 量产烧录

量产烧录详见《TXW81x 量产和烧录指南.pdf》

3. 硬件开发板

为了快速入门和方案评估，我们提供各种应用场景的开发板。

3.1. 音视频开发板

3.1.1. 音视频开发板接口介绍

图3.1.1.1 - 音视频开发板主视图

特殊说明

模式启动按键：此按键可以一键拯救系统，在芯片上电即跑死，cklink烧写和其他升级都失效的情况下使用。注意按此按键时不能连接Debug接口。

LCD接口：此接口支持LCD子板，支持MCU（8080、6800）、RGB、SPI接口屏，用户可以使用配套的屏（默认MCU屏320*240，具体型号和参数可以扫描二维码获取）或者自行设计屏子板进行开发。

主控核心板：主控核心板采样标准pcie接口；默认配置了主控芯片TXW818-C0xL;具体型号和参数可以扫描二维码获取；

3.2. 网桥开发板

3.3. 无线网卡开发板

4. SDK概述

4.1. SDK Feature

• • 应用场景
    • VGA/720P 耳镜、航拍
    • miniDV
    • 可视门铃
    • Wi-Fi触控家电
  • 操作系统
    • AliOS
  • 工作角色
    • AP
    • STA
  • 网络协议栈
    • LWIP
    • MQTT
    • HTTP
  • 文件系统
    • (ex)FAT
  • 抽象数据总线
    • USB device、SDIO device、SPI salve、UART、I2C
  • 抽象外设
    • GPIO、ADC、DMA、DVP、MJPEG、IIS、PDM、USB、SDIO 、SPI、UART、I2C、LED、PWM、UART、WDT、TIMER、TOUCH、AES、CRC

4.2. SDK 框架图

SDK基本框架如下图所示，SDK定义了OSAL和 HAL 2个抽象层；OSAL抽象层定义了与OS相关操作的API，HAL定义了硬件设备访问API。

在使用SDK进行二次开发代码时，涉及到与OSAL和HAL相关的API调用时，请使用OSAL和HAL提供的API。

4.3. 目录结构

TXW81x SDK解压后的目录结构如下图所示。

• • csky：CSKY RTOS代码目录，通常不需要修改该部分代码。
  • project：CDK工程应用代码目录，main.c位于该目录。
  • sdk/chip：芯片定义及启动代码目录
  • sdk/driver：外设驱动代码目录
  • include：SDK头文件目录
  • lib：常用library，包括lwip协议栈，以太网PHY驱动等。用户自行移植的代码库可以放在此目录下。

4.4. SDK启动流程

SDK的启动代码在sdk/chip/txw81x目录下，大致的启动流程如下图所示，其中 device_init 和 main 函数可以进行相应修改，其它启动流程代码请勿修改。

• • device_init 函数：系统设备初始化函数，完成了驱动初始化和设备注册；所有设备只有注册后才可以使用。在该函数中可以删除未使用的设备的初始化代码，以减少代码体积。
  • main 函数：应用程序入口函数。

Reset_Handler

pre_main

main_task()

dev_init()

device_init()

main()

SystemInit

sdk/chip/txw81x/startup.S

sdk/chip/txw81x/system.c

sdk/lib/common/dev.c

project/device.c

project/main.c

4.5. 系统参数

SDK的系统参数定义在project/sys_cfg.h文件中，如下所示：

其中前面12个byte：magic_num，crc，size是核心字段，不能修改，应用代码也不能使用这些字段；rev1,rev2,rev3是SDK预留扩展字段，不建议使用。系统参数在project/sys_cfg.c中配置示例如下：

• wifi_mode：字段是Wi-Fi工作模式，支持STA、AP、AP+STA。
• channel：2.4G channel选择，0表示自动选择，非0则强制channel（STA不能强制channel）。
• beacon_int：beacon interval (ms)。
• dtim_period：dtim interval (beacon个数)。
• bss_max_idle：bss 范围内最大的不活动时间, AP会超时后查询STA是否还在。
• key_mgmt：加密模式选择
• Ipaddr：IP地址
• Netmask：网络掩码
• gw_ip：网关
• dhcpd_startip：DHCP服务器分配IP地址范围的开始
• dhcpd_endip：DHCP服务器分配IP地址范围的结束
• dhcpd_lease_time：DHCP IP租赁时间
  dhcpd_en：DHCP服务器使能
• dhcpc_en：DHCP客户端使能
• 参数区存储位置：参数区存储位置的指定在device.c里面的syscfg_info_get函数，该函数指定了每个参数区所在的flash设备，参数区的地址及大小。SDK默认使用了Flash最后2个sector（2个参数区所占用的sector不能重叠）。

• 参数API：

参数读取/存储的API定义在sdk/include/lib/syscfg.h文件中。SDK定义了全局变量sys_cfgs，该变量作为整个SDK参数的引用，可以在其它模块直接访问该变量。

其中：

• • • syscfg_init：syscfg模块初始化，并加载flash参数。该函数通常在main函数启动时执行，并读取flash参数。
    • syscfg_read：读取参数。会从2个参数区中选择有效的参数区进行读取。
    • syscfg_write：保存参数，交替使用2个参数区。
    • syscfg_info_get：指定参数区的存储位置信息。在device.c中根据实际flash信息进行指定。
    • syscfg_loaddef：参数区load default，会设置2个参数区都为无效区。

系统时钟SDK默认配置为DEFAULT_SYS_CLK = 180Mhz，方案需要修改系统时钟时需要重写函数：system_clock_init，system_clock_init源码如下：

#define DEFAULT_SYS_CLK 180000000UL

__weak void system_clock_init(void)

{

if (!sysctrl_cmu_sysclk_set(DEFAULT_SYS_CLK, 0)) {

while (1);

}

}

4.6. FLASH布局

SDK设计了双固件区和双参数区，其中2个固件区地址固定为0和512KB/1MB的位置。参数区默认使用flash最后2个sector，大小为1个sector。

默认Flash分区如下：

/1MB

参数区可以根据实际情况进行调整。

4.7. Memory布局

TXW81x芯片的SRAM Size为288KByte，整体分布如下：

• dsleep参数区：最前面为Deep Sleep功能参数区。
• text/data：程序的代码段和data段。
• heap：程序可使用的heap区间。heap区间大小可根据实际应用需求进行设定。
• WiFi rx buffer：Wi-Fi rx buffer区间
• WiFi tx buffer：Wi-Fi tx buffer区间

可以根据tx/rx数据量的大小来调整Wi-Fi tx/rx buffer的大小。例如实际通信tx数据多，rx数据少，则可以调大tx buffer，减少rx buffer。

以上各个buffer区间的设置在sys_config.h中进行定义。

Heap默认size

Wi-Fi rx buffer size

Heap buffer地址

Wi-Fi tx buffer地址

Wi-Fi rx buffer地址

4.8. 方案开发基本规则

方案开发需要遵循的一些基本准则，包括头文件引用、内存分配、延时、打印和数据格式转换等；另外方案开发常见配置主要看project_config.h 和 sys_config.h，里面包含了系统参数、存储空间、外设功能和参数等配置。

• • 头文件引用

使用SDK进行二次开发代码时，头文件引用请使用SDK定义的头文件。头文件引用基本顺序如下图所示。

typesdef.h是基础类型头文件，所有源码文件只引用该头文件即可，不要直接引用编译器的头文件。

list.h，dev.h，devid.h 是设备访问基础头文件

设备HAL api在include/hal目录，根据实际访问的设备，添加引用对应的头文件。

osal/string.h，osal/semaphore.h，osal/xxx 是OSAL API，头文件在 include/osal目录。需要使用这类API时，引用 osal/xxx.h 即可。

library 头文件

HAL层头文件

sleep操作，软件timer API头文件

中断注册，任务创建头文件

semaphore，mutex API头文件

string类操作API

设备访问基础头文件

SDK基础类型定义头文件

• • 常用API

调试打印

• • • os_printf： 带时间戳的打印API
    • dump_hex： 以十六进制格式打印数据

内存分配

• • • os_malloc： 申请内存
    • os_free： 释放内存
    • os_zalloc： 申请内存，并清理
    • os_realloc： 申请内存，复制原内存的数据，释放原内存空间

Sleep函数

• • • os_sleep： task sleep API，单位秒
    • os_sleep_ms：task sleep API，单位毫秒

格式转换

• • • hex2int： 十六进制字符串转换成int类型数据
    • hex2char： 十六进制字符串转换成char类型数据
    • hex2bin： 十六进制字符串转换成char数组
    • str2mac： MAC地址字符串转换成char数组

4.9. 驱动API使用说明

SDK设计了硬件抽象层HAL，应用程序访问外设请使用HAL API。HAL api会执行具体driver的API。

应用程序访问外设基本步骤：

1. 获取需要访问的device：使用dev_get API获取需要访问的外设device。该API通过指定的device id获取已经初始化的device。device id定义在include/devid.h文件中。
2. 使用HAL API访问device。

基本示例如下：

watchdog device id id

get device

HAL API

4.10. OSAL API使用说明

SDK设计了OS抽象层，提供了常用的semaphore/mutex/timer/irq/msg queue/task等功能的OSAL API，代码开发时请使用OSAL提供的API。

4.10.1. Task

Task OSAL API定义在 include/osal/task.h文件中。

• • OS_TASK_INIT

该宏定义执行了task的初始化，堆栈大小/优先级设置，并启动运行task。使用该宏定义可以简化task创建。

具体示例可以参考watchdog task：

Task stack size

task priority

task data

task function

task object

task name

• • os_task_init：task初始化

int32 os_task_init(const uint8 *name, struct os_task *task, os_task_func_t func, uint32 data)

参数：

• • • name：task名称
    • task：具体task对象
    • func：task需要执行的function
    • data：执行function需要的参数

返回值：

• • • RET_OK： 初始化成功
    • RET_ERR：初始化失败
  • os_task_priority：查看task的优先级

int32 os_task_priority(struct os_task *task)

参数：

• • • task：需要查看的task对象

返回值：

• • • task的优先级
  • os_task_stacksize：查看task的stack size

int32 os_task_stacksize(struct os_task *task)

参数：

• • • task：需要查看的task对象

返回值：

• • • task的堆栈size
  • os_task_set_priority：设置task的优先级（task运行之前设置有效）。

int32 os_task_set_priority(struct os_task *task, uint8 priority)

参数：

• • • task： 需要设置的task对象
    • priority： task的优先级。优先级定义：OS_TASK_PRIORITY

返回值：

• • • RET_OK： 设置成功
    • RET_ERR： 设置失败
  • os_task_set_stacksize：设置task的堆栈size（task运行之前设置有效）。

int32 os_task_set_stacksize(struct os_task *task, int32 stack_size)

参数：

• • • task： 需要设置的task对象
    • stack_size： task的堆栈size

返回值：

• • • RET_OK： 设置成功
    • RET_ERR： 设置失败
  • os_task_run：启动运行task

int32 os_task_run(struct os_task *task)

参数：

• • • task：需要启动运行的task对象

返回值：

• • • RET_OK：task启动运行成功（不代表task立即被执行）。
    • RET_ERR：task启动运行失败。

4.10.2. Mutex

Mutex功能OSAL API定义在 include/osal/mutex.h，如下图所示：

超时时间，单位：毫秒

4.10.3. Semaphore

Semaphore功能OSAL API定义在 include/osal/semaphore.h

wait forever 宏定义

超时时间，单位：毫秒

sema初始值，通常为0

include/osal/semaphore.h

4.10.4. Msgqueue

Message Queue功能OSAL API定义在include/osal/msgqueue.h文件中。Mesasge queue存储的是uint32类型数据。

wait forever

超时时间，单位毫秒

超时时间，单位毫秒

msg queue的size

include/osal/msgqueue.h

• • os_msgq_init：消息队列初始化，指定队列大小。

int32 os_msgq_init(struct os_msgqueue *msgq, int32 size);

参数：

• • • msgq： 需要初始化的msg queue
    • size： 指定msg queue的size。初始化时会从heap申请 size*sizoef(uint32) 大小的memory空间。

返回值：

• • • RET_OK： 初始化成功
    • RET_ERR： 初始化失败
  • os_msgq_get：从msg queue提取数据，可指定超时时间

uint32 os_msgq_get(struct os_msgqueue *msgq, int32 tmo_ms);

参数：

• • • msgq： 需要提取数据的msg queue
    • tmo_ms： get操作超时时间，单位毫秒；或者永久等待：osWaitForever

返回值：

• • • 从msg queue提供的数据
  • os_msgq_put：向msg queue中存入数据

int32 os_msgq_put(struct os_msgqueue *msgq, uint32 data, int32 tmo_ms);

参数：

• • • msgq：需要存入数据的msg queue
    • data：需要存入的数据
    • tmo_ms：put操作超时时间，单位毫秒；或者永久等待：osWaitForever

返回值：

• • • RET_OK：数据成功存入msg queue
    • 其它值：存入失败。
  • os_msgq_del：删除msg queue

int32 os_msgq_del(struct os_msgqueue *msgq);

• • os_msgq_cnt：查看当前msg queue中存储的数据个数。

int32 os_msgq_cnt(struct os_msgqueue *msgq);

4.10.5. SoftTimer

Soft Timer的OSAL API定义在osal/timer.h文件中。

Soft timer是基于OS tick运行的，所以timer的时间精度就是os tick，SDK默认OS Tick是1ms。

使用soft timer的注意事项：

1. 尽量缩短timer的callback函数执行时间。所有的soft timer共用1个执行序列，某个timer执行时间过长会影响其它timer的执行。
2. soft timer有2种工作模式：
   • ONCE：timer启动触发后，需要再次启动才会运行。
   • PERIODIC：timer只需要启动一次，会根据指定的超时时间循环周期性触发。

4.11. 调试信息

SDK提供了基本的调试手段，用于开发过程中的问题排查。

4.11.1. WiFi协议栈调试信息输出

WiFi协议栈底层调试信息，主要是用于分析无线传输问题分析。在无线传输遇到问题，请抓取该打印信息进行分析。

WiFi协议栈调试信息

部分打印信息的含义如下：

local：当前MAC地址。

chip-temperature：当前芯片温度。

freq：当前工作频点。

bg_rssi：最近一次的背景噪声，单位是dB。

tx：从上一次打印到现在的tx统计信息。其中tx dma代表总共dma的帧数；total tx代表已经发送完成的帧数；retry代表空口重传的次数；tx lost代表发送失败的帧数；tx err代表发送出错的次数。

rx：从上一次打印到现在的rx统计信息。rx irq代表进入rx接收帧中断的次数。

rx err：从上一次打印到现在的rx接收出错的统计信息。由于2.4G干扰多且复杂，会出现大量的rx err。

sta：代表已连接sta的信息。aid是sta的aid信息；rssi代表最近一次sta的信号强度；evm代表最近一次接收帧的信号质量（越小越好），只有接收OFDM调制方式的帧才会更新；tx frm type和tx mcs用于代表最近一次我们往sta发送的帧格式；freq offset代表我们探知到的最近一次sta频偏信息。

注意：可以通过AT命令（AT+PRINT_PERIOD=__）设置该打印的时间，单位是ms。时间设置为0时，则关闭打印。

4.11.2. 系统Heap使用情况

调用sysheap_status()可以打印系统Heap使用情况，该打印信息会输出当前heap剩余情况。可以根据该打印信息调整heap size，使用heap size保持够用即可，使tx/rx buffer可以使用更多的memory。

系统heap使用情况：heap size：40K

还剩余15260bytes，分为2个内存片

4.11.3. CPU 使用率

调用cpu_loading_print()可以打印CPU使用率，该打印信息显示了各个Task的CPU使用情况。从该信息可以分析代码运行是否存在异常。

各个Task的CPU使用率

4.11.4. XIP取指效率

对于跑XIP应用的方案，需要关心代码取指效率，这个主要受SPI FLASH读模式、频率以及Cache命中率影响。其中SPI FLASH读模式、频率在工程makecode.ini中配置；Cache命中率 = 1 - cpfmtr/cpfatr。其中Cache丢失（cpfmtr）和命中(cpfatr)次数可以通过函数csi_cache_get_miss_time() 和csi_cache_get_access_time()获取, 当需要统一某段时间内的cache命中率时，建议统计前调用csi_cache_reset_profile()清除历史数据。

当方案代码运行吃力时可以考虑以下优化方向：

1. 提高SPI FLASH访问效率（提高线模式、提高频率等）
2. 优化代码提高Cache命中率（加强代码时间和空间局部性）
3. 优化代码自身执行效率

5. 其他学习资源

【TXW81x 技术规格书】

该⼿册介绍了TXW81x芯片，包含TXW81x产品概述（特性、功能框图、管脚定义和布局、管脚功能）、功能描述（CPU、存储和闪存、时钟、模拟和数字外设等）、电气参数（工作条件、直流和交流特性、功耗、可靠性、射频性能等）等信息。

【TXW81x 硬件设计指南】

该⼿册介绍了TXW81x硬件设计，包含TXW81x主要电源、射频和高速模块设计和layout指南和注意事项、原理图等。

【TXW81x SDK API参考手册】

该⼿册介绍了TXW81x SDK抽象层API。

【TXW81x FAQ】

该⼿册介绍了TXW81x方案开发过程中的疑难答疑。

【TXW81x 视频开发指南】

该⼿册介绍了TXW81x视频方案开发，包括DVP/MJPEG/USB配置、DVP镜头驱动、USB Sensor驱动、以及视频和图片数据流。

【TXW81x USB开发指南】

该⼿册介绍了TXW81x USB方案开发，包括USB Host和USB device初始化和工作流程等。

【TXW81x 蓝牙配网开发指南】

该⼿册介绍了TXW81x蓝牙配网开发。

【TXW81x 音频开发指南】

该⼿册介绍了TXW81x音频方案开发, 包括音频子板介绍、PDM/IIS音频接口使用和音频数据流等。

【TXW81x IOT开发指南】

该⼿册介绍了TXW81x IOT方案开发。

【TXW81x 低功耗开发指南】

该⼿册介绍了TXW81x低功耗方案开发。

【TXW81x 认证测试指南】

该⼿册介绍了TXW81x方案认证测试。

【TXW81x 天线匹配和测试指南】

该⼿册介绍了TXW81x方案认证测试。

【TXW81x 量产和烧录指南】

该手册详细解释了TXW81x量产烧录相关配置、工具和流程，包括在线烧录和离线烧录。