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