# Peripheral Driver HDI Definition

## Introduction

This 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.


**Figure 1** HDI definition process

![](figures/hdi-schematic.png)

Define 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).

## Directory Structure

```
├── README.en.md
├── README.md
├── sensor                          # Sensor HDI definition.
│   └── v1_0                        # Sensor HDI v1.0 definition.
│       ├── BUILD.gn                # Sensor idl build script.
│       ├── ISensorCallback.idl     # Sensor callback interface definition.
│       ├── ISensorInterface.idl    # Sensor interface definition.
│       └── SensorTypes.idl         # Sensor data type definition.
├── audio                           # Audio HDI definition.
│   └── ...
├── camera                          # Camera HDI definition.
├── codec                           # Codec HDI definition.
├── display                         # Display HDI definition.
├── format                          # Format HDI definition.
├── input                           # Input HDI definition.
├── misc                            # Miscellaneous HDI definition.
├── usb                             # USB HDI definition.
└── wlan                            # WLAN HDI definition.
```

## How to Use

1. Create an `.idl` file in the IDL.

    - 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/`.

    - Define the interface `IFoo.idl`.
        ```
        package ohos.hdi.foo.v1_0;

        import ohos.hdi.foo.v1_0.IFooCallback;
        import ohos.hdi.foo.v1_0.MyTypes;

        interface IFoo {
            Ping([in] String sendMsg, [out] String recvMsg);

            GetData([out] struct FooInfo info);

            SendCallbackObj([in] IFooCallback cbObj);
        }
        ```
    - If customized data types are used in `interface`, define the data types in `MyTypes.idl`.
        ```
        package ohos.hdi.foo.v1_0;

        enum FooType {
            FOO_TYPE_ONE = 1,
            FOO_TYPE_TWO,
        };

        struct FooInfo {
            unsigned int id;
            String name;
            enum FooType type;
        };
        ```
    - If a callback from the server is required, define the callback class `IFooCallback.idl`.
        ```
        package ohos.hdi.foo.v1_0;

        [callback] interface IFooCallback {
            PushData([in] String message);
        }
        ```

2. Write `BUILD.gn` for the `idl` file.
    - Add the `BUILD.gn` file to the `drivers/interface/foo/v1.0/` directory. The file content is as follows:
        ```
        import("//drivers/adapter/uhdf2/hdi.gni")   # Template to be imported for compiling the .idl file.
        hdi("foo") {                                # Target .so files (libfoo_client_v1.0.z.so and libfoo_stub_v1.0.z.so) to be generated.
            package = "ohos.hdi.foo.v1_0"                    # Package name, which must match the .idl path.
            module_name = "foo"                     # moduleName that determines the driver descriptor (struct HdfDriverEntry) in the driver file.
            sources = [                             # .idl files to compile.
                "IFoo.idl",                         # Interface .idl file.
                "IFooCallback.idl",                 # .idl file for callbacks.
                "MyTypes.idl",                      # .idl file for customized data types.
            ]
            language = "cpp"                        # Generate C or C++ code from the .idl files. You can select `c` or `cpp`.
        }
        ```

3. Implement the HDI service.

    After the .idl files are compiled, intermediate code is generated in the `out/[product_name]/gen/drivers/interfaces/foo/v1_0` directory.

    - Implement the HDI service APIs.

        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`.

        Implement the service interface.
        ```
        namespace OHOS {
        namespace HDI {
        namespace Foo {
        namespace V1_0 {

        class FooService: public IFoo { // Inherit from the interface class and implement the interface.
        public:
            virtual ~FooService() {}

            int32_t Ping(const std::string& sendMsg, std::string& recvMsg) override;
            int32_t FooService::GetData(FooInfo& info) override;
            int32_t FooService::SendCallbackObj(const sptr<IFooCallback>& cbObj) override;
        };

        } // namespace V1_0
        } // namespace Foo
        } // namespace Hdi
        } // namespace OHOS
        ```
        Implement the service instantiation interface.
        ```
        #ifdef __cplusplus
        extern "C" {
        #endif /* __cplusplus */

        Hdi::Foo::V1_0::IFooInterface *FooInterfaceServiceConstruct();

        void FooInterfaceServiceRelease(Hdi::Foo::V1_0::IFooInterface *obj);

        #ifdef __cplusplus
        }
        #endif /* __cplusplus */
        ```

    - Implement the driver entry.

        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.
        Then, compile the driver entry source code as `libfoo_driver.z.so`. (The .so file name must match that in the HDF configuration source.)

4. Publish the HDI service.

    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:
    ```
    fooHost :: host {
            hostName = "fooHost";
            priority = 50;
            fooDevice :: device {
                device0 :: deviceNode {
                    policy = 2;
                    priority = 100;
                    preload = 2;
                    moduleName = "libfoo_driver.z.so";
                    serviceName = "foo_service";
                }
            }
        }
    ```

