YoC组件开发系列四: YoC YMAL规范(二)

  1. 前言

在上一篇文章里,我们对YoC YAML语法进行了简明的介绍,重点对YAML语法进行了分类,最后以KV组件为例,介绍了YoC如何利用YAML脚本对KV组件进行管理,分别对脚本里的七个部分做了介绍。本文进一步对YoC YAML语法规范做了详细描述和解释,为开发者用户在组件管理提供帮助。

  1. YoC YAML语法

2.1 组件定义
组件是完成某项特定功能的软件库,向开发者提供调用API,来满足应用需求。组件由软件描述信息、源代码或者库文件。组件目录结构中须包含下述文件:

说明文档:README.md
描述文件:package.yaml
2.1.1 说明文档
README.md 文件要介绍清楚该组件的功能以及特色介绍,包含组件的快速使用的方法,以及简单的示例代码。 参考模板如下:

概述

组件安装

接口

示例

运行资源

2.1.2 描述文件

第一部分: 基础信息

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 # YOC:表示使用当前版本以上的最新版本 (此项待定)

指定当前solution可以使用的sdk组件及版本, sdk_chip关键字只能出现在solution类型组件package.yaml里

sdk_chip:

  • sc5654_platform: v7.2.0
  • cb2201_platform: v7.2.0 # YOC:表示使用当前版本以上的最新版本 (此项待定)

第三部分:板级信息

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
    
    2.1.3 存储约定

为了保证 package.yaml文件的可读性与简约性,对 package.yaml文件的存储制定如下约定

字段的存储顺序与模板一致,保留模板的注释说明,数据与DICT 按读入时顺序保存 < 优选项>
默认值为空时,字段不出现在文件中 <优选项>
字符串不使用引号,除语法要求外 <优选项>
缩进采用二个空格字符 < 强制项>
一级字段之间增加一行空行,二级及以下字段不使用空行,第一部分基础信息一级字段间不使用空行 < 优选项>
2.2 硬件信息
字段 hw_info 用于配置该组件对硬件的依赖,该字段用于 chip、board、solution三种类型的组件中, common 类型该字段定义无效。

2.2.1 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 来推断编译器前缀
2.2.2 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 脚本
2.2.3 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 来推断编译器前缀

2.3 组件配置
组件可以定义一组配置项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

2.4 变量
在编译工程中,组件配置及内置的会产生出配置变量,在 package.yaml 中,可以使用配置变量来动态指定,变量使用方式为<变更名>, 例如:

根据 CPU 类型,使用不同的静态库

build_config:
libs:

- mqtt

libpath:

- libs/<cpu>

或者

build_config:
libs:

- mqtt-<cpu>

libpath:

- libs

根据 chip 及cpu,编译不同的源代码

source_file:

  • src///*.c

根据配置变量选择不同的源代码

/*.c ?

当 值为 'Y', 'YES', 'OK', '1', 'True'时,该选择有效

source_file:

  • src///*.c ? <CONFIG_DEBUG>

2.4.1 内置变量
: 大写 cpu arch 型号
: 小写 cpu arch 型号
<cpu_num> : CPU型号的数字, rsicv 对应是rv32
<cpu_num>:CK保持原定义,型号的数字;RISCV对应不再全部是RV32,而是如下对应表项: CDK V2.6.9其以后的版本中实现

e902 riscv/rv32_16gpr
e902m riscv/rv32_16gpr
e902t riscv/rv32_16gpr
e902mt riscv/rv32_16gpr
e906 riscv/rv32_32gpr
e906F riscv/rv32f_32gpr
e906FD riscv/rv32fd_32gpr
c906 riscv/rv64_32gpr
c906fd riscv/rv64fd_32gpr
c906v riscv/rv64fd_32gpr
c906fdv riscv/rv64fd_32gpr
c910 riscv/rv64fd_32gpr
c910v riscv/rv64fd_32gpr
其他RV处理器 rv32
: CPU指令架构 小写 'csky', 'rsicv','arm'
: CPU指令架构 大写 'CSKY', 'RSICV','ARM'
: 芯片供应商大写
: 芯片供应商小写
: 芯片名字大写
: 芯片名字小写
: 开发板名字大写
: 开发板名字小写
<BOARD_PATH> 开发板组件所在路径
<CHIP_PATH> 芯片组件所在路径
<SOLUTION_PATH> 方案组件所在路径
2.4.2 配置项变量
组件配置项也会生成同名的变量,例如:

def_config:
CONFIG_DEBUG: 1
CONFIG_ARCH_CSKY: 1
CONFIG_PARAM_NOT_CHECK: 1
增加变量:<CONFIG_DEBUG>=1、<CONFIG_ARCH_CSKY>=1、<CONFIG_PARAM_NOT_CHECK>=1

2.5 组件分类
根据组件的特点,分为以下4中类型组件:

solution:方案组件
board:开发板组件
chip:芯片驱动组件
common:通用组件
2.5.1 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
2.5.2 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 默认参数
2.5.3 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 文件。
2.5.4 common类型组件
不符合 solution 、board、chip 三种类型的组件,统称为 common 组件,common 组件通常为独立的第三方软件包,也可以是针对具体芯片的专用软件包。

2.6 组件编译选项作用域
common 组件的编译选项 cflag、cxxflag、asmflag 为私有定义,只对该组件有效。
solution/chip/board 组件的编译选项 cflag、cxxflag、asmflag 为全局定义,对整个工程有效。

上一篇:手把手教你如何安装wordpress


下一篇:IFAA开放能力,正式启动中小企业互联网身份认证加速器计划