移植案例与原理 - HDF驱动框架-驱动配置（1）

HCS(HDF Configuration Source)是HDF驱动框架的配置描述源码，内容以Key-Value为主要形式。它实现了配置代码与驱动代码解耦，便于开发者进行配置管理。应该，类似Linux DTS(Device Tree Source)设备树。

HC-GEN(HDF Configuration Generator)是HCS配置转换工具，可以将HDF配置文件转换为软件可读取的文件格式。类似的，在Linux下，可以将DTS转换为DTB（Device Tree Blob，设备树数据二进制编码），使用的工具是DTC。

对于HC-GEN，对不同性能的环境，采用不同的策略，如下。现在还不清楚，高弱性能环境是如何定义的。

在弱性能环境中，转换为配置树源码，驱动可直接调用C代码获取配置。
在高性能环境中，转换为HCB(HDF Configuration Binary)二进制文件，驱动可使用HDF框架提供的配置解析接口获取配置。

使用HCB模式的配置使用流程如下图，HCS经过HC-GEN编译生成HCB文件，HDF驱动框架中的HCS Parser模块会从HCB文件中重建配置树，HDF驱动模块使用HCS Parser提供的配置读取接口获取配置内容。

1、HCS 配置语法

1.1 HCS使用的关键字

关键字	描述	备注
root	配置根节点
include	引用其他HCS配置文件
delete	删除节点和属性	只能删除include引入的节点或属性
template	定义模板节点
match_attr	用于标记节点的匹配查找属性	解析配置时可以使用该属性的值查找到对应节点

关键字include、delete、template可以在文件drivers\framework\tools\leagecy\hc-gen\src\hcs_compiler.l中找到：

"root"              { LEXER_DEBUG("root\n"); return ROOT; }
"true"              { HcsCompilerlval.i = 1; return NUMBER; }
"false"             { HcsCompilerlval.i = 0; return NUMBER; }
"#include"          { LEXER_DEBUG("INCLUDE\n"); return INCLUDE; }
"delete"            { return DELETE; }
"template"          { return TEMPLATE; }

关键字match_attr应该是定义在文件drivers\framework\utils\include\hcs_tree_if.h中。

#define HCS_MATCH_ATTR "match_attr"

1.2 基本组成结构

HCS配置文件主要由属性attribute和节点node两部分组成。

1.2.1 属性

属性即最小的配置单元，是一个独立的配置项。语法如下，类似键值对，attribute 必须以分号(;)结束且必须属于一个node。

  attribute_name = value;

其中：

属性名称attribute_name：

字母、数字、下划线的组合且必须以字母或下划线开头，字母区分大小写。
属性值value：

可用格式为：数字常量，支持二进制、八进制、十进制、十六进制数，具体参考数据类型部分；字符串，内容使用双引号(“”)引用；节点引用。

1.2.2 节点

节点是一组属性的集合，语法如下，大括号后无需添加结束符“;”。其中，node_name 是字母、数字、下划线的组合且必须以字母或下划线开头，字母区分大小写。

  node_name {
      module = "sample";
      ...
  }

每个配置表必须以root节点开始，用于声明配置表的根节点。root节点中必须包含module属性，其值应该为一个字符串，用于表征该配置所属模块。节点中还可以增加match_attr属性，其值为一个全局唯一的字符串。在解析配置时，通过该属性值，调用查找节点可以查找到包含该属性的节点。

1.2.3 数据类型

在属性定义中使用自动数据类型，不显式指定类型，属性支持的数据类型如下。

1.2.3.1 整型

整型长度自动推断，根据实际数据长度给与最小空间占用的类型。

二进制，0b前缀，示例：0b1010。
八进制，0前缀，示例：0664。
十进制，无前缀，且支持有符号与无符号，示例：1024，+1024均合法。负值在读取时注意使用有符号数读取接口。
十六进制，0x前缀，示例：0xff00、0xFF。

1.2.3.2 字符串

字符串使用双引号(“”)表示。

1.2.3.3 数组

数组元素支持整型、字符串，不支持混合类型。整型数组中uint32_t uint64_t混用会向上转型为uint64_t 数组。整型数组与字符串数组示例如下

attr_foo = [0x01, 0x02, 0x03, 0x04];
attr_bar = ["hello", "world"];

1.2.3.4 bool类型

bool类型中true表示真，false表示假。

1.2.4 include预处理

用于导入其他HCS文件。语法示例如下，文件名必须使用双引号(“”)，不在同一目录使用相对路径引用。被include文件也必须是合法的HCS文件。
多个include，如果存在相同的节点，后者覆盖前者，其余的节点依次展开。

#include "foo.hcs"
#include "../bar.hcs"

可以参考示例文件device\board\fnlink\hcs\v200zr.hcs，等于板端hcs文件复用soc芯片部分的文件。

#include "../../../soc/bestechnic/bes2600/liteos_m/components/hdf_config/device_info.hcs"

1.2.5 注释

支持单行和多行两种注释风格。多行注释不支持嵌套，注释示例如下：

// comment 单行注释

/*
comment 多行注释
comment 多行注释
*/

1.2.6 引用修改

引用修改可以实现修改另外任意一个节点的内容，引用修改节点不产生新的节点，只修改另外一个节点。语法如下，表示node中的内容是对source_node节点内容的修改。注意 “:&”是整体，前后各有一个空格。

 node :& source_node

引用修改有如下注意事项：

引用同级node，可以直接使用node名称，否则被引用的节点必须使用绝对路径，节点间使用“.”分隔，root表示根节点，格式为root开始的节点路径序列，例如root.foo.bar即为一个合法的绝对路径。
如果出现修改冲突（即多处修改同一个属性），编译器将提示warning，因为这种情况下只会生效某一个修改而导致最终结果不确定。

示例如下:
``

root {
    module = "sample";
    foo {
        foo_ :& root.bar{
            attr = "foo";
        }
        foo1 :& foo2 {
            attr = 0x2;
        }
        foo2 {
            attr = 0x1;
        }
    }

    bar {
        attr = "bar";
    }
}

假如下述示例保存在文件ref_update.hcs中，可以先生成二进制hcb文件，然后再反编译生成hcs文件，查看效果。其他示例均可采用编译、反编译的方式来查看HCS配置文件的实现效果。

hc-gen -b ref_update.hcs
hc-gen -d ref_update.hcb

生成反编译的文件ref_update.d.hcs，内容为：

/*
 * HDF decompile hcs file
 */
root {
    module = "sample";
    foo {
        foo2 {
            attr = 0x2;
        }
    }
    bar {
        attr = "foo";
    }
}

在以上示例中，可以看到foo.foo_节点通过引用将bar.attr属性的值修改为了"foo"，foo.foo1节点通过引用将foo.foo2.attr属性的值修改为了0x2。foo.foo_以及foo.foo1节点表示对目标节点内容的修改，其自身并不会存在最终生成的配置树中。

如果大家想更加深入的学习 OpenHarmony（鸿蒙南向）开发的全栈内容，不妨可以参考以下相关学习文档进行学习，助你快速提升自己：