凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動
一、案例簡介
該程序是基于OpenHarmony標準系統編寫的基礎外設類：簡易HDF驅動。
目前已在凌蒙派-RK3568開發板跑通。
詳細資料請參考官網：https://gitee.com/Lockzhiner-Electronics/lockzhiner-rk3568-openharmony。
二、基礎知識
1、OpenHarmony HDF開發簡介
HDF（Hardware Driver Foundation）驅動框架，為驅動開發者提供驅動框架能力，包括驅動加載、驅動服務管理、驅動消息機制和配置管理。旨在構建統一的驅動架構平臺，為驅動開發者提供更精準、更高效的開發環境，力求做到一次開發，多系統部署。
2、OpenHarmony HDF驅動開發
HDF（Hardware Driver Foundation）框架以組件化的驅動模型作為核心設計思路，為開發者提供更精細化的驅動管理，讓驅動開發和部署更加規范。HDF框架將一類設備驅動放在同一個Host（設備容器）里面，用于管理一組設備的啟動加載等過程。在劃分Host時，驅動程序是部署在一個Host還是部署在不同的Host，主要考慮驅動程序之間是否存在耦合性，如果兩個驅動程序之間存在依賴，可以考慮將這部分驅動程序部署在一個Host里面，否則部署到獨立的Host中是更好的選擇。Device對應一個真實的物理設備。DeviceNode是設備的一個部件，Device至少有一個DeviceNode。每個DeviceNode可以發布一個設備服務。驅動即驅動程序，每個DevicdNode唯一對應一個驅動，實現和硬件的功能交互。
3、OpenHarmony HDF驅動加載
HDF驅動框架提供把和配置的設備列表匹配成功的驅動程序加載起來的功能。
支持按需加載和按序加載兩種策略，具體設備的加載策略由配置文件中的preload字段來控制，配置值參考如下：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
（1）按需加載
- preload字段配置為0（DEVICE_PRELOAD_ENABLE），則系統啟動過程中默認加載。
- preload字段配置為1（DEVICE_PRELOAD_ENABLE_STEP2），當系統支持快速啟動的時候，則在系統完成之后再加載這一類驅動，否則和DEVICE_PRELOAD_ENABLE含義相同。
- preload字段配置為2（DEVICE_PRELOAD_DISABLE），則系統啟動過程中默認不加載，支持后續動態加載，當用戶態獲取驅動服務時，如果驅動服務不存在，HDF框架會嘗試動態加載該驅動。
（2）按序加載（默認加載策略）
配置文件中的priority（取值范圍為整數0到200）是用來表示host（驅動容器）和驅動的優先級。不同的host內的驅動，host的priority值越小，驅動加載優先級越高；同一個host內驅動的priority值越小，加載優先級越高。
4、OpenHarmony HDF驅動服務管理
驅動服務是HDF驅動設備對外提供能力的對象，由HDF框架統一管理。驅動服務管理主要包含驅動服務的發布和獲取。
（1）驅動服務的發布策略
HDF框架定義了驅動對外發布服務的策略，由配置文件中的policy字段來控制，policy字段的取值范圍以及含義如下：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
（2）驅動服務的接口說明
針對驅動服務管理功能，HDF框架開放了以下接口供開發者調用，如下表所示：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
5、驅動消息機制管理
當用戶態應用和內核態驅動需要交互時，可以使用HDF框架的消息機制來實現。
消息機制的功能主要有以下兩種：
- 用戶態應用發送消息到驅動。
- 用戶態應用接收驅動主動上報事件。
消息機制接口如下所示：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
6、配置樹配置
HCS（HDF Configuration Source）是HDF驅動框架的配置描述源碼，內容以Key-Value為主要形式。它實現了配置代碼與驅動代碼解耦，便于開發者進行配置管理。
HC-GEN（HDF Configuration Generator）是HCS配置轉換工具，可以將HDF配置文件轉換為軟件可讀取的文件格式：
- 在弱性能環境中，轉換為配置樹源碼或配置樹宏定義，驅動可直接調用C代碼或宏式APIs獲取配置。
- 在高性能環境中，轉換為HCB（HDF Configuration Binary）二進制文件，驅動可使用HDF框架提供的配置解析接口獲取配置。
HCS經過HC-GEN編譯生成HCB文件，HDF驅動框架中的HCS Parser模塊會從HCB文件中重建配置樹，HDF驅動模塊使用HCS Parser提供的配置讀取接口獲取配置內容。
三、代碼解析
1、配置文件
（1）device_info.hcs
創建config/device_info.hcs，用于驅動設備描述，具體內容如下：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
注意：
- device_rk3568_sample：為配置樹的類設備結點。
- deviceMatchAttr：關鍵字必須與config.hcs的match_attr匹配。
（2）config.hcs
創建config/config.hcs，用于定義私有變量，具體內容如下：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
由于我們沒有用到其他私有變量，故不做定義。
（3）參與配置樹編譯
編輯//vendor/lockzhiner/rk3568/hdf_config/khdf/hdf.hcs，將device_info.hcs添加配置樹中。具體內容如下所示：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
2、HDF驅動
（1）driver_hdf_sample.c
頭文件
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
定義打印標簽
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
建議讀者用HDF_LOGI、HDF_LOGE等打印信息。
驅動初始化
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
驅動釋放
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
驅動綁定
將驅動對外提供的服務能力接口綁定到HDF框架，通過struct IDeviceIoService設置Dispatch函數。
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
HdfSampleDriverDispatch()掛載載struct IDeviceIoService的函數指針成員Dispatch，它相當于Linux的ioctl，可與應用程序進行數據交互。
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
驅動注冊
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
（2）Makefile
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
（3）參與Linux內核編譯
編輯//drivers/hdf_core/adapter/khdf/linux/Makefile，添加一段代碼，將sample驅動參與Linux內核編譯中。具體如下所示：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
3、應用程序
（1）sample_test.c
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
（2）BUILD.gn
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
（3）參與應用程序編譯
編輯//vendor/lockzhiner/rk3568/samples/BUILD.gn，開啟sample編譯。具體如下：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
四、編譯說明
建議使用docker編譯方法，運行如下：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
五、運行結果
該程序運行結果如下所示：
凌蒙派-RK3568開發板-基礎外設類：簡易HDF驅動-開源基礎軟件社區
