HiSpark编程指南
前言¶
概述
本文档介绍BS2X系列芯片SDK开发环境（包括：SDK编译、应用程序的开发等），用于帮助用户在快速了解开发环境后编译出可执行文件进行二次开发。
产品版本
与本文档相对应的产品版本如下。
产品名称 |
产品版本 |
|---|---|
BS2X |
V100 |
读者对象
本文档主要适用于以下工程师：
技术支持工程师
软件开发工程师
符号约定
在本文中可能出现下列标志，它们所代表的含义如下。
符号 |
说明 |
|---|---|
|
表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。 |
|
表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。 |
|
表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。 |
|
用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。 “须知”不涉及人身伤害。 |
|
对正文中重点信息的补充说明。 “说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。 |
修改记录
文档版本 |
发布日期 |
修改说明 |
|---|---|---|
04 |
2025-08-07 |
更新“打包添加其他bin文件”小节内容。 |
03 |
2025-05-30 |
更新“flash分区表配置”小节内容。 |
02 |
2025-01-24 |
|
01 |
2024-05-15 |
第一次正式版本发布。 |
00B03 |
2024-02-29 |
更新“版本编译”小节内容。 |
00B02 00B01 |
2023-12-04 2023-10-27 |
更新“启动编译”小节内容。 第一次临时版本发布。 |
开发环境搭建¶
SDK开发环境简介¶
典型的SDK开发环境主要包括：
Linux服务器
Linux服务器主要用于建立交叉编译环境，实现在Linux服务器上编译出可以在目标板上运行的可执行代码。
工作台
工作台主要用于目标板烧录和调试，通过串口与目标板连接，开发人员可以在工作台中烧录目标板的镜像、调试程序。工作台通常需要安装终端工具，用于登录Linux服务器和目标板，查看目标板的打印输出信息。工作台一般为Windows或Linux操作系统，在Windows或Linux工作台运行的终端工具通常有SecureCRT、Putty、miniCom等，这些软件需要从其官网下载。
目标板
本文的目标板以DEMO板为例，DEMO板与工作台通过USB转串口连接。工作台将交叉编译出来的DEMO板镜像通过串口烧录到DEMO板。如图1所示。
图 1 SDK 开发环境
搭建Windows开发环境¶
BS2X解决方案提供了Windows下IDE开发工具，支持一键构建版本，基于IDE的编译环境搭建，请参考《BS2XV100 IDE工具使用指南》，本文档不再赘述。
搭建Linux开发环境¶
Linux系统推荐使用Ubuntu 20.04及以上版本，Shell使用bash ，SDK使用Cmake编译（3.14.1以上），编译工具还包括Python（3.8.0以上）等。
配置Shell¶
配置默认使用 bash。打开Linux终端，执行命令“sudo dpkg-reconfigure dash”，选择 no。
安装Cmake¶
打开Linux终端，执行命令“sudo apt install cmake”，完成Cmake的安装。
安装Python环境¶
打开Linux终端，输入命令“python3 -V”，查看Python版本号，推荐python3.8.0以上版本。
如果Python版本太低，请使用命令“sudo apt-get update”更新系统到最新，或通过命令“sudo apt-get install python3 -y”安装Python3（需root/sudo权限安装），安装后再次确认Python版本。
如果仍不能满足版本要求，请从“https://www.python.org/downloads/source/ ”下载对应版本源码包，下载与安装方法请阅读 https://wiki.python.org/moin/BeginnersGuide/Download 和源码包内README内容。
安装Python包管理工具，运行命令“sudo apt-get install python3-setuptools python3-pip -y”（需root/sudo权限安装）。
安装Kconfiglib 14.1.0+，使用命令“sudo pip3 install kconfiglib”（需root/sudo权限安装），或从“https://pypi.org/project/kconfiglib”下载.whl文件（例如：kconfiglib-14.1.0-py2.py3-none-any.whl）后，使用“pip3 install kconfiglib-xxx.whl”进行安装（需root/sudo权限安装），或者下载源码包到本地并解压，使用“python setup.py install”进行安装（需root/sudo权限安装）。安装完成界面如图1所示。
图 1 安装Kconfiglib组件包完成示例
安装升级文件签名依赖的Python组件包。
安装pycparser：
从“https://pypi.org/project/pycparser/”下载.whl文件（例如：pycparser-2.21-py2.py3-none-any.whl）后，使用“pip3 install pycparser-xxx.whl”进行安装（需root/sudo权限安装），或者下载源码包到本地并解压，使用“python setup.py install”进行安装（需root/sudo权限安装）。安装完成后界面会提示“Successfully intalled pycparser-2.21”。
说明： 如果构建环境中包含多个python，特别是多个同版本的python，而用户无法辨认正在使用的是其中的哪个版本，此情况下，在安装python组件包时，推荐使用组件包源码进行安装。
编译SDK¶
SDK目录结构介绍¶
SDK根目录结构如表1所示。
表 1 SDK根目录
目录 |
说明 |
|---|---|
application |
应用层代码（其中包含demo程序为参考示例）。 |
build |
SDK构建所需的脚本、配置文件。 |
build.py |
编译入口脚本。 |
CMakeLists.txt |
Cmake工程顶层“CMakeLists.txt”文件。 |
config.in |
Kconfig配置文件。 |
drivers |
驱动代码。 |
include |
API头文件存放目录。 |
interim_binary |
库存放目录。 |
kernel |
内核代码和OS接口适配层代码。 |
middleware |
中间件代码。 |
open_source |
开源代码。 |
protocol |
BLE、SLE等协议栈。 |
test |
testsuite代码。 |
tools |
包含编译工具链（包括linux和windows）、镜像打包脚本、NV制作工具和签名脚本等。 |
output |
编译时生成的目标文件与中间文件（包括库文件、打印log、生成的二进制文件等）。 |
注：上表所述的output目录是编译后生成的。解压缩SDK后的根目录，如图1所示。
图 1 解压缩SDK示例
编译SDK（Cmake）¶
编译方法¶
根目录下执行“python3 build.py”指令运行脚本编译，即可编译出对应的SDK程序。编译命令列表如表1所示。此处以standard-bs21-n1100为例说明，根据BS2X项目不同编译目标可能不一致。
表 1 build.sh参数列表
参数 |
示例 |
说明 |
|---|---|---|
无 |
python3 build.py standard-bs21-n1100 |
启动standard-bs21-n1100目标的增量编译。 |
-c |
python3 build.py -c standard-bs21-n1100 |
启动standard-bs21-n1100目标的全量编译。 |
menuconfig |
python3 build.py standard-bs21-n1100 menuconfig |
启动standard-bs21-n1100目标的menuconfig图形配置界面。 |
表 2 编译目标介绍
编译目标 |
说明 |
|---|---|
python3 build.py -c standard-bs21-n1100 |
app版本编译目标（flashboot将被打包至编译产物）。 |
python3 build.py -c flashboot-bs21-n1100 |
flashboot镜像编译目标。 |
编译得到的烧录镜像在“output/bs21/fwpkg/standard-bs21-n1100”目录下（如表3所示）。
表 3 烧录镜像
文件名 |
说明 |
|---|---|
bs21_all_in_one.fwpkg |
空片烧录时，需要烧录此文件。包含了所有的需要烧录的内容。包含：loaderboot_sign.bin、flashboot_sign_a.bin、flashboot_sign_b.bin、bs21_all_nv.bin、application_sign.bin。 各文件介绍如下： loaderboot_sign.bin：loaderboot的镜像文件。升级开始时，芯片中固化的romboot会接收此镜像文件，加载到内存并运行，loadboot负责接收后续的镜像文件。注：此镜像只在升级阶段放在RAM中运行，并不存放在flash中。 flashboot_sign_a.bin：flashboot的镜像文件，烧录完成执行后，首要执行的flashboot镜像，启动时会校验flashboot的完整性。 flashboot_sign_b.bin：flashboot的备份镜像文件，当首要flashboot镜像被检查为不合法或已损坏时，将加载本镜像。 bs21_all_nv.bin：参数区的镜像文件。 application_sign.bin：应用版本镜像文件。 |
bs21_loadapp_only.fwpkg |
版本升级打包文件，包含：loaderboot_sign.bin、application_sign.bin。不包含flashboot相关内容。 当芯片烧录过“bs21_all_in_one.fwpkg”镜像后，如果后续修改不涉及flashboot、nv的修改，则可以用此文件升级。 |
bs21_flashboot_only.fwpkg |
boot升级打包文件，包含：loaderboot_sign.bin、flashboot_sign_a.bin、flashboot_sign_b.bin。不包含application相关内容。 当芯片烧录过“bs21_all_in_one.fwpkg”镜像后，有升级flashboot的需求，可用此文件升级。 |
bs21_nv_only.fwpkg |
nv升级打包文件，包含loaderboot_sign.bin、bs21_all_nv.bin。不包含application和flashboot相关内容。 当芯片烧录过“bs21_all_in_one.fwpkg”镜像后，有升级nv参数的需求，可用此文件升级。 |
注：编译得到的中间文件在“output/bs21/acore/standard-bs21-n1100”目录下。
编译参数详解¶
编译命令接收参数及解释如表1所示。
表 1 编译参数信息表
参数 |
参数信息 |
|---|---|
-c |
clean后编译。 |
-j |
-j<num>，以num线程数执行编译，如-j16、-j8。 默认最大线程。 |
-def= |
-def=XXX,YYY,ZZZ=x,... 向本次编译target中添加XXX、YYY、ZZZ=x编译宏。 可使用-def=-:XXX屏蔽XXX宏； 可使用-def=-:ZZZ=x添加或者修改ZZZ宏。 |
-component= |
-component=XXX,YYY,... 仅编译XXX,YYY组件。 |
-ninja |
使用ninja生成中间文件，默认使用Unix makefile。 |
-[release / debug] |
release: 在生成反汇编文件时节省时间； debug: 在生成反汇编文件时信息更加全面但也更耗时。 默认为debug。 |
-dump |
编译时在终端输出target的所有参数列表（包括编译宏、组件、编译选项等）。 |
-nhso |
不更新HSO数据库。 |
-out_libs |
-out_libs=file_path，不再链接成elf，转而将所有.a打包成一个大的.a。 |
others |
作为匹配编译target_names的关键字。 |
编译选项详解¶
bs2x在不同目录下的.py文件下配置编译选项，如表1所示。
表 1 BS2X通用组件编译选项
编译选项类型 |
说明 |
内容 |
对应文件控制路径 |
|---|---|---|---|
common_ccflags |
基础编译选项 |
-std=gnu99 -Wall -Werror -Wextra -Winit-self -Wpointer-arith -Wstrict-prototypes -Wno-type-limits -fno-strict-aliasing -Os -fno-unwind-tables |
\sdk\build\config\target_config\common_config.py |
riscv31 |
芯片类型编译选项 |
-ffreestanding -fdata-sections -Wno-implicit-fallthrough -ffunction-sections -nostdlib -pipe -fno-tree-scev-cprop -fno-common -mpush-pop -msmall-data-limit=0 -fno-ipa-ra -Wtrampolines -Wlogical-op -Wjump-misses-init -Wa,-enable-c-lbu-sb -Wa,-enable-c-lhu-sh -fimm-compare -femit-muliadd -fmerge-immshf -femit-uxtb-uxth -femit-lli -femit-clz -fldm-stm-optimize -g |
\sdk\build\config\target_config\common_config.py |
fp_flags |
硬浮点编译选项 |
-march=rv32imfc -mabi=ilp32f |
\sdk\build\config\target_config\bs21\target_config.py |
codesize_flags |
codesize优化选项 |
--short-enums -madjust-regorder -madjust-const-cost -freorder-commu-args -fimm-compare-expand -frmv-str-zero -mfp-const-opt -frtl-sequence-abstract -frtl-hoist-sink -fsafe-alias-multipointer -finline-optimize-size -fmuliadd-expand -mlli-expand -Wa,-mcjal-expand -foptimize-reg-alloc -fsplit-multi-zero-assignments -floop-optimize-size -Wa,-mlli-relax -mpattern-abstract -foptimize-pro-and-epilogue |
\sdk\build\config\target_config\bs21\target_config.py |
其中，编译选项的详细说明如表2所示。
表 2 编译选项详细说明
选项 |
说明 |
|---|---|
-std=gnu99 |
使用 ISO C99 标准再加上GNU的扩展。 |
-Wall |
选项意思是编译后显示所有警告。 |
-Werror |
用于将所有警告升级成错误。 |
-Wextra |
用于开启额外的警告信息（-Wall的补充）。 |
-Winit-self |
警告使用自己初始化的未初始化变量。 |
-Wpointer-arith |
警告任何取决于“功能类型”或“功能类型”的大小void。 |
-Wstrict-prototypes |
警告如果一个函数被声明或定义而没有指定参数类型。 |
-Wno-type-limits |
屏蔽由于数据类型范围有限而导致比较始终为真或始终为false的告警。 |
-fno-strict-aliasing |
禁用strict-aliasing优化规则：不同类型的指针绝对不会指向同一块内存区域。 |
-Os |
专门优化目标文件大小，执行所有的不增加目标文件大小的-O2优化选项，同时-Os还会执行更加优化程序的选项。 |
-fno-unwind-tables |
删除unwind调试信息。 |
-ffreestanding |
断言编译发生在独立环境中。 |
-fdata-sections |
将每个数据放入自己的部分（仅限ELF）。 |
-Wno-implicit-fallthrough |
可忽略编译时switch-case中缺少break的错误。 |
-ffunction-sections |
将每个函数放在自己的节中（仅限ELF）。 |
-nostdlib |
关闭默认头文件与库文件搜索目录。 |
-pipe |
编译过程中使用管道，借助GCC的管道功能来提高编译速度。 |
-fno-tree-scev-cprop |
禁用标量演化信息进行复写传递，代码空间优化相关。 |
-fno-common |
可以把静态库中的没有初始化的全局变量从弱符号变成强符号，当所有静态库链接成可执行文件，如果同时有两个以上“重名强符号”，链接器会报错。 |
-mpush-pop |
CodeSize优化，改编译选项需要CPU版本支持push/pop/popret/lwm/swm等指令。 |
-msmall-data-limit=0 |
CodeSize优化，改编译选项需要CPU版本支持push/pop/popret/lwm/swm等指令。 |
-fno-ipa-ra |
禁用编译器针对叶子函数的编译优化（编译选项中添加了-O2优化选项时-fipa-ra参数导致）。 |
-Wtrampolines |
该选项用于检查代码中是否包含内嵌函数,gcc对内嵌函数有个专门的称呼:trampoline。 |
-Wlogical-op |
当逻辑操作结果似乎总为真或假时给出警告。 |
-Wjump-misses-init |
switch或者goto语句后声明并且初始化变量，进行告警。 |
-Wa,-enable-c-lbu-sb |
汇编器优化，默认禁用。如果启用此优化，汇编器将使用压缩的lbu & sb替换 lbu & sb。 |
-Wa,-enable-c-lhu-sh |
汇编器优化，默认禁用。如果启用此优化，汇编器将使用压缩的lhu & sh替换 lhu & sh。 |
-fimm-compare |
代码大小的优化，可以将非零立即比较的两条指令（li，bxx）合并到一条指令（bxxi）。 |
-femit-muliadd |
CodeSize优化，可以将多条加树指令合并为一条指令。 |
-fmerge-immshf |
CodeSize优化，可以将立即移位合并为一条指令。组合仅在-O1以上的选项中生效。 |
-femit-uxtb-uxth |
CodeSize优化，将无符号扩展字节和无符号扩展半字优化为uxtb、uxth(16字节)。组合仅在-O1以上的选项中。 |
-femit-lli |
使用48位l.li指令代替64位指令lui + addi进行32位长立即加载。此优化与insn组合结合使用。 |
-femit-clz |
支持CLZ指令，所有__builtin_clz函数的调用都会优化为CLZ指令。 |
-fldm-stm-optimize |
启用用 ldmia/stmia 替换连续WORD加载/存储的优化，默认禁用。 |
-g |
调试编译选项，对于可执行二进制文件可通过以下方法确定是否包含调试信息。 |
-mabi=ilp32f |
支持硬浮点（指定整数和浮点调用约定）。 |
-march=rv32imfc |
支持硬浮点（为给定的RISC-V ISA生成代码）。 |
--short-enums |
CodeSize优化，enum类型等于大小足够的最小整数类型。 |
-madjust-regorder |
寄存器分配优化-寄存器分配顺序调整优化。 |
-madjust-const-cost |
立即数重复加载优化。 |
-freorder-commu-args |
浮点运算可交换操作数优化。 |
-fimm-compare-expand |
扩展指令常量比较指令优化。 |
-frmv-str-zero |
rodata段常量字符串对齐优化。 |
-mfp-const-opt |
浮点常量加载优化。 |
-mswitch-jump-table |
switch case跳转表优化。 |
-frtl-sequence-abstract |
函数内过程优化。 |
-frtl-hoist-sink |
代码移动优化。 |
-fsafe-alias-multipointer |
多级指针重复加载优化。 |
-finline-optimize-size |
inline内联代价模型优化。 |
-fmuliadd-expand |
扩展指令乘加指令优化（muliadd优化）。 |
-mlli-expand |
扩展指令l.li指令优化。 |
-Wa,-mcjal-expand |
汇编器上jal压缩指令优化。 |
-foptimize-reg-alloc |
寄存器分配优化-寄存器分配优先级调整优化。 |
-fsplit-multi-zero-assignments |
连续赋零值优化。 |
-floop-optimize-size |
循环结构优化。 |
-Wa,-mlli-relax |
高频立即数加载优化（汇编器和链接器协同优化）。 |
-mpattern-abstract |
过程间抽象优化（根据已知pattern抽象优化）。 |
-foptimize-pro-and-epilogue |
函数prologue和epilogue优化。 |
打包添加其他bin文件¶
当前bs21编译bs21_all_in_one.fwpkg时，默认会编译bs21_all_nv.bin、application_sign.bin文件，在打包时则会添加loaderboot_sign.bin、flashboot_sign_a.bin、flashboot_sign_b.bin文件，文件介绍如表3所示。
如果需要打包其他bin文件，可按如下步骤添加：
在根路径下打开/tools/pkg/chip_packet/bs2x/packet.py文件。
在make_all_in_one_packet函数中添加代码，如图1所示。
图 1 文件路径和待添加函数
在函数中添加bin文件路径，以partition.bin为例。
其中每个拼接字符串代表一层目录（文件夹名和文件名）
最终拼接完成的partition.bin实际路径：sdk\interim_binary\bs21\bin\boot_bin\loaderboot_sign.bin。
图 2 bin文件路径图
设置打包参数，参数之间用"|"分割，如图3所示。
图 3 bin文件编译参数
烧录位置，单板剩余地址可在sdk\build\config\target_config\bs2x\flash_sector_config\bs2x-xxx.json文件中查看。
占用空间大小。
文件类型。
0：loader。
1：代表普通烧写文件，烧写到flash。
3：eFuse。
4：OTP。
在函数末尾，将设置好编译参数和路径的变量添加到编译列表，如图3所示。
图 4 添加路径到编译列表
编译结果展示如图5所示。
图 5 编译结果
flash分区表配置¶
分区表配置文件路径“sdk\build\config\target_config\bs21\flash_sector_config\xxx.json”。
表 1 分区表说明
分区表Id |
起始地址 |
分区长度 |
描述 |
|---|---|---|---|
0x00 |
0x00001000 |
0x0000A000 |
flashboot a：二级boot主区（size根据使用使用大小配置）。 |
0x01 |
0x0000B000 |
0x00000000 |
flashboot b：二级boot备份区（size根据使用使用大小配置）。 |
0x23 |
0x0000B000 |
0x00073000 |
acpu image：应用程序分区。 |
0x25 |
0x00000000 |
0x00000080 |
nv data：nv数据区域。 |
0x26 |
0x00000080 |
0x00000700 |
fota dat：fota备份区。 |
0x27 |
0x00000000 |
0x00000000 |
rsv1：预留分区1。 |
0x28 |
0x00000000 |
0x00000000 |
rsv1：预留分区2。 |
0x29 |
0x00000000 |
0x00000000 |
rsv1：预留分区3。 |
0x30 |
0x00000000 |
0x00000000 |
rsv1：预留分区4。 |
0x31 |
0x00000000 |
0x00000000 |
rsv1：预留分区5。 |
0x32 |
0x00000000 |
0x00000000 |
rsv1：预留分区6。 |
0x33 |
0x00000000 |
0x00000000 |
rsv1：预留分区7。 |
Menuconfig配置¶
运行“python3 build.py -c standard-bs21-n1100 menuconfig”脚本会启动Menuconfig程序，用户可通过Menuconfig对编译和系统功能进行配置，如图1所示。
SDK集成了默认配置，但建议用户首次运行时进行相应配置，从而减少因为配置原因引起的问题。用户随时可以运行“python3 build.py -c standard-bs21-n1100 menuconfig”更改配置。
图 1 Menuconfig运行界面
注：界面如存在差异，以实际版本为准。
Menuconfig操作说明如表1所示，在Menuconfig界面中可输入快捷键进行配置。
表 1 Menuconfig常用操作命令
快捷键 |
说明 |
|---|---|
空格、回车 |
选中，反选。 |
ESC |
返回上级菜单，退出界面。 |
Q |
退出界面。 |
S |
保存配置。 |
F |
显示帮助菜单。 |
所有命令可在Menuconfig界面的下方查看Menuconfig官方说明解释，如图2所示。
图 2 Menuconfig命令帮助栏
表 2 Menuconfig菜单项说明
菜单 |
说明 |
|---|---|
Targets |
编译target相关配置。 |
Application |
应用相关配置（主要是sample相关）。 |
Bootloader |
boot相关配置。 |
Drivers |
外设驱动相关配置和板级相关配置。 |
Kernel |
内核相关配置。 |
Middleware |
中间件（NV、FOTA、AT、DFX、PM等）相关配置。 |
Protocol |
星闪、蓝牙相关配置。 |
Test |
testsuite相关配置。 |
注意事项¶
如果执行“./build.py”提示无权限，可执行命令“chmod +x build.py”添加执行权限或执行“python3./build.py”。
编译过程中，报错找不到某个包，请检查环境中的python是否已经安装了相应组件。如果构建环境中包含多个python，特别是多个同版本的python，而用户无法辨认正在使用的是其中的哪个版本，此情况下，在安装python组件包时，推荐使用组件包源码进行安装。
系统优先使用用户通过Menuconfig所做的配置，如果用户未配置，系统将使用默认配置进行编译。
新建APP¶
建立源码目录¶
步骤如下：
新建“application/bs21/my_demo”目录，用来存放“my_demo”的源文件。
复制“application/bs21/standard/CMakeLists.txt”到“application/bs21/my_demo/CmakeLists.txt”，并将源文件放在“application/bs21/my_demo”目录下。
修改“application/bs21/my_demo/CmakeLists.txt”文件。其中各个变量的含义如表1所示。
表 1 组件的CmakeLists.txt中的变量含义
变量名称
变量含义
COMPONENT_NAME
当前组件名称，如“my_demo”。
SOURCES
当前组件的C文件列表，其中CMAKE_CURRENT_SOURCE_DIR变量标识当前CMakeLists.txt所在的路径。
PUBLIC_HEADER
当前组件需要对外提供的头文件的路径。
PRIVATE_HEADER
当前组件内部的头文件搜索路径。
PRIVATE_DEFINES
当前组件内部生效的宏定义。
PUBLIC_DEFINES
当前组件需要对外提供的宏定义。
COMPONENT_PUBLIC_CCFLAGS
当前组件需要对外提供的编译选项。
COMPONENT_CCFLAGS
当前组件内部生效的编译选项。
修改“application/bs21/CMakeLists.txt”，将my_demo目录加入编译。
修改“build/config/target_config/bs21/config.py”，在ram_component字段中加入‘my_demo’，向编译系统中注册my_demo组件。
开发代码¶
目录结构建立完成后开始启动开发代码（用户可参考“application/samples”进行移植），代码开发完成后即可使用“python3 build.py -c standard-bs21-n1100”编译my_demo进行代码编译调试。
镜像烧录¶
镜像烧录方法，请参见《BS2XV100 BurnTool工具 使用指南》中“操作指南”章节。