• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Driver Service Management
2
3
4Driver services are objects of capabilities provided by HDF driver devices to external systems and are managed by the HDF in a unified manner. Driver service management involves publishing and obtaining driver services.
5
6
7The HDF uses the **policy** field in the configuration file to define policies for a driver to provide services externally. The values this field are as follows:
8
9
10
11```c
12typedef enum {
13    /* The driver does not provide services. */
14    SERVICE_POLICY_NONE = 0,
15    /* The driver publishes services only for kernel-mode processes. */
16    SERVICE_POLICY_PUBLIC = 1,
17    /* The driver publishes services for both kernel- and user-mode processes. */
18    SERVICE_POLICY_CAPACITY = 2,
19    /** The driver services are not published externally but can be subscribed to. */
20    SERVICE_POLICY_FRIENDLY = 3,
21    /* The driver private services cannot be published externally or subscribed to. */
22    SERVICE_POLICY_PRIVATE = 4,
23    /** Invalid service policy. */
24    SERVICE_POLICY_INVALID
25} ServicePolicy;
26```
27
28
29## When to Use
30
31You can use the driver service management capability of the HDF when the driver needs to provide capabilities via APIs.
32
33
34## Available APIs
35
36The table below describes the APIs for driver service management.
37
38  **Table 1** APIs for driver service management
39
40| API| Description|
41| -------- | -------- |
42| int32_t (\*Bind)(struct HdfDeviceObject \*deviceObject) | Binds a service API to the HDF. You need to implement the **Bind()** function.|
43| const struct HdfObject \*DevSvcManagerClntGetService(const char \*svcName)| Obtains a driver service.|
44|int HdfDeviceSubscribeService(struct HdfDeviceObject \*deviceObject, const char \*serviceName, struct SubscriberCallback callback) | Subscribes to a driver service.|
45
46
47## How to Develop
48
49The development procedure is as follows:
50
511. Define the service to be published by the driver.
52
53   ```c
54   // Define the driver service structure.
55   struct ISampleDriverService {
56       struct IDeviceIoService ioService;       // The first member must be of the IDeviceIoService type.
57       int32_t (*ServiceA)(void);               // API of the first driver service.
58       int32_t (*ServiceB)(uint32_t inputCode); // API of the second driver service. You can add more as required.
59   };
60
61   // Implement the driver service APIs.
62   int32_t SampleDriverServiceA(void)
63   {
64       // You need to implement the service logic.
65       return HDF_SUCCESS;
66   }
67
68   int32_t SampleDriverServiceB(uint32_t inputCode)
69   {
70       // You need to implement the service logic.
71       return HDF_SUCCESS;
72   }
73   ```
74
752. Bind the driver service.
76
77   Implement the **Bind** pointer function, for example, **SampleDriverBind**, in **HdfDriverEntry** to bind the driver service to the HDF.
78
79   ```c
80   int32_t SampleDriverBind(struct HdfDeviceObject *deviceObject)
81   {
82       // deviceObject is a pointer to the device object created by the HDF for each driver. The device object holds private device data and service APIs.
83       if (deviceObject == NULL) {
84           HDF_LOGE("Sample device object is null!");
85           return HDF_FAILURE;
86       }
87       static struct ISampleDriverService sampleDriverA = {
88           .ServiceA = SampleDriverServiceA,
89           .ServiceB = SampleDriverServiceB,
90       };
91       deviceObject->service = &sampleDriverA.ioService;
92       return HDF_SUCCESS;
93   }
94   ```
95
963. Obtain the driver service.
97
98   The driver service can be obtained by using either of the following methods:
99
100   - Using the API provided by the HDF
101
102     If the service requester clearly knows the time when the driver is loaded, use the API provided by the HDF to obtain the driver service. The following is an example:
103
104
105      ```c
106      const struct ISampleDriverService *sampleService =
107              (const struct ISampleDriverService *)DevSvcManagerClntGetService("sample_driver");
108      if (sampleService == NULL) {
109          return HDF_FAILURE;
110      }
111      sampleService->ServiceA();
112      sampleService->ServiceB(5);
113      ```
114   - Using the subscription mechanism
115
116     If the service requester is unaware of the time when the driver (in the same host) is loaded, use the subscription mechanism provided by the HDF to subscribe to the service. After the driver is loaded, the HDF publishes the driver service to the subscriber. The implementation is as follows:
117
118
119      ```c
120      // Callback invoked to return the driver service after the subscribed driver is loaded.
121      // object is the pointer to the private data of the subscriber, and service is the pointer to the subscribed service object.
122      int32_t TestDriverSubCallBack(struct HdfDeviceObject *deviceObject, const struct HdfObject *service)
123      {
124          const struct ISampleDriverService *sampleService =
125              (const struct ISampleDriverService *)service;
126          if (sampleService == NULL) {
127              return HDF_FAILURE;
128          }
129          sampleService->ServiceA();
130          sampleService->ServiceB(5);
131      }
132      // Implement the subscription process.
133      int32_t TestDriverInit(struct HdfDeviceObject *deviceObject)
134      {
135          if (deviceObject == NULL) {
136              HDF_LOGE("Test driver init failed, deviceObject is null!");
137              return HDF_FAILURE;
138          }
139          struct SubscriberCallback callBack;
140          callBack.deviceObject = deviceObject;
141          callBack.OnServiceConnected = TestDriverSubCallBack;
142          int32_t ret = HdfDeviceSubscribeService(deviceObject, "sample_driver", callBack);
143          if (ret != HDF_SUCCESS) {
144              HDF_LOGE("Test driver subscribe sample driver failed!");
145          }
146          return ret;
147      }
148      ```
149