yoctools芯片SDK开发
YoC 平台向开发者提供丰富的应用组件,来满足开发者不同需求。我们更需要更多的开发者一起参与,我们真诚邀请您参与YoC 的生态建设,欢迎向 YoC 提供您的开源组件。
组件定义
组件是完成某项特定功能的软件库,向开发者提供调用API,来满足应用需求。组件由软件描述信息、源代码或者库文件。组件目录结构中须包含下述文件:
- 说明文档:
README.md
- 描述文件:
package.yaml
说明文档(README.md)
README.md 文件要介绍清楚该组件的功能以及特色介绍,包含组件的快速使用的方法,以及简单的示例代码。 参考模板如下:
# 介绍
# 使用说明
# 示例
描述文件(package.yaml)
## 第一部分: 基础信息
name: helloworld # <必选项> 包名称 (符合C语言变量命名规则),长度少于等于64字节
description: 简洁直白用一句完成组件介绍 # <必选项> 建议至少20字以上
version: v7.3.0 # <必选项> 组件版本号
type: common # <必选项> 组件类型,为:solution, chip, board, common
tag: 通用组件 # <可选项> 组件分类,缺省值: ''
keywords: # <可选项> 标签,会影响到组件被搜索的效果,合理的标签很重要
- base
- XML
author: # <可选项> 原作者信息
name: Dave Gamble (original author), Max Bruckner (current maintainer)
license: MIT # <可选项> 源代码的许可证,要确保所有代码、文件的许可证不冲突。如:
# GPLv2,LGPLv2.1,MIT,Apache license v2.0,BSD
# 默认值: Apache license v2.0
homepage: https://www.t-head.cn
## 第二部分:依赖信息
# 指定该组件依赖的组件及版本,版本支持条件比较,支持:>=v1.0, >v1.0, ==v1.0, <=v1.0, <v1.0, v1.0
# 未指定条件时,默认为 ==,如 v1.0 与 ==v1.0
# depends: # <可选项> 该组件依赖其他的组件,合理的依赖才能保证组件能编译、使用
# - minilibc: v7.2.0
# - aos: >=v7.2.0
depends:
- minilibc: v7.2.0
- aos: >=v7.2.0
## 第三部分:板级信息
# hw_info: # 对 solution、board、chip 三个字段的改进,统称为 hw_info 字段
# cpu_id: cpu0
# cpu_name: CK804EF
# vendor_name: t-head
# chip_name: csi_pangu # <可选项> 指定芯片组件名,未设置时,使用depends中 chip 第一个组件
# board_name: pangu_cpu0 # <可选项> 指定开发板组件名,未设置时,使用depends中 board 第一个组件
# ld_script: configs/gcc_eflash.ld # <可选项> 连接时使用 LD 脚本,当选把未设置时,使用对应的 board 的 LD 脚本
# flash_program: bin/flash_program.elf # <可选项> 芯片全局烧写程序
# cpu0:
# cpu_name: CK804EF # <必选项> 该芯片使用的 CPU 型号
# ld_script: configs/gcc_eflash.ld # <必选项> 连接时使用 LD 脚本
# flash_program: bin/flash_program.elf # <可选项> 该CPU对应烧写程序,未指定时使用全局烧写程序
# cpu1:
# cpu_name: CK804EF # <必选项> 该芯片使用的 CPU 型号
# ld_script: configs/gcc_eflash.ld # <可选项> 连接时使用 LD 脚本
# flash_program: bin/flash_program.elf # <可选项> 该CPU对应烧写程序,未指定时使用全局烧写程序
## solution component
# hw_info:
# cpu_id: cpu0
# board_name: pangu_cpu0
# cpu_name: CK805EF
# vendor_name: t-head
# chip_name: 'csi_pangu'
# ld_script: configs/gcc_eflash.ld.S
## board component
# hw_info:
# chip_name: csi_pangu
# ld_script: configs/gcc_eflash.ld
## chip component (单处理器)
# hw_info:
# cpu_name: CK804EF
# ld_script: configs/gcc_eflash.ld
# flash_program: bin/flash_program.elf
## chip component(多处理器)
# hw_info:
# cpu0:
# cpu_name: CK804EF # <必选项> 该芯片使用的 CPU 型号
# ld_script: configs/gcc_eflash.ld # <必选项> 连接时使用 LD 脚本
# flash_program: bin/flash_program.elf # <可选项> 该CPU对应烧写程序,未指定时使用全局烧写程序
# cpu1:
# cpu_name: CK804EF # <必选项> 该芯片使用的 CPU 型号
# ld_script: configs/gcc_eflash.ld # <必选项> 连接时使用 LD 脚本
# flash_program: bin/flash_program.elf # <可选项> 该CPU对应烧写程序,未指定时使用全局烧写程序
# flash_program: bin/flash_program.elf # <可选项> 芯片全局烧写程序
hw_info:
cpu_name: CK804EF
ld_script: configs/gcc_eflash.ld
## 第四部分:编译连接信息
# build_config: # <可选项> 编译配置项
# include: # <可选项> 编译时,影响编译器的-I 参数 ,全局有效
# - src # include 只能是该软件包下的目录,不能使用外部目录
# internal_include: # <可选项> 编译时,影响编译器的-I 参数 ,组件内有效
# - include
# cflag: '' # <可选项> C 编译器所需要要的编译参数
# cxxflag: '' # <可选项> CXX 编译器所需要要的编译参数
# asmflag: '' # <可选项> 汇编器所需要要参数
# define: # <可选项> 宏定义, 增加编译器的-D 选项,如:
# XXX: 1 # -DXXX=1
# AAA: 1 # -DAAA
# STR: "abc" # -DSTR=\"abc\"
# libs: # 该组件中支持的二进制静态库,如:libxxx.a, libyyy.a
# - xxx # -lxxx
# - yyy # -lyyy
# libpath: # 指定静态库所在的路径(相对于该组件路径)
# - libs # -Llibs
build_config:
include:
- src
internal_include:
- include
## source_file: # <可选项> 指定参与编译的源代码文件,支持通配符,采用相对路径
# - src/*.c # 例:组件 src 目录下所有的扩展名为 c 的源代码文件
source_file:
- src/*.c
## 第五部分:配置信息
# def_config: # 组件的可配置项
# CONFIG_DEBUG: y
# CONFIG_PARAM_NOT_CHECK: y
# CONFIG_CLI: y
def_config:
CONFIG_DEBUG: y
CONFIG_PARAM_NOT_CHECK: y
CONFIG_CLI: y
## 第六部分:安装信息
# install:
# - dest: include/ # 安装的目的路径 dest是相当路径,通常是相对于YoC SDK 安装目录
# source: # 安装源列表
# - src/*.h # 支持通配符,相对路径
install:
- dest: include/
source:
- src/*.h
## 第七部分:导出部分
export:
- dest: <SOLUTION_PATH>/generated/data # 导出来到指定的位置
source:
- bootimgs/boot
- bootimgs/tee
- configs/config.yaml
存储约定
为了保证 package.yaml
文件的可读性与简约性,对 package.yaml
文件的存储制定如下约定
- 字段的存储顺序与模板一致,保留模板的注释说明,数据与DICT 按读入时顺序保存 < 强制项>
- 默认值为空时,字段不出现在文件中 <优选项>
- 字符串不使用引号,除语法要求外 <优选项>
- 缩进采用二个空格字符 < 强制项>
- 一级字段之间增加一行空行,二级及以下字段不使用空行,第一部分基础信息一级字段间不使用空行 < 强制项>
硬件信息
字段 hw_info
用于配置该组件对硬件的依赖,该字段用于 chip
、board
、solution
三种类型的组件中, common
类型该字段定义无效。
chip 组件
chip
组件中hw_info
包含:
- cpu_name: CPU 名字,例:'ck801', 'ck802', 'ck803', 'ck805', 'ck803f', 'ck803ef', 'ck803efr1', 'ck804ef', 'ck805f', 'ck805ef', 'cortex-m0'
- vendor_name: 芯片的供应商名
- arch_name: 芯片架构名称,例如:'arm', 'csky'
- ld_script: 该芯片应用编程默认使用的连接器脚本文件
- flash_program: 芯片 FLASH 烧写程序
- toolchain_prefix: 编译器前缀,例如:csky-abiv2-elf,可以选项,未指定时,根据 cpu_name 来推断编译器前缀
chip
组件的 hw_info
信息可支持单核、异构多核的配置,参考如下:
- 单CPU 的
chip
组件配置:
# chip component (单处理器)
hw_info:
cpu_name: CK804EF
vendor_name: t-head
arch_name: csky
ld_script: configs/gcc_eflash.ld
flash_program: bin/flash_program.elf # <可选项> 芯片全局烧写程序
toolchain_prefix: csky-abiv2-elf
- 异构多核的
chip
组件配置:
# chip component(多处理器)
hw_info:
vendor_name: t-head
cpu0:
cpu_name: CK804EF # <必选项> 该芯片使用的 CPU 型号
ld_script: configs/gcc_eflash.ld # <必选项> 连接时使用 LD 脚本
flash_program: bin/flash_program.elf # <可选项> 该CPU对应烧写程序,未指定时使用全局烧写程序
toolchain_prefix: csky-abiv2-elf
cpu1:
cpu_name: CK804EF # <必选项> 该芯片使用的 CPU 型号
ld_script: configs/gcc_eflash.ld # <必选项> 连接时使用 LD 脚本
flash_program: bin/flash_program.elf # <可选项> 该CPU对应烧写程序,未指定时使用全局烧写程序
toolchain_prefix: csky-abiv2-elf
flash_program: bin/flash_program.elf # <可选项> 芯片全局烧写程序
toolchain_prefix: csky-abiv2-elf
board 组件
board
组件的hw_info
字段包含:
- chip_name: 该开发板组件对应的芯片组件的名字,该字段是可选项
- ld_script: 使用该开发板的默认连接脚本,可选项,如果未指定,默认使用所依赖的 chip_name 组件的 ld_script 文件
# board component
hw_info:
chip_name: csi_pangu # <可选项> 指定芯片组件名,未设置时,使用depends中 chip 第一个组件
ld_script: configs/gcc_eflash.ld # <可选项> 连接时使用 LD 脚本,当选把未设置时,使用对应的 board 的 LD 脚本
solution 组件
solution
组件的hw_info
字段包含:
- board_name: 该solution 组件使用的开发板组件名字
- chip_name:指定 solution组件使用的 chip 组件,未指定时,使用
board_name
指定的 board 组件hw_info
指定的 chip 组件 - cpu_id: 当该方案使用的芯片上有多个 异构CPU时,指定对应的 CPU 配置
- cpu_name: 未指定时,使用 chip 组件的 cpu_name
- ld_script: 使用该solution 组件指定的连接脚本,未设置时,按 board、chip 组件依赖查找 到 ld_script 配置,当 cpu_id 与 cpu_name、ld_script 同时指定时, cpu_name、ld_script 优先于 cpu_id
- flash_program: 芯片 FLASH 烧写程序
- toolchain_prefix: 编译器前缀,例如:csky-abiv2-elf,可以选项,未指定时,根据 cpu_name 来推断编译器前缀
solution 组件的 hw_info 组件有三种使用场景:指定开发板、指定芯片、指定CPU
指定开发板
solution 组件支持一个或者多个开发板时,可以用通过 hw_info.board_name
组件来选择编译时对应的开发板,如果开发板上使用的芯片支持多 CPU时,再通过hw_info.cpu_id
来选择对应的处理器。
# solution component
hw_info:
board_name: pangu_cpu0 # <必选项> 指定开发板组件名,未设置时,使用depends中 board 第一个组件
cpu_id: cpu0
ld_script: configs/gcc_eflash.ld # <可选项> 连接时使用 LD 脚本,当选把未设置时,使用对应的 board 的 LD 脚本
...
depends:
pangu_cpu0: V7.3.0 # 开发板组件
board_dummy: V7.3.0 # 开发板组件
指定芯片
如果 solution 开发时,不使用 Borad 组件,可以直接使用 Chip 组件来选择编译参数
hw_info:
cpu_id: cpu0
chip_name: 'csi_pangu'
ld_script: configs/gcc_eflash.ld.S
...
depends:
csi_pangu: V7.3.0 # 芯片组件
指定CPU
如果 solution 开发时,不使用 Board 组件,也不使用 Chip 时,可以直接通过指定 cpu_name
与 ld_script
来编译程序,如果需要指定编译器前缀时,可通过 toolchain_prefix
字段指定
hw_info:
cpu_name: CK804EF
ld_script: configs/gcc_eflash.ld.S
flash_program: bin/flash_program.elf # <可选项> 芯片全局烧写程序
toolchain_prefix: csky-abiv2-elf # <可选项> 未指定时根据cpu_name 字段适配
当编译系统编译 solution 时,需要一个完整的 hw_info 信息,该信息通过 solution 、board 、chip 三个组件的 hw_info 字段汇总成一个完整的 hw_info 信息,示例如下 :
hw_info:
cpu_id: cpu0
cpu_name: CK804EF
vendor_name: t-head
arch_name: csky # <可选项> 指定芯片架构类型,未设置时,默认csky
chip_name: csi_pangu # <可选项> 指定芯片组件名,未设置时,使用depends中 chip 第一个组件
board_name: pangu_cpu0 # <可选项> 指定开发板组件名,未设置时,使用depends中 board 第一个组件
ld_script: configs/gcc_eflash.ld # <可选项> 连接时使用 LD 脚本,当选把未设置时,使用对应的 board 的 LD 脚本
flash_program: bin/flash_program.elf # <可选项> 芯片全局烧写程序
cpu0:
cpu_name: CK804EF # <必选项该芯片使用的 CPU 型号
ld_script: configs/gcc_eflash.ld # <必选项> 连接时使用 LD 脚本
flash_program: bin/flash_program.elf # <可选项> 芯片全局烧写程序
cpu1:
cpu_name: CK804EF # <必选项该芯片使用的 CPU 型号
ld_script: configs/gcc_eflash.ld # <必选项> 连接时使用 LD 脚本
flash_program: bin/flash_program.elf # <可选项> 芯片全局烧写程序
汇集的优先规则:solution 的 hw_info 优先于 board 的 hw_info,board 的 hw_info 优先于 chip组件。
组件配置
组件可以定义一组配置项def_config
,配置项在全工程内有效,示例:
def_config:
CONFIG_DEBUG: 1
CONFIG_ARCH_CSKY: 1
CONFIG_PARAM_NOT_CHECK: 1
CONFIG_CLI: 1
CONFIG_NETMGR_WIFI: 1
配置采用 Key-Value 形式,该配置通过C语言宏的方式定义,Key 为宏名,Value 为宏的值,Value 符合 yaml 标准的类型,可以是字符串、数值、布尔型,如:
def_config:
CONFIG_DEBUG: true
CONFIG_INT: 1
CONFIG_STR: "abc"
对应的C代码形式:
#define CONFIG_DEBUG 1
#define CONFIG_INT 1
#define CONFIG_STR "abc"
对应GCC 命令行参数: -DCONFIG_DEBUG=1 -DCONFIG_INT=1 -DCONFIG_STR=\"abc\"
每个组件都可以定义自己的配置项,组件内的配置项为该配置项的默认值。当 common 组件、chip 组件、board 组件、solution 组件都存在相同配置时,优先顺序为 :solution > board > chip > common
变量
在编译工程中,组件配置及内置的会产生出配置变量,在 package.yaml
中,可以使用配置变量来动态指定,变量使用方式为<变更名>, 例如:
# 根据 CPU 类型,使用不同的静态库
build_config:
libs:
- mqtt
libpath:
- libs/<cpu>
# 或者
build_config:
libs:
- mqtt-<cpu>
libpath:
- libs
# 根据 chip 及cpu,编译不同的源代码
source_file:
- src/<chip>/<cpu>/*.c
# 根据配置变量选择不同的源代码
# <ver>/*.c ? <condition>
# 当 <condition>值为 'Y', 'YES', 'OK', '1', 'True'时,该选择有效
source_file:
- src/<chip>/<cpu>/*.c ? <CONFIG_DEBUG>
内置变量
- \
: 大写 cpu arch 型号 - \
: 小写 cpu arch 型号 - \
: CPU型号的数字, rsicv 对应是rv32, arm对应的例如:cm0、cm3 - \
: CPU指令架构 小写 'csky', 'rsicv','arm' - \
: CPU指令架构 大写 'CSKY', 'RSICV','ARM' - \
: 芯片供应商大写 - \
: 芯片供应商小写 - \
: 芯片名字大写 - \
: 芯片名字小写 - \
: 开发板名字大写 - \
: 开发板名字小写 - \
开发板组件所在路径 - \
芯片组件所在路径 - \
方案组件所在路径
配置项变量
组件配置项也会生成同名的变量,例如:
def_config:
CONFIG_DEBUG: 1
CONFIG_ARCH_CSKY: 1
CONFIG_PARAM_NOT_CHECK: 1
增加变量:
组件分类
根据组件的特点,分为以下4中类型组件:
solution
:方案组件board
:开发板组件chip
:芯片驱动组件common
:通用组件
board类型组件
提供芯片开发板的管脚配置、初始化函数、二进制数据等,该组件可以生成库文件
hw_info: # <过时配置> 当 type 为 board,该字段为 board 相关配置
chip_name: csi_pangu # 该开发板使用的芯片组件名
ld_script: configs/gcc_eflash.ld # <可选项> 连接时使用 LD 脚本,当选把未设置时,使用对应的 board 的 LD 脚本
说明:
- board 组件的 hw_info 组件,需要包含该组件对应的芯片组件名,即设置
`hw_info.chip_name
字段 - ld_script 字段可以缺省,未指定 ld_script 时,使用所依赖的芯片的
hw_info.ld_script
chip类型组件
提供芯片的 CSI 驱动功能,该组件可以生成库文件
hw_info: # <过时配置> 当 type 为 board,该字段为 board 相关配置
cpu_name: CK804EF # <必选项> 该开发板使用的芯片组件名
ld_script: configs/gcc_eflash.ld # <可选项> 连接时使用 LD 脚本,当选把未设置时,使用对应的 board 的 LD 脚本
...
build_config: # <必选项> 编译配置项
cflag: >
-nostdlib -mistack -Wpointer-arith -Wundef -Wall -Wl,-EL
-ffunction-sections -fdata-sections
-fno-inline-functions -fno-builtin -fno-strict-aliasing -fno-strength-reduce
说明:
hw_info.cpu_name
对应的CPU名称:CK801, CK802, ck803, CK805, CK803F, CK803EF, CK803EFR1, CK804EF, CK805F, CK805EF, RV32EMC
hw_info.ld_script
: 该字段需要指定该芯片默认支持的连接脚本build_config.cflag
: 指定该芯片对应的编译器所需要的基础参数,该参数通常为 YoC 默认参数
solution类型组件
能够生成二进制执行程序的组件,还包含 FLASH 分区、BOOT、resource 等资源,该组件可以生成 FLASH IMAGE包、烧录FLASH。
hw_info: # 对 solution、board、chip 三个字段的改进,统称为 hw_info 字段
board_name: pangu_cpu0 # <可选项>
vendor_name: t-head # <可选项>
chip_name: csi_pangu # <可选项>
cpu_name: CK804EF # <可选项>
ld_script: configs/gcc_eflash.ld # <可选项>
对于 solution 组件,工程编译时,需要有cpu_name
与ld_script
字段,该字段可以在 solution 组件、board 组件、chip 组件中获取。当 solution、board、chip 三个组件中都存在相同字段时,按 solution 优先于 board,board 优化于 chip 规则。即:
- 当 solution 中定义了
hw_info.ld_script
时,工程连接时使用solution.hw_info.ld_script
,board 与 chip 的hw_info.ld_script
无效。 - 当 solution 的
hw_info.ld_script
未定义时,根据hw_info.board_name
找到对应的 board 组件,连接脚本取 board 组件的、hw_info.ld_script
值,当 board 组件的hw_info.ld_script
不存在时,根据 board 组件的hw_info.chip_name
到对应的芯片组件,取芯片组件的hw_info.ld_script
对应的文件作为连接脚本。 - 根据以上优先规则,获取到 ld_script 后,如果对应的文件不存时,编译错误,无需要再按优化顺序取下一个 ld_script 文件。
common类型组件
不符合 solution
、board
、chip
三种类型的组件,统称为 common 组件,common 组件通常为独立的第三方软件包,也可以是针对具体芯片的专用软件包。
配置作用域
- common 组件的 build_config 组件下的
cflag
、cxxflag
、asmflag
为私有定义,只对该组件有效, solution、chip、board 组件的cflag
、cxxflag
、asmflag
为全局组件,对整个工程有效
组件开源
YoC 开源组件开发步骤:
- 第一步:根据上述模板,完成组件开发
- 第二步:发布到 https://code.aliyun.com 或者其他开源社区的代码仓库。目前仅支持 git 仓库
- 第三步:登录 OCC 平台, 进入组件管理页面,然后在“组件”档目中“新建”组件
- 第四步:在“组件地址”中输入 GIT 仓库的地址,要求以
https://
或者http://....
的地址,不能使用类似git@github.com
的GIT仓库地址 - 第五步:等待 OCC 小二审核通过后,可以在 OCC 平台 看到该组件,通过审核的组件可以 YoC 的方案中使用。