1# Develop Guide
2
3## h2hdf工具使用场景
4
5在OpenHarmony系统中，上层应用或服务层通过调用HDF框架提供的HDI接口，能够以一种标准化和抽象化的方式与底层硬件设备进行交互。使用h2hdf工具，用户只需提供一个drivername，工具会自动生成整个框架的代码，包含驱动配置文件、idl接口、驱动程序driver和驱动服务框架。
6
7![image-20240724093743837](./figures/pic_code_frame.png)
8
9## h2hdf工具代码框架说明
10
11```
12h2hdf
13├── docs                                      # 文档
14│   ├── figures                               # 图片资源
15│   ├── usage.md                              # 使用文档
16│   ├── develop.md                            # 设计文档        
17├── src
18│   ├── templete                              # 模板文件
19│   │   ├── HcsconfigTemplete
20│   │   │   ├── hcsconfigTemplete.gen         # hcs配置模板
21│   │   ├── IdlInterfaceTemplete
22│   │   │   ├── buildgnTemplete.gen           # idl接口BUILD.gn模板
23│   │   │   ├── v4_1
24│   │   │   │   ├── bundlejsonTemplete.gen    # idl接口bundle.json模板
25│   │   │   ├── idlInterfaceTemplete.gen      # idl接口定义文件模板
26│   │   ├── PeripheralTemplete
27│   │   │   ├── DumpExampleTemplete           # dump示例
28│   │   │   │   ├── v4_1
29│   │   │   │   │   ├── buildgnTemplete.gen   # BUILD.gn模板
30│   │   │   │   ├── dumpCTemplete.gen         # dump实现示例模板
31│   │   │   │   ├── dumpHTemplete.gen         # dump h文件模板
32│   │   │   ├── HdiServiceTemplete            # hdi_service 模板
33│   │   │   │   ├── v4_1
34│   │   │   │   │   ├── buildgnTemplete.gen   # BUILD.gn模板
35│   │   │   │   ├── driverTemplete.gen        # driver模板
36│   │   │   │   ├── logHTemplte.gen           # 日志文件模板
37│   │   │   │   ├── serviceCppTemplete.gen    # 驱动服务模板
38│   │   │   │   ├── serviceHTemplete.gen      # 驱动服务 h 文件模板
39│   │   │   ├── buildgnTemplete.gen           # hdi service BUILD.gn模板
40│   │   │   ├── v4_1
41│   │   │   │   ├── bundlejsonTemplete.gen    # hdi service bundle.json模板
42│   │   ├── framework.json                    # 存储模板对应相对路径   
43│   ├── generate.js                           # 使用templete中对应的模板生成代码。
44│   ├── main.js                               # 工具入口文件,定义输入参数，调用generate.js来启动代码生成过程。
45├── package.json                              # Node.js打包配置文件
46```
47
48运行逻辑
49
50![image-20240724093743837](./figures/pic_code_process.png)
51
52main.js为脚本入口，其中使用stdio.getopt获取参数，其中，参数详情如下：
53
54  -n, drivername，例如：hello
55
56  -v, 可选参数，版本，默认为4.1
57
58  -o, 可选参数，默认为当前目录，指定生成框架代码输出路径。
59
60```
61let ops = stdio.getopt({
62    // 输入driver name ,输入一个字符串，默认为hello
63    'drivername': { key: 'n', args: 1, description: 'driver name', default: 'hello' },
64    // 输入版本号
65    'version': { key: 'v', args: 1, description: 'source version', default: '4.1' },
66    // 输出文件夹路径
67    'out': { key: 'o', args: 1, description: 'output directory', default: '' },
68});
69```
70
71对输入的参数值进行校验：checkInput对输入的drivername进行校验，输入的drivername必须符合命名规范；isValidValue对输入的版本号进行校验，输入的版本号必须包含在版本号数组中，该数组后续可持续更新：
72
73```
74...
75const allowedVersion = ['4.1'];
76function isValidValue(value, allowedVersion) {
77  return allowedVersion.includes(value);
78}
79
80function checkInput(input) {
81  const regex = /\b[a-zA-Z_][a-zA-Z0-9_]*\b/;
82  return regex.test(input);
83}
84```
85
86获取到每个模板的路径后，根据路径读取模板文件，并替换模板文件中的drivername等：
87
88```
89/* 根据用户输入的driver名字生成framework框架
90 * drivername:用户输入的驱动名，frameworkJson: 模板内容，out:生成框架路径
91 * 替换模板中的名字并写文件输出
92 */
93function genDriverFramework(driverName, frameworkJson, version, out = '') {
94  ...
95  // 生成Hcs配置文件
96  genHcsconfigFile(frameworkJson, driverName, frameworkPath);
97  // 生成Idl接口
98  genInterface(frameworkPath, frameworkJson, rootInfo);
99  // 生成hdi_service
100  genPeripheral(frameworkPath, frameworkJson, rootInfo);
101}
102```
103
104## 开发指导
105
106### 适配新版本
107
108适配新版本的步骤如下：
109
1101.在main.js中，在allowedVersion数组中加入适配的版本号，其中版本号需统一写法，如4.1
111
1122.在templete目录下，IdlInterfaceTemplete目录下新建适配版本文件夹，如v4_1，在适配版本文件夹下新增bundle.json模板，在 Periphheral, Periphheral/DumpExampleTemplete, Periphheral/HdiServiceTemplete新增适配版本文件夹，在适配版本下新增对应的BUILD.gn模板，并在framework.json中新增版本的bundle.json,BUILD.gn模板路径。
113
1143.在generate.js中，在genInterface方法、genExampleDumpfile方法、genHdiService方法、genBuildFile方法中修改相应代码：当rootInfo.version为新增版本时，替换对应的BUILD.gn, bundle.json模板路径。
115
1164.适配新版本增加其它配置时，可在templete目录下增加配置模板，并在framework.json中增加配置文件模板的路径，然后在generate.js中替换模板并生成配置文件。
117
118## Roadmap
119
120| 工作目标                      | 工作内容                                                     | 验收要求                                                     | 时间节点         |
121| ----------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ---------------- |
122| 支持一个简单的sample_host模板 | 根据工具基于OpenHarmony4.1源码，编写脚本生成Hdf框架模板，其中包括hcsconfig模板，idl接口模板，peripheral模板 | 生成之后可动态加载Host，并能使用Hidump查看日志，打印出"hello word!" | 2024.8（已完成） |
123| 完善host模板                  | 增加testapp测试程序；完善模板中hitrace日志跟踪定位工具的使用；模板中增加死亡监听：客户端监听服务端消亡、服务端监听客户端消亡、服务端监听底层HDI侧消亡 | 驱动host能随镜像起来，服务端/客户端/HDI侧消亡时能打印出日志；检测接口被调用时打印hitrace日志 | 2024.10          |
124| 适配5.0                       | 适配5.0release版本                                           | 适配5.0时，可以编译出对应版本的工具，且编译验证成功          | 2024.11          |
125
126