1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup Core 11 * @{ 12 * 13 * @brief Provides Hardware Driver Foundation (HDF) APIs. 14 * 15 * The HDF implements driver framework capabilities such as driver loading, service management, 16 * and driver message model. You can develop drivers based on the HDF. 17 * 18 * @since 1.0 19 */ 20 21 /** 22 * @file hdf_device_desc.h 23 * 24 * @brief Declares functions related to driver loading, service obtaining, and power management. 25 * 26 * @since 1.0 27 */ 28 29 #ifndef HDF_DEVICE_DESC_H 30 #define HDF_DEVICE_DESC_H 31 32 #include "hdf_device_section.h" 33 #include "hdf_io_service_if.h" 34 #include "hdf_object.h" 35 #include "hdf_sbuf.h" 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif /* __cplusplus */ 40 /** 41 * @brief The maximum priority for loading the host and device. 42 */ 43 #define MAX_PRIORITY_NUM 200 44 45 /** 46 * @brief Enumerates policies for releasing driver services developed based on the HDF. 47 * 48 * If a driver is developed based on the HDF and uses the service management feature of the HDF, you need to 49 * configure the policy for releasing services to external systems. 50 * 51 * @since 1.0 52 */ 53 typedef enum { 54 /** The driver does not provide services externally. */ 55 SERVICE_POLICY_NONE = 0, 56 /** The driver provides services for kernel-level applications. */ 57 SERVICE_POLICY_PUBLIC, 58 /** The driver provides services for both kernel- and user-level applications. */ 59 SERVICE_POLICY_CAPACITY, 60 /** Driver services are not released externally but can be subscribed to. */ 61 SERVICE_POLICY_FRIENDLY, 62 /** Driver services are only internally available. 63 They are not released externally and cannot be subscribed to by external users. */ 64 SERVICE_POLICY_PRIVATE, 65 /** The service policy is incorrect. */ 66 SERVICE_POLICY_INVALID 67 } ServicePolicy; 68 69 /** 70 * @brief Enumerates driver loading policies. 71 * 72 * If a driver developed based on the HDF needs to use the on-demand loading mechanism in the HDF, the <b>PRELOAD</b> 73 * field must be correctly set in the driver configuration information to control the driver loading mode. 74 * 75 * @since 1.0 76 */ 77 typedef enum { 78 DEVICE_PRELOAD_ENABLE = 0, /**< The driver is loaded during system startup by default. */ 79 DEVICE_PRELOAD_ENABLE_STEP2, /**< The driver is loaded after OS startup if quick start is enabled. */ 80 DEVICE_PRELOAD_DISABLE, /**< The driver is not loaded during system startup by default. */ 81 DEVICE_PRELOAD_INVALID /**< The loading policy is incorrect. */ 82 } DevicePreload; 83 84 /** 85 * @brief Defines the device object. 86 * 87 * This structure is a device object defined by the HDF and is used to store private data and interface information 88 * of a device. 89 * 90 * @since 1.0 91 */ 92 struct HdfDeviceObject { 93 /** Pointer to the service interface object, which is registered with the HDF by the driver */ 94 struct IDeviceIoService *service; 95 /** Pointer to the property of the device, which is read by the HDF from the configuration file and 96 transmitted to the driver. */ 97 #ifdef LOSCFG_DRIVERS_HDF_CONFIG_MACRO 98 const char *deviceMatchAttr; 99 #else 100 const struct DeviceResourceNode *property; 101 #endif 102 DeviceClass deviceClass; 103 /** Pointer to the private data of the device */ 104 void *priv; 105 }; 106 107 /** 108 * @brief Defines the client object structure of the I/O service. 109 * 110 * This structure describes the invoker information of the I/O servcie. 111 * 112 * @since 1.0 113 */ 114 struct HdfDeviceIoClient { 115 /** Device object corresponding to the client object */ 116 struct HdfDeviceObject *device; 117 /** Private data of the client object. The driver can use <b>priv</b> to bind the internal data with the client. */ 118 void *priv; 119 }; 120 121 /** 122 * @brief Defines the driver service. 123 * 124 * When a driver releases services to user-level applications, the service interface must inherit this structure 125 * and implements the <b>Dispatch</b> function in the structure. 126 * 127 * @since 1.0 128 */ 129 struct IDeviceIoService { 130 /** Driver service object ID */ 131 struct HdfObject object; 132 /** 133 * @brief Called when the driver service is enabled by a user-level application. 134 * 135 * @param client Indicates the pointer to the client object of the service. 136 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 137 * 138 * @since 1.0 139 */ 140 int32_t (*Open)(struct HdfDeviceIoClient *client); 141 /** 142 * @brief Called when the driver service is invoked by a user-level application. 143 * 144 * @param client Indicates the pointer to the client object of the service. 145 * @param cmdId Indicates the command word of the service interface. 146 * @param data Indicates the pointer to the data passed by the invoker. 147 * @param reply Indicates the pointer to the data that needs to be returned to the invoker. 148 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 149 * 150 * @since 1.0 151 */ 152 int32_t (*Dispatch)(struct HdfDeviceIoClient *client, int cmdId, struct HdfSBuf *data, struct HdfSBuf *reply); 153 /** 154 * @brief Called when the driver service is released by a user-level application. 155 * 156 * @param client Indicates the pointer to the client object of the service. 157 * 158 * @since 1.0 159 */ 160 void (*Release)(struct HdfDeviceIoClient *client); 161 }; 162 163 /** 164 * @brief Called when the driver subscribes to other driver services. 165 * 166 * The callback is used in the service subscription mechanism. After the driver is registered with the HDF, the HDF 167 * proactively invokes the callback after the subscribed-to driver is loaded. 168 * 169 * @since 1.0 170 */ 171 struct SubscriberCallback { 172 /** Driver object of the subscriber */ 173 struct HdfDeviceObject *deviceObject; 174 /** 175 * @brief Called by the HDF when the subscribed-to driver service is loaded. 176 * 177 * @param deviceObject Indicates the pointer to the variable of the {@link HdfDeviceObject} type. This variable 178 * is generated by the HDF and passed to the driver. 179 * @param service Indicates the pointer to the service object. 180 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 181 * 182 * @since 1.0 183 */ 184 int32_t (*OnServiceConnected)(struct HdfDeviceObject *deviceObject, const struct HdfObject *service); 185 }; 186 187 /** 188 * @brief Defines the entry structure of the driver in the HDF. 189 * 190 * This structure must be used as the entry for the driver to use the HDF mechanism. 191 * 192 * @since 1.0 193 */ 194 struct HdfDriverEntry { 195 /** Driver version */ 196 int32_t moduleVersion; 197 /** Driver module name, which is used to match the driver information in the configuration file. */ 198 const char *moduleName; 199 /** 200 * @brief Binds the external service interface of a driver to the HDF. This function is implemented by the driver 201 * developer and called by the HDF. 202 * 203 * @param deviceObject Indicates the pointer to the variable of the {@link HdfDeviceObject} type. This variable 204 * is generated by the HDF and passed to the driver. Then, the service object of the driver is bound to the 205 * <b>service</b> parameter of <b>deviceObject</b>. 206 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 207 * 208 * @since 1.0 209 */ 210 int32_t (*Bind)(struct HdfDeviceObject *deviceObject); 211 /** 212 * @brief Initializes the driver. This function is implemented by the driver developer and called by the HDF. 213 * 214 * @param deviceObject Indicates the pointer to the variable of the {@link HdfDeviceObject} type. It is the same 215 * as the parameter of {@link Bind}. 216 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 217 * 218 * @since 1.0 219 */ 220 int32_t (*Init)(struct HdfDeviceObject *deviceObject); 221 /** 222 * @brief Releases driver resources. This function is implemented by the driver developer. When an exception 223 * occurs during driver loading or the driver is uninstalled, the HDF calls this function to release the 224 * driver resources. 225 * 226 * @param deviceObject Indicates the pointer to the variable of the {@link HdfDeviceObject} type. It is the same 227 * as the parameter of {@link Bind}. 228 * 229 * @since 1.0 230 */ 231 void (*Release)(struct HdfDeviceObject *deviceObject); 232 }; 233 234 /** 235 * @brief Registers the driver with the HDF. 236 * 237 * For a driver developed based on the HDF, {@link HDF_INIT} must be used to register an entry with the HDF, and the 238 * registered object must be of the {@link HdfDriverEntry} type. 239 * 240 * @param module Indicates the global variable of the {@link HdfDriverEntry} type 241 * 242 * @since 1.0 243 */ 244 #define HDF_INIT(module) HDF_DRIVER_INIT(module) 245 246 /** 247 * @brief Obtains the driver service object based on a driver service name. 248 * 249 * @param svcName Indicates the pointer to the released driver service name. 250 * 251 * @return Returns the driver service object if the operation is successful; returns <b>NULL</b> otherwise. 252 * @since 1.0 253 */ 254 const struct HdfObject *DevSvcManagerClntGetService(const char *svcName); 255 256 /** 257 * @brief Obtains the service name of a driver. 258 * 259 * If a driver does not save its service name, it can use this function to obtain the service name. \n 260 * 261 * @param deviceObject Indicates the pointer to the driver device object. 262 * 263 * @return Returns the service name if the operation is successful; returns <b>NULL</b> otherwise. 264 * @since 1.0 265 */ 266 const char *HdfDeviceGetServiceName(const struct HdfDeviceObject *deviceObject); 267 268 /** 269 * @brief Subscribes to a driver service. 270 * 271 * If the driver loading time is not perceived, this function can be used to subscribe to the driver service. (The 272 * driver service and the subscriber must be on the same host.) After the subscribed-to driver service is loaded by the 273 * HDF, the framework proactively releases the service interface to the subscriber. \n 274 * 275 * @param deviceObject Indicates the pointer to the driver device object of the subscriber. 276 * @param serviceName Indicates the pointer to the driver service name. 277 * @param callback Indicates the callback invoked by the HDF after the subscribed-to driver service is loaded. 278 * 279 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 280 * @since 1.0 281 */ 282 int32_t HdfDeviceSubscribeService( 283 struct HdfDeviceObject *deviceObject, const char *serviceName, struct SubscriberCallback callback); 284 285 /** 286 * @brief Sends event messages. 287 * 288 * When the driver service invokes this function to send a message, all user-level applications that have registered 289 * listeners through {@link HdfDeviceRegisterEventListener} will receive the message. 290 * 291 * @param deviceObject Indicates the pointer to the driver device object. 292 * @param id Indicates the ID of the message sending event. 293 * @param data Indicates the pointer to the message content sent by the driver. 294 * 295 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 296 * @since 1.0 297 */ 298 int32_t HdfDeviceSendEvent(const struct HdfDeviceObject *deviceObject, uint32_t id, const struct HdfSBuf *data); 299 300 /** 301 * @brief Sends an event message to a specified client object. 302 * 303 * When the driver service invokes this function to send a message, the user-level applications that have registered 304 * listeners through {@link HdfDeviceRegisterEventListener} and correspond to this client object will receive 305 * the message. 306 * 307 * @param client Indicates the pointer to the client object of the driver service. 308 * @param id Indicates the ID of the message sending event. 309 * @param data Indicates the pointer to the message content sent by the driver. 310 * 311 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 312 * @since 1.0 */ 313 int32_t HdfDeviceSendEventToClient(const struct HdfDeviceIoClient *client, uint32_t id, const struct HdfSBuf *data); 314 315 /** 316 * @brief Sets the driver device class. 317 * 318 * After setting the driver device class, you can obtain the service name of this driver device type via 319 * {@link HdfGetServiceNameByDeviceClass}. 320 * 321 * 322 * @param deviceObject Indicates the pointer to the driver device object. 323 * @param deviceClass Indicates the device class defined by {@link DeviceClass}. 324 * 325 * @return Returns <b>true</b> if the operation is successful; returns <b>false</b> otherwise. 326 * @since 1.0 */ 327 bool HdfDeviceSetClass(struct HdfDeviceObject *deviceObject, DeviceClass deviceClass); 328 329 #ifdef __cplusplus 330 } 331 #endif /* __cplusplus */ 332 333 #endif /* HDF_DEVICE_DESC_H */ 334 /** @} */ 335