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 #ifndef PLATFORM_DEVICE_H 10 #define PLATFORM_DEVICE_H 11 12 #include "hdf_base.h" 13 #include "hdf_device_desc.h" 14 #include "hdf_dlist.h" 15 #include "hdf_sref.h" 16 #include "osal_sem.h" 17 #include "osal_spinlock.h" 18 #include "platform_event.h" 19 #include "platform_if.h" 20 21 #ifdef __cplusplus 22 #if __cplusplus 23 extern "C" { 24 #endif 25 #endif /* __cplusplus */ 26 27 struct PlatformManager; 28 29 struct PlatformDevice { 30 struct HdfDeviceObject *hdfDev; /* related to a hdf device object */ 31 struct IDeviceIoService *service; /* related to a hdf io service object */ 32 struct PlatformManager *manager; /* the platform manager it belongs to */ 33 int32_t number; /* number of the device instance */ 34 const char *name; /* name of the device instance */ 35 struct HdfSRef ref; /* used for reference count */ 36 struct DListHead node; /* linked to the list of a manager */ 37 struct PlatformEvent event; /* platform event obj of this device */ 38 OsalSpinlock spin; /* for member protection */ 39 uint32_t irqSave; /* for spinlock irq save */ 40 struct OsalSem released; /* for death notification */ 41 void *priv; /* private data of the device */ 42 }; 43 44 /** 45 * @brief Initialize a platform device. 46 * 47 * Initialize members of a platform device. 48 * 49 * @param device Indicates the pointer to the platform device. 50 * 51 * @since 1.0 52 */ 53 int32_t PlatformDeviceInit(struct PlatformDevice *device); 54 55 /** 56 * @brief Uninitialize a platform device. 57 * 58 * Uninitialize members of a platform device. 59 * 60 * @param device Indicates the pointer to the platform device. 61 * 62 * @since 1.0 63 */ 64 void PlatformDeviceUninit(struct PlatformDevice *device); 65 66 /** 67 * @brief Set the name of a platform device. 68 * 69 * Use PlatformDeviceClearName to clean the name if no need anymore. 70 * 71 * @param device Indicates the pointer to the platform device. 72 * @param fmt Indicates the pointer to the format string. 73 * 74 * @since 1.0 75 */ 76 int32_t PlatformDeviceSetName(struct PlatformDevice *device, const char *fmt, ...); 77 78 /** 79 * @brief Clear the name of a platform device. 80 * 81 * Can only clear the name set by PlatformDeviceSetName. 82 * 83 * @param device Indicates the pointer to the platform device. 84 * 85 * @since 1.0 86 */ 87 void PlatformDeviceClearName(struct PlatformDevice *device); 88 89 /** 90 * @brief Increase reference count for a platform device. 91 * 92 * @param device Indicates the pointer to the platform device. 93 * 94 * @return Returns 0 if get successfully; returns a negative value otherwise. 95 * @since 1.0 96 */ 97 int32_t PlatformDeviceGet(struct PlatformDevice *device); 98 99 /** 100 * @brief Decrease reference count for a platform device. 101 * 102 * @param device Indicates the pointer to the platform device. 103 * 104 * @since 1.0 105 */ 106 void PlatformDevicePut(struct PlatformDevice *device); 107 108 /** 109 * @brief Get the reference count for a platform device. 110 * 111 * @param device Indicates the pointer to the platform device. 112 * 113 * @return Returns the reference count on success; returns a negative value otherwise. 114 * @since 1.0 115 */ 116 int32_t PlatformDeviceRefCount(struct PlatformDevice *device); 117 118 /** 119 * @brief Wait for specified events of a platform device. 120 * 121 * @param device Indicates the pointer to the platform device. 122 * @param mask Mask the events interested. 123 * @param tms The timeout value specified. 124 * @param events Pointer to receive the events, NULL if not needed. 125 * 126 * @return Returns 0 if wait successfully; returns a negative value otherwise. 127 * @since 1.0 128 */ 129 int32_t PlatformDeviceWaitEvent(struct PlatformDevice *device, uint32_t mask, uint32_t tms, uint32_t *events); 130 131 /** 132 * @brief Post a platform event. 133 * 134 * @param device Indicates the pointer to the platform device. 135 * @param events The platform event to post. 136 * 137 * @return Returns 0 if the event post successfully; returns a negative value otherwise. 138 * @since 1.0 139 */ 140 int32_t PlatformDevicePostEvent(struct PlatformDevice *device, uint32_t events); 141 142 /** 143 * @brief Register a listener to a platform device. 144 * 145 * The events will be notified by callback function specified by the platform listener object. 146 * 147 * @param device Indicates the pointer to the platform device. 148 * @param listener Indicates the pointer to the platform listener. 149 * 150 * @return Returns 0 if registered successfully; returns a negative value otherwise. 151 * @since 1.0 152 */ 153 int32_t PlatformDeviceListenEvent(struct PlatformDevice *device, struct PlatformEventListener *listener); 154 155 /** 156 * @brief Unregister a listener to a platform device. 157 * 158 * @param device Indicates the pointer to the platform device. 159 * @param listener Indicates the pointer to the platform listener. 160 * 161 * @since 1.0 162 */ 163 void PlatformDeviceUnListenEvent(struct PlatformDevice *device, struct PlatformEventListener *listener); 164 165 /** 166 * @brief Add a platform device by module type. 167 * 168 * do not call in irq context cause can sleep 169 * 170 * @param device Indicates the pointer to the platform device. 171 * 172 * @return Returns 0 if add successfully; returns a negative value otherwise. 173 * @since 1.0 174 */ 175 int32_t PlatformDeviceAdd(struct PlatformDevice *device); 176 177 /** 178 * @brief Remove a platform device by module type. 179 * 180 * do not call in irq context cause can sleep 181 * 182 * @param device Indicates the pointer to the platform device. 183 * 184 * @since 1.0 185 */ 186 void PlatformDeviceDel(struct PlatformDevice *device); 187 188 /** 189 * @brief Get device resource node of the device. 190 * 191 * @param device Indicates the pointer to the platform device. 192 * 193 * @return Returns the pointer to the resource node on success; returns NULL otherwise. 194 * @since 1.0 195 */ 196 const struct DeviceResourceNode *PlatformDeviceGetDrs(const struct PlatformDevice *device); 197 198 /** 199 * @brief Create a hdf device service for the platform device. 200 * 201 * @param device Indicates the pointer to the platform device. 202 * @param dispatch Dispatch function for the service. 203 * 204 * @return Returns 0 if create successfully; returns a negative value otherwise. 205 * @since 1.0 206 */ 207 int32_t PlatformDeviceCreateService(struct PlatformDevice *device, 208 int32_t (*dispatch)(struct HdfDeviceIoClient *client, int cmd, struct HdfSBuf *data, struct HdfSBuf *reply)); 209 210 /** 211 * @brief Destroy the hdf device service for the platform device. 212 * 213 * @param device Indicates the pointer to the platform device. 214 * 215 * @since 1.0 216 */ 217 void PlatformDeviceDestroyService(struct PlatformDevice *device); 218 219 /** 220 * @brief Bind to a hdf device object. 221 * 222 * @param device Indicates the pointer to the platform device. 223 * @param hdfDevice Indicates the pointer to the hdf device object. 224 * 225 * @return Returns 0 if bind successfully; returns a negative value otherwise. 226 * @since 1.0 227 */ 228 int32_t PlatformDeviceBind(struct PlatformDevice *device, struct HdfDeviceObject *hdfDevice); 229 230 /** 231 * @brief Unbind from a hdf device object. 232 * 233 * @param device Indicates the pointer to the platform device. 234 * @param hdfDevice Indicates the pointer to the hdf device object. 235 * 236 * @since 1.0 237 */ 238 void PlatformDeviceUnbind(struct PlatformDevice *device, const struct HdfDeviceObject *hdfDevice); 239 240 /** 241 * @brief Set a hdf device object for the platform device object. 242 * 243 * @param device Indicates the pointer to the platform device. 244 * @param hdfDevice Indicates the pointer to the hdf device object. 245 * 246 * @return Returns 0 if set successfully; returns a negative value otherwise. 247 * @since 1.0 248 */ 249 int32_t PlatformDeviceSetHdfDev(struct PlatformDevice *device, struct HdfDeviceObject *hdfDevice); 250 251 /** 252 * @brief Transform a hdf device object to a platform device object. 253 * 254 * @param device Indicates the pointer to the platform device. 255 * 256 * @return Returns the pointer to the platform device object on success; otherwise null. 257 * @since 1.0 258 */ 259 struct PlatformDevice *PlatformDeviceFromHdfDev(const struct HdfDeviceObject *hdfDev); 260 261 #ifdef __cplusplus 262 #if __cplusplus 263 } 264 #endif 265 #endif /* __cplusplus */ 266 267 #endif /* PLATFORM_DEVICE_H */ 268