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 为全局定义，对整个工程有效。