OpenHarmony HDF 配置管理分析及使用
51CTO和華為官方合作共建的鴻蒙技術(shù)社區(qū)
HDF配置管理概述
HCS(HDF Configuration Source)是 HDF 驅(qū)動(dòng)框架的配置描述源碼，內(nèi)容以 KeyValue 為主要形式。它實(shí)現(xiàn)了配置代碼與驅(qū)動(dòng)代碼解耦，便于開發(fā)者進(jìn)行配置管理。
HC-GEN(HDF Configuration Generator)是 HCS 配置轉(zhuǎn)換工具，可以將 HDF 配置文件轉(zhuǎn)換為軟件可讀取的文件格式：
- 在弱性能環(huán)境中，轉(zhuǎn)換為配置樹源碼，驅(qū)動(dòng)可直接調(diào)用 C 代碼獲取配置。
- 在高性能環(huán)境中，轉(zhuǎn)換為 HCB(HDF Configuration Binary)二進(jìn)制文件，驅(qū)動(dòng)可使用 HDF 框架提供的配置解析接口獲取配置。
以下是使用 HCB 模式的典型應(yīng)用場(chǎng)景：
圖1 配置使用流程圖
HCS 經(jīng)過 HC-GEN 編譯生成 HCB 文件，HDF 驅(qū)動(dòng)框架中的 HCS Parser 模塊會(huì)從 HCB 文件中重建配置樹，HDF 驅(qū)動(dòng)模塊使用 HCS Parser 提供的配置讀取接口獲取配置內(nèi)容。
圖2 HCS的架構(gòu)圖
HCS 文本更適合人類閱讀，但是并不方便程序直接存取，所以經(jīng)過 HC-GEN 編譯，輸出二進(jìn)制的 HCB 數(shù)據(jù)。HCB 在編譯后打包進(jìn)內(nèi)核鏡像的.rodata 只讀分區(qū)，在啟動(dòng)加載時(shí)，框架定位到 HCB 數(shù)據(jù)頭，再將二進(jìn)制數(shù)據(jù)重新構(gòu)造為樹形數(shù)據(jù)結(jié)構(gòu)供驅(qū)動(dòng)查詢和讀取。下面詳細(xì)分析 HC-GEN 實(shí)現(xiàn)。
HCS源碼語法
HCS 的語法介紹如下：
關(guān)鍵字
HCS 配置語法保留了以下關(guān)鍵字。
基本結(jié)構(gòu)
HCS 主要分為屬性(Attribute)和節(jié)點(diǎn)(Node)兩種結(jié)構(gòu)。
屬性
屬性即最小的配置單元，是一個(gè)獨(dú)立的配置項(xiàng)。語法如下：
- attribute_name = value;
attribute_name 是字母、數(shù)字、下劃線的組合且必須以字母或下劃線開頭，字母區(qū)分大小寫。
value 的可用格式如下：
- 數(shù)字常量，支持二進(jìn)制、八進(jìn)制、十進(jìn)制、十六進(jìn)制數(shù)，具體參考數(shù)據(jù)類型節(jié)。
- 字符串，內(nèi)容使用雙引號(hào)(“”)引用。
- 節(jié)點(diǎn)引用。
- attribute 必須以分號(hào)(;)結(jié)束且必須屬于一個(gè) node。
節(jié)點(diǎn)
節(jié)點(diǎn)是一組屬性的集合，語法如下：
- node_name {
- module = "sample";
- ...
- }
- node_name 是字母、數(shù)字、下劃線的組合且必須以字母或下劃線開頭，字母區(qū)分大小寫。
- 大括號(hào)后無需添加結(jié)束符“;”。
- root為保留關(guān)鍵字，用于聲明配置表的根節(jié)點(diǎn)。每個(gè)配置表必須以 root 節(jié)點(diǎn)開始。
- root 節(jié)點(diǎn)中必須包含 module 屬性，其值應(yīng)該為一個(gè)字符串，用于表征該配置所屬模塊。
- 節(jié)點(diǎn)中可以增加 match_attr 屬性，其值為一個(gè)全局唯一的字符串。在解析配置時(shí)可以調(diào)用查找接口以該屬性的值查找到包含該屬性的節(jié)點(diǎn)。
數(shù)據(jù)類型
整型
整型長(zhǎng)度自動(dòng)推斷，根據(jù)實(shí)際數(shù)據(jù)長(zhǎng)度給與最小空間占用的類型。
- 二進(jìn)制，0b 前綴，示例：0b1010。
- 八進(jìn)制，0 前綴，示例：0664。
- 十進(jìn)制 ，無前綴，且支持有符號(hào)與無符號(hào)，示例：1024，+1024 均合法。負(fù)值在讀取時(shí)注意使用有符號(hào)數(shù)讀取接口。
- 十六進(jìn)制，0x 前綴，示例：0xff00、0xFF。
字符串
字符串使用雙引號(hào)(“”)表示。
數(shù)組
數(shù)組元素支持整型、字符串，不支持混合類型。整型數(shù)組中 uint32_t uint64_t 混用會(huì)向上轉(zhuǎn)型為 uint64_t 數(shù)組。整型數(shù)組與字符串?dāng)?shù)組示例如下：
- attr_foo = [0x01, 0x02, 0x03, 0x04];
- attr_bar = ["hello", "world"];
bool類型
bool 類型中 true 表示真，false 表示假。
注釋
HCS 支持兩種注釋風(fēng)格。
單行注釋：
- 1. // comment
多行注釋：
- /*
- comment
- */
其他語法
模板
模板的用途在于生成嚴(yán)格一致的 node 結(jié)構(gòu)，以便對(duì)同類型 node 進(jìn)行遍歷和管理。
使用 template 關(guān)鍵字定義模板 node，子 node 通過雙冒號(hào)“::”聲明繼承關(guān)系。子節(jié)點(diǎn)可以改寫但不能新增和刪除 template 中的屬性，子節(jié)點(diǎn)中沒有定義的屬性將使用 template 中的定義作為默認(rèn)值。示例如下：
- 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 節(jié)點(diǎn)繼承了 foo 節(jié)點(diǎn)，生成配置樹節(jié)點(diǎn)結(jié)構(gòu)與 foo 保持了完全一致，只是屬性的值不同。
引用修改
引用修改可以實(shí)現(xiàn)修改另外任意一個(gè)節(jié)點(diǎn)的內(nèi)容，語法為：
- node :& source_node
上述語句表示 node 中的內(nèi)容是對(duì) source_node 節(jié)點(diǎn)內(nèi)容的修改。示例如下：
- 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_節(jié)點(diǎn)通過引用將 bar.attr 屬性的值修改為了"foo"，foo.foo1 節(jié)點(diǎn)通過引用將 foo.foo2.attr 屬性的值修改為了 0x2。foo.foo_以及 foo.foo1 節(jié)點(diǎn)表示對(duì)目標(biāo)節(jié)點(diǎn)內(nèi)容的修改，其自身并不會(huì)存在最終生成的配置樹中。
引用同級(jí) node，可以直接使用 node 名稱，否則被引用的節(jié)點(diǎn)必須使用絕對(duì)路徑，節(jié)點(diǎn)間使用“.”分隔，root 表示根節(jié)點(diǎn)，格式為 root 開始的節(jié)點(diǎn)路徑序列，例如 root.foo.bar 即為一個(gè)合法的絕對(duì)路徑。
如果出現(xiàn)修改沖突(即多處修改同一個(gè)屬性)，編譯器將提示 warning，因?yàn)檫@種情況下只會(huì)生效某一個(gè)修改而導(dǎo)致最終結(jié)果不確定。
節(jié)點(diǎn)復(fù)制
節(jié)點(diǎn)復(fù)制可以實(shí)現(xiàn)在節(jié)點(diǎn)定義時(shí)從另一個(gè)節(jié)點(diǎn)先復(fù)制內(nèi)容，用于定義內(nèi)容相似的節(jié)點(diǎn)。語法為：
- node : source_node
上述語句表示在定義"node"節(jié)點(diǎn)時(shí)將另一個(gè)節(jié)點(diǎn)"source_node"的屬性復(fù)制過來。示例如下：
- 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 節(jié)點(diǎn)即包含 attr_0 屬性也包含 attr_1 屬性，在 bar 中對(duì) attr_0 的修改不會(huì)影響到 foo。
在 foo 和 bar 在同級(jí) node 中可不指定 foo 的路徑，否則需要使用絕對(duì)路徑引用。
刪除
要對(duì) include 導(dǎo)入的 base 配置樹中不需要的節(jié)點(diǎn)或?qū)傩赃M(jìn)行刪除，可以使用 delete 關(guān)鍵字。下面的舉例中 sample1.hcs 通過 include 導(dǎo)入了 sample2.hcs 中的配置內(nèi)容，并使用 delete 刪除了 sample2.hcs 中的 attribute2 屬性和 foo_2 節(jié)點(diǎn)，示例如下：
- #include "sample1.hcs"
- root {
- attr_2 = delete;
- foo_2 : delete {
- }
}
屬性引用
為了在解析配置時(shí)快速定位到關(guān)聯(lián)的節(jié)點(diǎn)，可以把節(jié)點(diǎn)作為屬性的右值，通過讀取屬性查找到對(duì)應(yīng)節(jié)點(diǎn)。語法為：
- attribute = &node；
HCB二進(jìn)制格式
HCB 為便于程序讀取的 HCS 的二進(jìn)制數(shù)據(jù)格式，按照下面的編碼表進(jìn)行數(shù)據(jù)組織：
以一個(gè)示例分析下 HCS 源碼和 HCB 的對(duì)應(yīng)關(guān)系：
- root {
- module = "sample";
- gpio = [1, 2];
- }
上述 HCS 編譯后的 HCB 數(shù)據(jù)如下：
HC-GEN使用介紹
hc-gen 是 HCS 的編譯器，用于在編譯時(shí)將 HCS 轉(zhuǎn)化為 HCB，也可以將 HCB 反編譯為 HCS 以驗(yàn)證配置數(shù)據(jù)的正確性，這在驅(qū)動(dòng)調(diào)試時(shí)將很有幫助。
hc-gen v0.7 之前版本作為 prebuilt 文件以二進(jìn)制下載方式提供。0.7 版本開始，為了更好的支持多環(huán)境部署和版本管理，hc-gen 在編譯過程中從源碼構(gòu)建。如果調(diào)試需要，可以在 OpenHarmony 源碼的 drivers/framework/tools/hc-gen 下執(zhí)行 make 生成，生成產(chǎn)物在該目錄的 build 子目錄中。
- cd drivers/framework/tools/hc-gen
- make
- ./build/hc-gen –v
- > Hcs compiler 0.7
驅(qū)動(dòng)開發(fā)過程中，在 hcs 配置文件修改后，可以手動(dòng)使用 hc-gen 快速驗(yàn)證配置的正確性，生成 HCB 配置文件方法：
- hcgen o [OutputHcbFileName] b [SourceHcsFileName]
在驅(qū)動(dòng)調(diào)試時(shí)，可以使用 hc-gen 反編譯 HCB 文件獲得 HCS 源碼，進(jìn)行配置數(shù)據(jù)核對(duì)。反編譯 HCB 文件為 HCS 方法：
- hcgen o [OutputHcsFileName] d [SourceHcbFileName]
HCS文件編譯過程
在 linux 內(nèi)核中，HCS 編譯基于 KBuild 自定義規(guī)則實(shí)現(xiàn)自主的編譯過程，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為根據(jù)目標(biāo)平臺(tái)和產(chǎn)品拼接出的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生成規(guī)則覆蓋KBbuild默認(rèn)規(guī)則
- $(obj)/$(HCS_OBJ): $(CONFIG_GEN_HEX_SRC)
- $(Q)$(CC) $(c_flags) -c -o $@ $<
- $(Q)rm -f $<
- # 將HCB文件生成后再轉(zhuǎn)換為.c文件中的hex數(shù)組，依賴目標(biāo)為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 適配其他平臺(tái)時(shí)，可以復(fù)用該 Makefile，核心變化點(diǎn)在正確配置對(duì)應(yīng)平臺(tái)的 HCS 根路徑。
HCS配置使用
HCS配置讀取接口
在驅(qū)動(dòng)實(shí)現(xiàn)中，可以使用 device_resource_if.h 中定義的接口對(duì)配置進(jìn)行查詢和讀取。常用 API 介紹如下：
配置讀取接口使用實(shí)例
以 UART 控制器驅(qū)動(dòng)為例看 HCS 的使用。UART 在 HCS 中 device_info.hcs 中配置的設(shè)備信息為：
- 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 特性，這樣驅(qū)動(dòng)框架在 device_uart 設(shè)備加載時(shí)將自動(dòng)將 device_uart_0x0000 節(jié)點(diǎn)關(guān)聯(lián)到該設(shè)備。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 節(jié)點(diǎn)被自動(dòng)關(guān)聯(lián)到了 HdfDeviceObject 的 property 成員。使用 DeviceResourceGetIfaceInstance 接口獲取到 HCS 接口實(shí)例后調(diào)用其成員方法 GetUint32 讀取名為"num"的無符號(hào)值屬性，使用 GetString 接口讀取名為"driver_name"的字符串屬性。從配置中獲取到屬性值后，再根據(jù)配置值完成相關(guān)軟硬件的初始化。
總結(jié)
本文從全景介紹了 HCS 配置管理方案，重點(diǎn)分析了 HC-GEN 的實(shí)現(xiàn)和 HCS 的編譯過程，希望對(duì)讀者理解 HCS 的原理和配置方法能有所幫助。關(guān)于 HDF 驅(qū)動(dòng)框架的更多分析，請(qǐng)關(guān)注后續(xù)文章。
51CTO和華為官方合作共建的鴻蒙技術(shù)社區(qū)
