README.md
1# Peripheral Driver HDI Definition
2
3## Introduction
4
5This repository is used to manage the hardware device interface (HDI) definition of each module. The HDIs are defined in the interface definition language (IDL) and saved in the `.idl` format.
6
7
8**Figure 1** HDI definition process
9
10
11
12Define an HDI in the IDL and saved it in the `.idl` format. Then, the `.idl` file will be compiled and converted into the function interface declaration and IPC-related process code in C or C++. You only need to implement service functionalities based on the `ifoo.h` generated. The `//drivers/adapter/uhdf2/hdi.gni` template integrates code generation and compilation. You can write the `BUILD.gn` file based on this template to generate client and server code and compile the code into a shared library (.so file).
13
14## Directory Structure
15
16```
17├── README.en.md
18├── README.md
19├── sensor # Sensor HDI definition.
20│ └── v1_0 # Sensor HDI v1.0 definition.
21│ ├── BUILD.gn # Sensor idl build script.
22│ ├── ISensorCallback.idl # Sensor callback interface definition.
23│ ├── ISensorInterface.idl # Sensor interface definition.
24│ └── SensorTypes.idl # Sensor data type definition.
25├── audio # Audio HDI definition.
26│ └── ...
27├── camera # Camera HDI definition.
28├── codec # Codec HDI definition.
29├── display # Display HDI definition.
30├── format # Format HDI definition.
31├── input # Input HDI definition.
32├── misc # Miscellaneous HDI definition.
33├── usb # USB HDI definition.
34└── wlan # WLAN HDI definition.
35```
36
37## How to Use
38
391. Create an `.idl` file in the IDL.
40
41 - Create the module/version interface directory by referring to the directory structure. The initial version is defined as `v1_0`, for example, `drivers/interface/foo/v1.0/`.
42
43 - Define the interface `IFoo.idl`.
44 ```
45 package ohos.hdi.foo.v1_0;
46
47 import ohos.hdi.foo.v1_0.IFooCallback;
48 import ohos.hdi.foo.v1_0.MyTypes;
49
50 interface IFoo {
51 Ping([in] String sendMsg, [out] String recvMsg);
52
53 GetData([out] struct FooInfo info);
54
55 SendCallbackObj([in] IFooCallback cbObj);
56 }
57 ```
58 - If customized data types are used in `interface`, define the data types in `MyTypes.idl`.
59 ```
60 package ohos.hdi.foo.v1_0;
61
62 enum FooType {
63 FOO_TYPE_ONE = 1,
64 FOO_TYPE_TWO,
65 };
66
67 struct FooInfo {
68 unsigned int id;
69 String name;
70 enum FooType type;
71 };
72 ```
73 - If a callback from the server is required, define the callback class `IFooCallback.idl`.
74 ```
75 package ohos.hdi.foo.v1_0;
76
77 [callback] interface IFooCallback {
78 PushData([in] String message);
79 }
80 ```
81
822. Write `BUILD.gn` for the `idl` file.
83 - Add the `BUILD.gn` file to the `drivers/interface/foo/v1.0/` directory. The file content is as follows:
84 ```
85 import("//drivers/adapter/uhdf2/hdi.gni") # Template to be imported for compiling the .idl file.
86 hdi("foo") { # Target .so files (libfoo_client_v1.0.z.so and libfoo_stub_v1.0.z.so) to be generated.
87 package = "ohos.hdi.foo.v1_0" # Package name, which must match the .idl path.
88 module_name = "foo" # moduleName that determines the driver descriptor (struct HdfDriverEntry) in the driver file.
89 sources = [ # .idl files to compile.
90 "IFoo.idl", # Interface .idl file.
91 "IFooCallback.idl", # .idl file for callbacks.
92 "MyTypes.idl", # .idl file for customized data types.
93 ]
94 language = "cpp" # Generate C or C++ code from the .idl files. You can select `c` or `cpp`.
95 }
96 ```
97
983. Implement the HDI service.
99
100 After the .idl files are compiled, intermediate code is generated in the `out/[product_name]/gen/drivers/interfaces/foo/v1_0` directory.
101
102 - Implement the HDI service APIs.
103
104 Implement the service interface based on the `foo_interface_service.h` file that is automatically generated, and compile the related source code to `FooService.z.so`.
105
106 Implement the service interface.
107 ```
108 namespace OHOS {
109 namespace HDI {
110 namespace Foo {
111 namespace V1_0 {
112
113 class FooService: public IFoo { // Inherit from the interface class and implement the interface.
114 public:
115 virtual ~FooService() {}
116
117 int32_t Ping(const std::string& sendMsg, std::string& recvMsg) override;
118 int32_t FooService::GetData(FooInfo& info) override;
119 int32_t FooService::SendCallbackObj(const sptr<IFooCallback>& cbObj) override;
120 };
121
122 } // namespace V1_0
123 } // namespace Foo
124 } // namespace Hdi
125 } // namespace OHOS
126 ```
127 Implement the service instantiation interface.
128 ```
129 #ifdef __cplusplus
130 extern "C" {
131 #endif /* __cplusplus */
132
133 Hdi::Foo::V1_0::IFooInterface *FooInterfaceServiceConstruct();
134
135 void FooInterfaceServiceRelease(Hdi::Foo::V1_0::IFooInterface *obj);
136
137 #ifdef __cplusplus
138 }
139 #endif /* __cplusplus */
140 ```
141
142 - Implement the driver entry.
143
144 The HDI services are published based on the user-mode Hardware Driver Foundation (HDF). Therefore, a driver entry needs to be implemented. The reference driver implementation code is generated in the **out** directory, for example, `out/gen/xxx/foo_interface_driver.cpp`. You can use this file or modify the file based on service requirements.
145 Then, compile the driver entry source code as `libfoo_driver.z.so`. (The .so file name must match that in the HDF configuration source.)
146
1474. Publish the HDI service.
148
149 Declare the HDI service in the HDF configuration source (HCS). The following uses the Hi3516D V300 board as an example. The HCS path is `vendor/hisilicon/Hi3516DV300/hdf_config/uhdf/device_info.hcs`. Add the following configuration:
150 ```
151 fooHost :: host {
152 hostName = "fooHost";
153 priority = 50;
154 fooDevice :: device {
155 device0 :: deviceNode {
156 policy = 2;
157 priority = 100;
158 preload = 2;
159 moduleName = "libfoo_driver.z.so";
160 serviceName = "foo_service";
161 }
162 }
163 }
164 ```
165
1665. Invoke the HDI service.
167
168 - Add the following dependency to **BUILD.gn** on the client:
169 `//drivers/interface/foo/v1.0:libfoo_proxy_1.0"`
170
171 - Invoke the HDI interface in the code (CPP is used as an example.)
172 ```
173 #include <v1_0/ifoo_interface.h>
174
175 int WorkFunc(void) {
176 sptr<IFoo> foo = OHOS::HDI::Foo::V1_0::Foo::Get(); // Use the built-in static method of the Foo object to obtain the client instance of the service.
177 if (foo == nullptr) {
178 // If the HDI service does not exist, handle the error.
179 }
180
181 foo->Bar(); // Do interface call.
182 }
183 ```
184 If a service has multiple instances, you can use the `Hdi::Foo::V1_0::Foo::GetInstance(const std::string& serviceName)` method to obtain the instance.
185
186## Conventions
187
1881. Rules for naming .idl files
189
190 - Name an .idl file in UpperCamelCase style, which is the same as the interface name. Generally, the file name starts with the letter I.
191 - The interface description file name extension is .idl.
192
1931. Interface naming rules
194
195 | Type| Style|
196 | ----- | ------- |
197 | Class, struct, enum, union, and package names | UpperCamelCase|
198 | Methods| UpperCamelCase|
199 | Function parameters and member variables in a class, struct, or union| lowerCamelCase|
200 | Macros, constants (const), and enumerated values| All uppercase letters, separated by underscores (_)|
201
2021. Interface version naming rules
203
204 The HDI interface version is defined in [major].[minor] format.
205 - Different major versions indicate that the interfaces are incompatible.
206 - The same major version and different minor versions indicate that the interfaces are compatible. However, the interface name, parameter type/quantity, and return value type/quantity in an earlier minor version cannot be changed.
207
208## Repositories Involved
209
210[Drive Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/driver-subsystem.md)
211
212
213[HDF adapter](https://gitee.com/openharmony/drivers_adapter/blob/master/README.md)
214
215
216[Peripheral](https://gitee.com/openharmony/drivers_peripheral/blob/master/README.md)
217
