OpenHarmony HDF 配置管理分析及使用
HDF配置管理概述
HCS(HDF Configuration Source)是 HDF 驅動框架的配置描述源碼，內容以 KeyValue 為主要形式。它實現了配置代碼與驅動代碼解耦，便于開發者進行配置管理。
HC-GEN(HDF Configuration Generator)是 HCS 配置轉換工具，可以將 HDF 配置文件轉換為軟件可讀取的文件格式：
- 在弱性能環境中，轉換為配置樹源碼，驅動可直接調用 C 代碼獲取配置。
- 在高性能環境中，轉換為 HCB(HDF Configuration Binary)二進制文件，驅動可使用 HDF 框架提供的配置解析接口獲取配置。
以下是使用 HCB 模式的典型應用場景：
圖1 配置使用流程圖
HCS 經過 HC-GEN 編譯生成 HCB 文件，HDF 驅動框架中的 HCS Parser 模塊會從 HCB 文件中重建配置樹，HDF 驅動模塊使用 HCS Parser 提供的配置讀取接口獲取配置內容。
圖2 HCS的架構圖
HCS 文本更適合人類閱讀，但是并不方便程序直接存取，所以經過 HC-GEN 編譯，輸出二進制的 HCB 數據。HCB 在編譯后打包進內核鏡像的.rodata 只讀分區，在啟動加載時，框架定位到 HCB 數據頭，再將二進制數據重新構造為樹形數據結構供驅動查詢和讀取。下面詳細分析 HC-GEN 實現。
HCS源碼語法
HCS 的語法介紹如下：
關鍵字
HCS 配置語法保留了以下關鍵字。
基本結構
HCS 主要分為屬性(Attribute)和節點(Node)兩種結構。
屬性
屬性即最小的配置單元，是一個獨立的配置項。語法如下：
- attribute_name = value;
attribute_name 是字母、數字、下劃線的組合且必須以字母或下劃線開頭，字母區分大小寫。
value 的可用格式如下：
- 數字常量，支持二進制、八進制、十進制、十六進制數，具體參考數據類型節。
- 字符串，內容使用雙引號(“”)引用。
- 節點引用。
- attribute 必須以分號(;)結束且必須屬于一個 node。
節點
節點是一組屬性的集合，語法如下：
- node_name {
- module = "sample";
- ...
- }
- node_name 是字母、數字、下劃線的組合且必須以字母或下劃線開頭，字母區分大小寫。
- 大括號后無需添加結束符“;”。
- root為保留關鍵字，用于聲明配置表的根節點。每個配置表必須以 root 節點開始。
- root 節點中必須包含 module 屬性，其值應該為一個字符串，用于表征該配置所屬模塊。
- 節點中可以增加 match_attr 屬性，其值為一個全局唯一的字符串。在解析配置時可以調用查找接口以該屬性的值查找到包含該屬性的節點。
數據類型
整型
整型長度自動推斷，根據實際數據長度給與最小空間占用的類型。
- 二進制，0b 前綴，示例：0b1010。
- 八進制，0 前綴，示例：0664。
- 十進制 ，無前綴，且支持有符號與無符號，示例：1024，+1024 均合法。負值在讀取時注意使用有符號數讀取接口。
- 十六進制，0x 前綴，示例：0xff00、0xFF。
字符串
字符串使用雙引號(“”)表示。
數組
數組元素支持整型、字符串，不支持混合類型。整型數組中 uint32_t uint64_t 混用會向上轉型為 uint64_t 數組。整型數組與字符串數組示例如下：
- attr_foo = [0x01, 0x02, 0x03, 0x04];
- attr_bar = ["hello", "world"];
bool類型
bool 類型中 true 表示真，false 表示假。
注釋
HCS 支持兩種注釋風格。
單行注釋：
- 1. // comment
多行注釋：
- /*
- comment
- */
其他語法
模板
模板的用途在于生成嚴格一致的 node 結構，以便對同類型 node 進行遍歷和管理。
使用 template 關鍵字定義模板 node，子 node 通過雙冒號“::”聲明繼承關系。子節點可以改寫但不能新增和刪除 template 中的屬性，子節點中沒有定義的屬性將使用 template 中的定義作為默認值。示例如下：
- root {
- module = "sample";
- template foo {
- attr_1 = 0x1;
- attr_2 = 0x2;
- }
- bar :: foo {
- }
- bar_1 :: foo {
- attr_1 = 0x2;
- }
- }
生成配置樹如下：
- root {
- module = "sample";
- bar {
- attr_1 = 0x1;
- attr_2 = 0x2;
- }
- bar_1 {
- attr_1 = 0x2;
- attr_2 = 0x2;
- }
- }
在上述示例中，bar 和 bar_1 節點繼承了 foo 節點，生成配置樹節點結構與 foo 保持了完全一致，只是屬性的值不同。
引用修改
引用修改可以實現修改另外任意一個節點的內容，語法為：
- node :& source_node
上述語句表示 node 中的內容是對 source_node 節點內容的修改。示例如下：
- root {
- module = "sample";
- foo {
- foo_ :& root.bar{
- attr = "foo";
- }
- foo1 :& foo2 {
- attr = 0x2;
- }
- foo2 {
- attr = 0x1;
- }
- }
- bar {
- attr = "bar";
- }
- }
最終生成配置樹為：
- 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 節點表示對目標節點內容的修改，其自身并不會存在最終生成的配置樹中。
引用同級 node，可以直接使用 node 名稱，否則被引用的節點必須使用絕對路徑，節點間使用“.”分隔，root 表示根節點，格式為 root 開始的節點路徑序列，例如 root.foo.bar 即為一個合法的絕對路徑。
如果出現修改沖突(即多處修改同一個屬性)，編譯器將提示 warning，因為這種情況下只會生效某一個修改而導致最終結果不確定。
節點復制
節點復制可以實現在節點定義時從另一個節點先復制內容，用于定義內容相似的節點。語法為：
- node : source_node
上述語句表示在定義"node"節點時將另一個節點"source_node"的屬性復制過來。示例如下：
- root {
- module = "sample";
- foo {
- attr_0 = 0x0;
- }
- bar:foo {
- attr_1 = 0x1;
- }
- }
上述代碼的最終生成配置樹為：
- root {
- module = "sample";
- foo {
- attr_0 = 0x0;
- }
- bar {
- attr_1 = 0x1;
- attr_0 = 0x0;
- }
- }
在上述示例中，編譯后 bar 節點即包含 attr_0 屬性也包含 attr_1 屬性，在 bar 中對 attr_0 的修改不會影響到 foo。
在 foo 和 bar 在同級 node 中可不指定 foo 的路徑，否則需要使用絕對路徑引用。
刪除
要對 include 導入的 base 配置樹中不需要的節點或屬性進行刪除，可以使用 delete 關鍵字。下面的舉例中 sample1.hcs 通過 include 導入了 sample2.hcs 中的配置內容，并使用 delete 刪除了 sample2.hcs 中的 attribute2 屬性和 foo_2 節點，示例如下：
- #include "sample1.hcs"
- root {
- attr_2 = delete;
- foo_2 : delete {
- }
}
屬性引用
為了在解析配置時快速定位到關聯的節點，可以把節點作為屬性的右值，通過讀取屬性查找到對應節點。語法為：
- attribute = &node；
HCB二進制格式
HCB 為便于程序讀取的 HCS 的二進制數據格式，按照下面的編碼表進行數據組織：
以一個示例分析下 HCS 源碼和 HCB 的對應關系：
- root {
- module = "sample";
- gpio = [1, 2];
- }
上述 HCS 編譯后的 HCB 數據如下：
HC-GEN使用介紹
hc-gen 是 HCS 的編譯器，用于在編譯時將 HCS 轉化為 HCB，也可以將 HCB 反編譯為 HCS 以驗證配置數據的正確性，這在驅動調試時將很有幫助。
hc-gen v0.7 之前版本作為 prebuilt 文件以二進制下載方式提供。0.7 版本開始，為了更好的支持多環境部署和版本管理，hc-gen 在編譯過程中從源碼構建。如果調試需要，可以在 OpenHarmony 源碼的 drivers/framework/tools/hc-gen 下執行 make 生成，生成產物在該目錄的 build 子目錄中。
- cd drivers/framework/tools/hc-gen
- make
- ./build/hc-gen –v
- > Hcs compiler 0.7
驅動開發過程中，在 hcs 配置文件修改后，可以手動使用 hc-gen 快速驗證配置的正確性，生成 HCB 配置文件方法：
- hcgen o [OutputHcbFileName] b [SourceHcsFileName]
在驅動調試時，可以使用 hc-gen 反編譯 HCB 文件獲得 HCS 源碼，進行配置數據核對。反編譯 HCB 文件為 HCS 方法：
- hcgen o [OutputHcsFileName] d [SourceHcbFileName]
HCS文件編譯過程
在 linux 內核中，HCS 編譯基于 KBuild 自定義規則實現自主的編譯過程，Makefile 入口在 drivers/adapter/khdf/linux/hcs/Makefile。
- HC_GEN_DIR := $(abspath $(SOURCE_ROOT)/drivers/framework/tools/hc-gen)
- HC_GEN := $(HC_GEN_DIR)/build/hc-gen
- LOCAL_HCS_ROOT := $(abspath $(dir $(realpath $(lastword $(MAKEFILE_LIST)))))
- # LOCAL_HCS_ROOT為根據目標平臺和產品拼接出的HCS路徑
- HCS_DIR := $(LOCAL_HCS_ROOT)
- HCB_FLAGS := -b -i -a
- HCS_OBJ := hdf_hcs_hex.o
- HCS_OBJ_SRC := $(subst .o,.c,$(notdir $(HCS_OBJ)))
- CONFIG_GEN_HEX_SRC := $(addprefix $(LOCAL_HCS_ROOT)/, $(HCS_OBJ_SRC))
- CONFIG_HCS_SRC := $(subst _hcs_hex.o,.hcs,$(addprefix $(HCS_DIR)/, $(HCS_OBJ)))
- # 使用自定義的.o生成規則覆蓋KBbuild默認規則
- $(obj)/$(HCS_OBJ): $(CONFIG_GEN_HEX_SRC)
- $(Q)$(CC) $(c_flags) -c -o $@ $<
- $(Q)rm -f $<
- # 將HCB文件生成后再轉換為.c文件中的hex數組，依賴目標為hc-gen工具
- $(CONFIG_GEN_HEX_SRC): $(LOCAL_HCS_ROOT)/%_hcs_hex.c: $(HCS_DIR)/%.hcs | $(HC_GEN)
- $(Q)echo gen hdf built-in config
- $(Q)if [ ! -d $(dir $@) ]; then mkdir -p $(dir $@); fi
- $(Q)$(HC_GEN) $(HCB_FLAGS) -o $(subst _hex.c,,$(@)) $<
- # 生成hc-gen工具
- $(HC_GEN):
- $(Q)make -C $(HC_GEN_DIR)
- obj-$(CONFIG_DRIVERS_HDF) += $(HCS_OBJ)
在 HDF 適配其他平臺時，可以復用該 Makefile，核心變化點在正確配置對應平臺的 HCS 根路徑。
HCS配置使用
HCS配置讀取接口
在驅動實現中，可以使用 device_resource_if.h 中定義的接口對配置進行查詢和讀取。常用 API 介紹如下：
配置讀取接口使用實例
以 UART 控制器驅動為例看 HCS 的使用。UART 在 HCS 中 device_info.hcs 中配置的設備信息為：
- device_uart :: device {
- device0 :: deviceNode {
- policy = 1;
- priority = 40;
- permission = 0644;
- moduleName = "HDF_PLATFORM_UART";
- serviceName = "HDF_PLATFORM_UART_0";
- deviceMatchAttr = "hisilicon_hi35xx_uart_0";
- }
- }
在 hi35xx_uart_config.hcs 中配置如下：
- root {
- platform {
- uart_config {
- device_uart_0x0000 {
- serviceName = "";
- match_attr = "hisilicon_hi35xx_uart_0";
- driver_name = "ttyAMA";
- num = 0;
- }
- }
- }
- }
注意到 UART 使用了 match_attr 特性，這樣驅動框架在 device_uart 設備加載時將自動將 device_uart_0x0000 節點關聯到該設備。UART 的配置解析代碼如下：
- static int32_t HdfUartInit(struct HdfDeviceObject *obj)
- {
- int32_t ret;
- struct DeviceResourceIface *iface = NULL;
- …
- devResourceIface = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE);
- if (devResourceIface == NULL) {
- HDF_LOGE("%s: face is invalid", __func__);
- return HDF_FAILURE;
- }
- devResourceIface->GetUint32(obj->property, "num", &host->num, 0);
- devResourceIface->GetString(obj->property, "driver_name", &drName, "ttyAMA")；
- ……
- ret = memcpy_s(g_driverName, UART_NAME_LEN - 1, drName, strlen(drName));
- if (ret != EOK) {
- return HDF_FAILURE;
- }
- host->method = &g_uartHostMethod;
- return HDF_SUCCESS;
- }
device_uart_0x0000 節點被自動關聯到了 HdfDeviceObject 的 property 成員。使用 DeviceResourceGetIfaceInstance 接口獲取到 HCS 接口實例后調用其成員方法 GetUint32 讀取名為"num"的無符號值屬性，使用 GetString 接口讀取名為"driver_name"的字符串屬性。從配置中獲取到屬性值后，再根據配置值完成相關軟硬件的初始化。
總結
本文從全景介紹了 HCS 配置管理方案，重點分析了 HC-GEN 的實現和 HCS 的編譯過程，希望對讀者理解 HCS 的原理和配置方法能有所幫助。關于 HDF 驅動框架的更多分析，請關注后續文章。
