1 /* 2 * This file is produced automatically. 3 * Do not modify anything in here by hand. 4 * 5 * Created from source file 6 * device_if.m 7 * with 8 * makeobjops.awk 9 * 10 * See the source file for legal information 11 */ 12 13 /** 14 * @defgroup DEVICE device - KObj methods for all device drivers 15 * @brief A basic set of methods required for all device drivers. 16 * 17 * The device interface is used to match devices to drivers during 18 * autoconfiguration and provides methods to allow drivers to handle 19 * system-wide events such as suspend, resume or shutdown. 20 * @{ 21 */ 22 23 #ifndef _device_if_h_ 24 #define _device_if_h_ 25 26 /** @brief Unique descriptor for the DEVICE_PROBE() method */ 27 extern struct kobjop_desc device_probe_desc; 28 /** @brief A function implementing the DEVICE_PROBE() method */ 29 typedef int device_probe_t(device_t dev); 30 /** 31 * @brief Probe to see if a device matches a driver. 32 * 33 * Users should not call this method directly. Normally, this 34 * is called via device_probe_and_attach() to select a driver 35 * calling the DEVICE_PROBE() of all candidate drivers and attach 36 * the winning driver (if any) to the device. 37 * 38 * This function is used to match devices to device drivers. 39 * Typically, the driver will examine the device to see if 40 * it is suitable for this driver. This might include checking 41 * the values of various device instance variables or reading 42 * hardware registers. 43 * 44 * In some cases, there may be more than one driver available 45 * which can be used for a device (for instance there might 46 * be a generic driver which works for a set of many types of 47 * device and a more specific driver which works for a subset 48 * of devices). Because of this, a driver should not assume 49 * that it will be the driver that attaches to the device even 50 * if it returns a success status from DEVICE_PROBE(). In particular, 51 * a driver must free any resources which it allocated during 52 * the probe before returning. The return value of DEVICE_PROBE() 53 * is used to elect which driver is used - the driver which returns 54 * the largest non-error value wins the election and attaches to 55 * the device. Common non-error values are described in the 56 * DEVICE_PROBE(9) manual page. 57 * 58 * If a driver matches the hardware, it should set the device 59 * description string using device_set_desc() or 60 * device_set_desc_copy(). This string is used to generate an 61 * informative message when DEVICE_ATTACH() is called. 62 * 63 * As a special case, if a driver returns zero, the driver election 64 * is cut short and that driver will attach to the device 65 * immediately. This should rarely be used. 66 * 67 * For example, a probe method for a PCI device driver might look 68 * like this: 69 * 70 * @code 71 * int 72 * foo_probe(device_t dev) 73 * { 74 * if (pci_get_vendor(dev) == FOOVENDOR && 75 * pci_get_device(dev) == FOODEVICE) { 76 * device_set_desc(dev, "Foo device"); 77 * return (BUS_PROBE_DEFAULT); 78 * } 79 * return (ENXIO); 80 * } 81 * @endcode 82 * 83 * To include this method in a device driver, use a line like this 84 * in the driver's method list: 85 * 86 * @code 87 * KOBJMETHOD(device_probe, foo_probe) 88 * @endcode 89 * 90 * @param dev the device to probe 91 * 92 * @retval 0 if this is the only possible driver for this 93 * device 94 * @retval negative if the driver can match this device - the 95 * least negative value is used to select the 96 * driver 97 * @retval ENXIO if the driver does not match the device 98 * @retval positive if some kind of error was detected during 99 * the probe, a regular unix error code should 100 * be returned to indicate the type of error 101 * @see DEVICE_ATTACH(), pci_get_vendor(), pci_get_device() 102 */ 103 104 static __inline int DEVICE_PROBE(device_t dev) 105 { 106 kobjop_t _m; 107 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_probe); 108 return ((device_probe_t *) _m)(dev); 109 } 110 111 /** @brief Unique descriptor for the DEVICE_IDENTIFY() method */ 112 extern struct kobjop_desc device_identify_desc; 113 /** @brief A function implementing the DEVICE_IDENTIFY() method */ 114 typedef void device_identify_t(driver_t *driver, device_t parent); 115 /** 116 * @brief Allow a device driver to detect devices not otherwise enumerated. 117 * 118 * The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA 119 * bus driver) to help populate the bus device with a useful set of 120 * child devices, normally by calling the BUS_ADD_CHILD() method of 121 * the parent device. For instance, the ISA bus driver uses several 122 * special drivers, including the isahint driver and the pnp driver to 123 * create child devices based on configuration hints and PnP bus 124 * probes respectively. 125 * 126 * Many bus drivers which support true plug-and-play do not need to 127 * use this method at all since child devices can be discovered 128 * automatically without help from child drivers. 129 * 130 * To include this method in a device driver, use a line like this 131 * in the driver's method list: 132 * 133 * @code 134 * KOBJMETHOD(device_identify, foo_identify) 135 * @endcode 136 * 137 * @param driver the driver whose identify method is being called 138 * @param parent the parent device to use when adding new children 139 */ 140 141 static __inline void DEVICE_IDENTIFY(driver_t *driver, device_t parent) 142 { 143 kobjop_t _m; 144 KOBJOPLOOKUP(driver->ops,device_identify); 145 ((device_identify_t *) _m)(driver, parent); 146 } 147 148 /** @brief Unique descriptor for the DEVICE_ATTACH() method */ 149 extern struct kobjop_desc device_attach_desc; 150 /** @brief A function implementing the DEVICE_ATTACH() method */ 151 typedef int device_attach_t(device_t dev); 152 /** 153 * @brief Attach a device to a device driver 154 * 155 * Normally only called via device_probe_and_attach(), this is called 156 * when a driver has succeeded in probing against a device. 157 * This method should initialise the hardware and allocate other 158 * system resources (e.g. devfs entries) as required. 159 * 160 * To include this method in a device driver, use a line like this 161 * in the driver's method list: 162 * 163 * @code 164 * KOBJMETHOD(device_attach, foo_attach) 165 * @endcode 166 * 167 * @param dev the device to probe 168 * 169 * @retval 0 success 170 * @retval non-zero if some kind of error was detected during 171 * the attach, a regular unix error code should 172 * be returned to indicate the type of error 173 * @see DEVICE_PROBE() 174 */ 175 176 static __inline int DEVICE_ATTACH(device_t dev) 177 { 178 kobjop_t _m; 179 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_attach); 180 return ((device_attach_t *) _m)(dev); 181 } 182 183 /** @brief Unique descriptor for the DEVICE_DETACH() method */ 184 extern struct kobjop_desc device_detach_desc; 185 /** @brief A function implementing the DEVICE_DETACH() method */ 186 typedef int device_detach_t(device_t dev); 187 /** 188 * @brief Detach a driver from a device. 189 * 190 * This can be called if the user is replacing the 191 * driver software or if a device is about to be physically removed 192 * from the system (e.g. for removable hardware such as USB or PCCARD). 193 * 194 * To include this method in a device driver, use a line like this 195 * in the driver's method list: 196 * 197 * @code 198 * KOBJMETHOD(device_detach, foo_detach) 199 * @endcode 200 * 201 * @param dev the device to detach 202 * 203 * @retval 0 success 204 * @retval non-zero the detach could not be performed, e.g. if the 205 * driver does not support detaching. 206 * 207 * @see DEVICE_ATTACH() 208 */ 209 210 static __inline int DEVICE_DETACH(device_t dev) 211 { 212 kobjop_t _m; 213 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_detach); 214 return ((device_detach_t *) _m)(dev); 215 } 216 217 /** @brief Unique descriptor for the DEVICE_SHUTDOWN() method */ 218 extern struct kobjop_desc device_shutdown_desc; 219 /** @brief A function implementing the DEVICE_SHUTDOWN() method */ 220 typedef int device_shutdown_t(device_t dev); 221 /** 222 * @brief Called during system shutdown. 223 * 224 * This method allows drivers to detect when the system is being shut down. 225 * Some drivers need to use this to place their hardware in a consistent 226 * state before rebooting the computer. 227 * 228 * To include this method in a device driver, use a line like this 229 * in the driver's method list: 230 * 231 * @code 232 * KOBJMETHOD(device_shutdown, foo_shutdown) 233 * @endcode 234 */ 235 236 static __inline int DEVICE_SHUTDOWN(device_t dev) 237 { 238 kobjop_t _m; 239 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_shutdown); 240 return ((device_shutdown_t *) _m)(dev); 241 } 242 243 /** @brief Unique descriptor for the DEVICE_SUSPEND() method */ 244 extern struct kobjop_desc device_suspend_desc; 245 /** @brief A function implementing the DEVICE_SUSPEND() method */ 246 typedef int device_suspend_t(device_t dev); 247 /** 248 * @brief This is called by the power-management subsystem when a 249 * suspend has been requested by the user or by some automatic 250 * mechanism. 251 * 252 * This gives drivers a chance to veto the suspend or save their 253 * configuration before power is removed. 254 * 255 * To include this method in a device driver, use a line like this in 256 * the driver's method list: 257 * 258 * @code 259 * KOBJMETHOD(device_suspend, foo_suspend) 260 * @endcode 261 * 262 * @param dev the device being suspended 263 * 264 * @retval 0 success 265 * @retval non-zero an error occurred while attempting to prepare the 266 * device for suspension 267 * 268 * @see DEVICE_RESUME() 269 */ 270 271 static __inline int DEVICE_SUSPEND(device_t dev) 272 { 273 kobjop_t _m; 274 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_suspend); 275 return ((device_suspend_t *) _m)(dev); 276 } 277 278 /** @brief Unique descriptor for the DEVICE_RESUME() method */ 279 extern struct kobjop_desc device_resume_desc; 280 /** @brief A function implementing the DEVICE_RESUME() method */ 281 typedef int device_resume_t(device_t dev); 282 /** 283 * @brief This is called when the system resumes after a suspend. 284 * 285 * To include this method in a device driver, use a line like this 286 * in the driver's method list: 287 * 288 * @code 289 * KOBJMETHOD(device_resume, foo_resume) 290 * @endcode 291 * 292 * @param dev the device being resumed 293 * 294 * @retval 0 success 295 * @retval non-zero an error occurred while attempting to restore the 296 * device from suspension 297 * 298 * @see DEVICE_SUSPEND() 299 */ 300 301 static __inline int DEVICE_RESUME(device_t dev) 302 { 303 kobjop_t _m; 304 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_resume); 305 return ((device_resume_t *) _m)(dev); 306 } 307 308 /** @brief Unique descriptor for the DEVICE_QUIESCE() method */ 309 extern struct kobjop_desc device_quiesce_desc; 310 /** @brief A function implementing the DEVICE_QUIESCE() method */ 311 typedef int device_quiesce_t(device_t dev); 312 /** 313 * @brief This is called when the driver is asked to quiesce itself. 314 * 315 * The driver should arrange for the orderly shutdown of this device. 316 * All further access to the device should be curtailed. Soon there 317 * will be a request to detach, but there won't necessarily be one. 318 * 319 * To include this method in a device driver, use a line like this 320 * in the driver's method list: 321 * 322 * @code 323 * KOBJMETHOD(device_quiesce, foo_quiesce) 324 * @endcode 325 * 326 * @param dev the device being quiesced 327 * 328 * @retval 0 success 329 * @retval non-zero an error occurred while attempting to quiesce the 330 * device 331 * 332 * @see DEVICE_DETACH() 333 */ 334 335 static __inline int DEVICE_QUIESCE(device_t dev) 336 { 337 kobjop_t _m; 338 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_quiesce); 339 return ((device_quiesce_t *) _m)(dev); 340 } 341 342 /** @brief Unique descriptor for the DEVICE_REGISTER() method */ 343 extern struct kobjop_desc device_register_desc; 344 /** @brief A function implementing the DEVICE_REGISTER() method */ 345 typedef void * device_register_t(device_t dev); 346 /** 347 * @brief This is called when the driver is asked to register handlers. 348 * 349 * 350 * To include this method in a device driver, use a line like this 351 * in the driver's method list: 352 * 353 * @code 354 * KOBJMETHOD(device_register, foo_register) 355 * @endcode 356 * 357 * @param dev the device for which handlers are being registered 358 * 359 * @retval NULL method not implemented 360 * @retval non-NULL a pointer to implementation specific static driver state 361 * 362 */ 363 364 static __inline void * DEVICE_REGISTER(device_t dev) 365 { 366 kobjop_t _m; 367 KOBJOPLOOKUP(((kobj_t)dev)->ops,device_register); 368 return ((device_register_t *) _m)(dev); 369 } 370 371 #endif /* _device_if_h_ */ 372