5. Invoke the HDI service.

    - Add the following dependency to **BUILD.gn** on the client:
    `//drivers/interface/foo/v1.0:libfoo_proxy_1.0"`

    - Invoke the HDI interface in the code (CPP is used as an example.)
        ```
        #include <v1_0/ifoo_interface.h>

        int WorkFunc(void) {
            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.
            if (foo == nullptr) {
                // If the HDI service does not exist, handle the error.
            }

            foo->Bar(); // Do interface call.
        }
        ```
        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.

## Conventions

1. Rules for naming .idl files

    - Name an .idl file in UpperCamelCase style, which is the same as the interface name. Generally, the file name starts with the letter I.
    - The interface description file name extension is .idl.

1. Interface naming rules

    | Type| Style|
    | -----  | ------- |
    | Class, struct, enum, union, and package names | UpperCamelCase|
    | Methods| UpperCamelCase|
    | Function parameters and member variables in a class, struct, or union| lowerCamelCase|
    | Macros, constants (const), and enumerated values| All uppercase letters, separated by underscores (_)|

1. Interface version naming rules

    The HDI interface version is defined in [major].[minor] format.
    - Different major versions indicate that the interfaces are incompatible.
    - 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.

## Repositories Involved

[Drive Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/driver-subsystem.md)


[HDF adapter](https://gitee.com/openharmony/drivers_adapter/blob/master/README.md)


[Peripheral](https://gitee.com/openharmony/drivers_peripheral/blob/master/README.md)

# 外设驱动HDI接口定义

## 简介

该仓库用于管理各模块HDI(Hardware Device Interface)接口定义，接口定义使用IDL语言描述并以`·idl`文件形式保存。


**图 1**  HDI原理图

![](figures/hdi-schematic.png)

使用IDL语法描述HDI接口并保存为`.idl`文件，`.idl`文件在编译过程中转换为C/C++语言的函数接口声明、客户端与服务端IPC相关过程代码，开发者只需要基于生成的`ifoo.h`函数接口实现具体服务功能即可。代码生成与编译功能已经集成在`//drivers/adapter/uhdf2/hdi.gni`编译模板，基于该编译模板编写`idl`文件的`BUILD.gn`就可以简单的生成客户端、服务端代码并编译为共享库。

## 目录

```
├── README.en.md
├── README.md
├── sensor                          #sensor HDI 接口定义
│   └── v1_0                        #sensor HDI 接口 v1.0版本定义
│       ├── BUILD.gn                #sensor idl文件编译脚本
│       ├── ISensorCallback.idl     #sensor callback 接口定义idl文件
│       ├── ISensorInterface.idl    #sensor interface 接口定义idl文件
│       └── SensorTypes.idl         #sensor 数据类型定义idl文件
├── audio                           #audio HDI 接口定义
│   └── ...
├── camera                          #camera HDI接口定义
├── codec                           #codec HDI接口定义
├── display                         #display HDI接口定义
├── format                          #format HDI接口定义
├── input                           #input HDI接口定义
├── misc                            #misc HDI接口定义
├── usb                             #usb HDI接口定义
└── wlan                            #wlan HDI接口定义
```

## 使用说明

1. 使用IDL语法编写 `.idl` 文件

    - 参考上节目录结构创建对应模块/版本接口目录，初始版本定义为`v1_0`，如 `drivers/interface/foo/v1.0/`

    - 定义接口 `IFoo.idl`
        ```
        package ohos.hdi.foo.v1_0;

        import ohos.hdi.foo.v1_0.IFooCallback;
        import ohos.hdi.foo.v1_0.MyTypes;

        interface IFoo {
            Ping([in] String sendMsg, [out] String recvMsg);

            GetData([out] struct FooInfo info);

            SendCallbackObj([in] IFooCallback cbObj);
        }
        ```
    - 如果`interface`中用到了自定义数据类型，将自定义类型定义到`MyTypes.idl`
        ```
        package ohos.hdi.foo.v1_0;

        enum FooType {
            FOO_TYPE_ONE = 1,
            FOO_TYPE_TWO,
        };

        struct FooInfo {
            unsigned int id;
            String name;
            enum FooType type;
        };
        ```
    - 如果需要从服务端回调，可以定义`callback`接口类`IFooCallback.idl`
        ```
        package ohos.hdi.foo.v1_0;

        [callback] interface IFooCallback {
            PushData([in] String message);
        }
        ```

1. 编写 `idl`文件的`BUILD.gn`
    - 在上述`drivers/interface/foo/v1.0/`目录中添加`BUILD.gn`文件，内容参考如下：
        ```
        import("//drivers/adapter/uhdf2/hdi.gni")   # 编译idl必须要导入的模板
        hdi("foo") {                                # 目标名称，会生成两个so，分别对应 libfoo_client_v1.0.z.so 和 libfoo_stub_v1.0.z.so
            package = "ohos.hdi.foo.v1_0"           # 包名，必须与idl路径匹配
            module_name = "foo"                     # module_name控制dirver文件中驱动描 述符(struct HdfDriverEntry)的moduleName
            sources = [                             # 参与编译的idl文件
                "IFoo.idl",                         # 接口idl
                "IFooCallback.idl",                 # 用于回调的idl
                "MyTypes.idl",                      # 自定义类型idl
            ]
            language = "cpp"                        # 控制idl生成c或c++代码 可选择`c`或`cpp`
        }
        ```

2. 实现 HDI 服务

    在上述步骤中idl编译后将在out目录`out/[product_name]/gen/drivers/interfaces/foo/v1_0`生成中间代码。

    - 实现HDI服务接口

        基于工具自动生成的`foo_interface_service.h`，实现其中的服务接口，并将相关源码编译为FooService.z.so。

        实现服务业务接口：
        ```
        namespace OHOS {
        namespace HDI {
        namespace Foo {
        namespace V1_0 {

        class FooService : public IFoo {  //继承接口类，并重写接口
        public:
            virtual ~FooService() {}

            int32_t Ping(const std::string& sendMsg, std::string& recvMsg) override;
            int32_t FooService::GetData(FooInfo& info) override;
            int32_t FooService::SendCallbackObj(const sptr<IFooCallback>& cbObj) override;
        };

        } // namespace V1_0
        } // namespace Foo
        } // namespace Hdi
        } // namespace OHOS
        ```

    - 实现驱动入口

        HDI服务发布是基于用户态HDF驱动框架，所以需要实现一个驱动入口。驱动实现代码参考已经在out目录中生成，如`out/gen/xxx/foo_interface_driver.cpp`，可以根据业务需要直接使用该文件或参考该文件按业务需要重新实现。
        然后将驱动入口源码编译为`libfoo_driver.z.so`（该名称无强制规定，与hcs配置中配套即可）。

3. 发布服务

    在产品hcs配置中声明HDI服务，以标准系统Hi3516DV300单板为例，HDF设备配置路径为`vendor/hisilicon/Hi3516DV300/hdf_config/uhdf/device_info.hcs`，在其中新增以下配置：
    ```
    fooHost :: host {
            hostName = "fooHost";
            priority = 50;
            fooDevice :: device {
                device0 :: deviceNode {
                    policy = 2;
                    priority = 100;
                    preload = 2;
                    moduleName = "libfoo_driver.z.so";
                    serviceName = "foo_service";
                }
            }
        }
    ```

4. 调用HDI服务

    - 客户端在BUILD.gn中增加依赖：
    `//drivers/interface/foo/v1.0:libfoo_proxy_1.0"`

    - 在代码中调用HDI接口（以CPP为例）
        ```
        #include <v1_0/ifoo_interface.h>

        int WorkFunc(void) {
            sptr<IFoo> foo = OHOS::HDI::Foo::V1_0::Foo::Get(); // 使用Foo对象的内置静态方法获取该服务客户端实例
            if (foo == nullptr) {
                // hdi service not exist, handle error
            }

            foo->Bar(); // do interface call
        }
        ```
        如果服务存在多实例可以通过指定实例名称的方法获取对应实例`Hdi::Foo::V1_0::Foo::GetInstance(const std::string& serviceName)`;

## 约定

1. idl 文件命名规则

    - idl 文件以大驼峰命名，与接口名称保持一致，一般以字母‘I’开头。
    - 接口描述文件以`.idl`作为后缀。

1. 接口命名规则

    | 类型   | 命名风格  |
    | -----  | ------- |
    | 类、结构体、枚举、联合体等类型名，包名 | 大驼峰 |
    | 方法 | 大驼峰 |
    | 函数参数，类、结构体和联合体中的成员变量 | 小驼峰 |
    | 宏，常量(const)，枚举值 | 全大写，下划线分割 |

1. 接口版本号命名规则

    HDI接口版本号使用语义化版本号定义，即[major].[minor]。
    - major版本号不同表示接口间不兼容；
    - minor版本不同但是major版本号相同表示接口相互兼容，这种情况下不允许修改以前接口的接口名称、参数类型/个数、返回值类型/个数。

## 相关仓

[驱动子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/%E9%A9%B1%E5%8A%A8%E5%AD%90%E7%B3%BB%E7%BB%9F.md)


[drivers\_adapter](https://gitee.com/openharmony/drivers_adapter/blob/master/README_zh.md)


[drivers\_peripheral](https://gitee.com/openharmony/drivers_peripheral/blob/master/README_zh.md)