driver-hdf-development.md 9.8 KB
Newer Older
W
wenjun 已提交
1 2
# Driver Development<a name="EN-US_TOPIC_0000001051930361"></a>

N
NEEN 已提交
3 4 5
-   [Introduction](#section157425168112)
-   [How to Develop](#section1969312275533)

W
wenjun 已提交
6 7
## Introduction<a name="section157425168112"></a>

D
duangavin123 已提交
8
The HDF is designed based on the component-based driver model. It provides more refined driver management to make driver development and deployment more standard. Device drivers of the same type are placed in the same host. You can develop and deploy the drivers separately. One driver can have multiple nodes.  [Figure 1](#fig5487113011526)  shows the HDF driver model.
W
wenjun 已提交
9

D
duangavin123 已提交
10
**Figure  1**  HDF driver model<a name="fig5487113011526"></a>  
W
wenjun 已提交
11 12


D
duangavin123 已提交
13
![](figure/en-us_image_0000001054564784.png)
W
wenjun 已提交
14 15 16 17 18 19 20 21 22 23 24 25 26

## How to Develop<a name="section1969312275533"></a>

Driver development based on the HDF consists of two parts: driver implementation and driver configuration. The details are as follows:

1.  <a name="li35182436435"></a>Implement driver.

    To implement a driver, compile driver service code and register a driver entry.

    -   Driver service code

        ```
        #include "hdf_device_desc.h"  // Header file that describes the APIs provided by the HDF to the driver.
D
duangavin123 已提交
27
        #include "hdf_log.h"          // Header file that describes the log APIs provided by the HDF.
W
wenjun 已提交
28
        
D
duangavin123 已提交
29
        #define HDF_LOG_TAG "sample_driver"   // Tag contained in logs. If no tag is not specified, the default HDF_TAG is used.
W
wenjun 已提交
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
        
        // The driver service interface must be bound to the HDF for you to use the service capability.
        int32_t HdfSampleDriverBind(struct HdfDeviceObject *deviceObject)
        {
            HDF_LOGD("Sample driver bind success");
            return 0;
        }
        
        // Initialize the driver service.
        int32_t HdfSampleDriverInit(struct HdfDeviceObject *deviceObject)
        {
            HDF_LOGD("Sample driver Init success");
            return 0;
        }
        
        // Release the driver resources.
        void HdfSampleDriverRelease(struct HdfDeviceObject *deviceObject)
        {
            HDF_LOGD("Sample driver release success");
            return;
        }
        ```

    -   Registering the driver entry with the HDF

        ```
        // Define the object of the driver entry. The object must be a global variable of the HdfDriverEntry type (defined in hdf_device_desc.h).
        struct HdfDriverEntry g_sampleDriverEntry = {
            .moduleVersion = 1,
            .moduleName = "sample_driver",
            .Bind = HdfSampleDriverBind,
            .Init = HdfSampleDriverInit,
            .Release = HdfSampleDriverRelease,
        };
        
        // Call HDF_INIT to register the driver entry with the HDF framework. When loading the driver, call the Bind function and then the Init function. If the Init function fails to be called, the HDF will call Release to release the driver resource and exit.
        HDF_INIT(g_sampleDriverEntry);
        ```

2.  Compile the driver code.
    -   Use the  **Makefile**  template provided by the HDF to compile the driver code.

        ```
D
duanxichao 已提交
73
        include $(LITEOSTOPDIR)/../../drivers/adapter/lite/khdf/lite.mk # (Mandatory) Import the predefined content of the HDF.
N
NEEN 已提交
74 75 76 77
        MODULE_NAME :=    # Generated result file
        LOCAL_INCLUDE: =  # Header file directory of the driver
        LOCAL_SRCS : =     # Source code file of the driver
        LOCAL_CFLAGS : =  # Custom compilation options
W
wenjun 已提交
78 79 80 81 82 83 84 85 86 87 88 89
        include $(HDF_DRIVER) # Import the template Makefile to complete compilation.
        ```

    -   Link the compilation result file to the kernel image by adding the result file to  **hdf\_vendor.mk**  in the  **vendor**  directory. The following is an example:

        ```
        LITEOS_BASELIB +=  -lxxx  # Static library generated through linking
        LIB_SUBDIRS    +=         # Directory of Makefile
        ```

3.  Configure the driver.

D
duangavin123 已提交
90
    HDF Configuration Source \(HCS\) is the source code that describes the configuration of the HDF. For details about the HCS, see  [Driver Configuration Management](driver-hdf-manage.md).
W
wenjun 已提交
91 92 93 94 95 96 97 98 99 100 101 102 103

    The driver configuration consists of the driver device description defined by the HDF and private driver configuration information.

    -   \(Mandatory\) Driver device description

        The information required for the HDF to load drivers comes from the driver device description defined by the HDF. Therefore, the device description must be added to the configuration file  **device\_info.hcs**  defined by the HDF for drivers developed based on the HDF. The following is an example:

        ```
        root {
            device_info {
                match_attr = "hdf_manager";
                template host {       // Host template. If the node (for example, sample_host) that inherits the template uses default values in the template, the values of the node fields can be omitted.
                    hostName = "";
W
wenjun 已提交
104 105 106 107 108 109 110 111 112 113 114
                    priority = 100;
                    template device {
                        template deviceNode {
                            policy = 0;
                            priority = 100;
                            preload = 0;
                            permission = 0664;
                            moduleName = "";
                            serviceName = "";
                            deviceMatchAttr = "";
                        }
W
wenjun 已提交
115 116 117 118 119
                    }
                }
                sample_host :: host{
                    hostName = "host0";    // Host name. The host node is used to store a certain type of drivers.
                    priority = 100;        // Host startup priority (0-200). A larger value indicates a lower priority. The default value 100 is recommended. If the priorities are the same, the host loading sequence is random.
W
wenjun 已提交
120 121
                    device_sample :: device {        // Device node of sample
                        device0 :: deviceNode {      // DeviceNode of the sample driver
N
NEEN 已提交
122 123
                            policy = 1;              // Driver service release policy. For details, see section Driver Service Management.
                            priority = 100;          // Driver startup priority (0-200). A larger value indicates a lower priority. The default value 100 is recommended. If the priorities are the same, the device loading sequence is random.
D
duangavin123 已提交
124
                            preload = 0;             // On-demand loading of the driver. For details, see "NOTE" at the end of this section.
N
NEEN 已提交
125 126 127
                            permission = 0664;       // Permission for the driver to create device nodes.
                            moduleName = "sample_driver";   // Driver name. The value of this field must be the same as the value of moduleName in the driver entry structure.
                            serviceName = "sample_service";    // Name of the service released by the driver. The name must be unique.
W
wenjun 已提交
128 129
                            deviceMatchAttr = "sample_config"; // Keyword matching the private data of the driver. The value must be the same as that of match_attr in the private data configuration table of the driver.
                        }
W
wenjun 已提交
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
                    }
                }
            }
        }
        ```

    -   \(Optional\) Private configuration information of the driver

        If the driver has private configurations, you can add a driver configuration file to fill in the default configuration information of the driver. When loading the driver, the HDF obtains the information and saves it in the  **property**  of  **HdfDeviceObject**, and transfers it to the driver using  **Bind**  and  **Init**  \(see  [1](#li35182436435)\). The following is an example of the driver configuration information:

        ```
        root {
            SampleDriverConfig {
                sample_version = 1;
                sample_bus = "I2C_0";
                match_attr = "sample_config"; // The value of this field must be the same as that of deviceMatchAttr in device_info.hcs.
            }
        }
        ```

        After the configuration information is defined, you need to add the configuration file to the board-level configuration entry file  **hdf.hcs**. \(You can use the DevEco to perform on-click configuration. For details, see the description about the driver development suite.\) The following is an example:

        ```
        #include "device_info/device_info.hcs"
        #include "sample/sample_config.hcs"
        ```



D
duangavin123 已提交
159
>![](../public_sys-resources/icon-note.gif) **NOTE:** 
W
wenjun 已提交
160 161 162 163 164
>On-demand loading and sequential loading are supported. The detailed usage is as follows:
>-   On-demand loading
>    ```
>    typedef enum {
>        DEVICE_PRELOAD_ENABLE = 0,
M
mamingshuai 已提交
165
>        DEVICE_PRELOAD_ENABLE_STEP2,
W
wenjun 已提交
166 167 168 169
>        DEVICE_PRELOAD_DISABLE,
>        DEVICE_PRELOAD_INVALID
>    } DevicePreload;
>    ```
D
duangavin123 已提交
170
>    When the  **preload**  field in the configuration file is set to  **0**  \(**DEVICE\_PRELOAD\_ENABLE**\), the driver is loaded by default during system startup. When this field is set to  **1**  \(**DEVICE\_PRELOAD\_ENABLE\_STEP2**\), the driver is loaded after system startup if quick start is enabled; it is loaded during system startup otherwise. When this field is set to  **2**  \(**DEVICE\_PRELOAD\_DISABLE**\), the driver is not loaded by default during system startup and can be dynamically loaded later. If the driver service does not exist when a user-level application obtains the driver service \(for details about how to obtain the driver service, see  [Driver Message Mechanism Management](driver-hdf-news.md)\), the HDF attempts to dynamically load the driver.
W
wenjun 已提交
171 172 173
>-   Sequential loading \(drivers must be loaded by default\)
>    In the configuration file, the  **priority**  field \(the value is an integer ranging from 0 to 200\) indicates the priority of the host and driver. For drivers in different hosts, a smaller host priority value indicates a higher driver loading priority; for drivers in the same host, a smaller driver priority value indicates a higher driver loading priority.