1 /* 2 * This file is produced automatically. 3 * Do not modify anything in here by hand. 4 * 5 * Created from source file 6 * bus_if.m 7 * with 8 * makeobjops.awk 9 * 10 * See the source file for legal information 11 */ 12 13 /** 14 * @defgroup BUS bus - KObj methods for drivers of devices with children 15 * @brief A set of methods required device drivers that support 16 * child devices. 17 * @{ 18 */ 19 20 #ifndef _bus_if_h_ 21 #define _bus_if_h_ 22 23 /** @brief Unique descriptor for the BUS_ALLOC_RESOURCE() method */ 24 extern struct kobjop_desc bus_alloc_resource_desc; 25 /** @brief A function implementing the BUS_ALLOC_RESOURCE() method */ 26 typedef struct resource * bus_alloc_resource_t(device_t _dev, device_t _child, 27 int _type, int *_rid, 28 rman_res_t _start, 29 rman_res_t _end, 30 rman_res_t _count, u_int _flags); 31 /** 32 * @brief Allocate a system resource 33 * 34 * This method is called by child devices of a bus to allocate resources. 35 * The types are defined in <machine/resource.h>; the meaning of the 36 * resource-ID field varies from bus to bus (but @p *rid == 0 is always 37 * valid if the resource type is). If a resource was allocated and the 38 * caller did not use the RF_ACTIVE to specify that it should be 39 * activated immediately, the caller is responsible for calling 40 * BUS_ACTIVATE_RESOURCE() when it actually uses the resource. 41 * 42 * @param _dev the parent device of @p _child 43 * @param _child the device which is requesting an allocation 44 * @param _type the type of resource to allocate 45 * @param _rid a pointer to the resource identifier 46 * @param _start hint at the start of the resource range - pass 47 * @c 0 for any start address 48 * @param _end hint at the end of the resource range - pass 49 * @c ~0 for any end address 50 * @param _count hint at the size of range required - pass @c 1 51 * for any size 52 * @param _flags any extra flags to control the resource 53 * allocation - see @c RF_XXX flags in 54 * <sys/rman.h> for details 55 * 56 * @returns the resource which was allocated or @c NULL if no 57 * resource could be allocated 58 */ 59 60 static __inline struct resource * BUS_ALLOC_RESOURCE(device_t _dev, 61 device_t _child, int _type, 62 int *_rid, 63 rman_res_t _start, 64 rman_res_t _end, 65 rman_res_t _count, 66 u_int _flags) 67 { 68 kobjop_t _m; 69 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_alloc_resource); 70 return ((bus_alloc_resource_t *) _m)(_dev, _child, _type, _rid, _start, _end, _count, _flags); 71 } 72 /** @brief Unique descriptor for the BUS_CHILD_PNPINFO_STR() method */ 73 extern struct kobjop_desc bus_child_pnpinfo_str_desc; 74 /** @brief A function implementing the BUS_CHILD_PNPINFO_STR() method */ 75 typedef int bus_child_pnpinfo_str_t(device_t _dev, device_t _child, char *_buf, 76 size_t _buflen); 77 78 /** 79 * @brief Returns the pnp info for this device. 80 * 81 * Return it as a string. If the storage is insufficient for the 82 * string, then return EOVERFLOW. 83 * 84 * The string must be formatted as a space-separated list of 85 * name=value pairs. Names may only contain alphanumeric characters, 86 * underscores ('_') and hyphens ('-'). Values can contain any 87 * non-whitespace characters. Values containing whitespace can be 88 * quoted with double quotes ('"'). Double quotes and backslashes in 89 * quoted values can be escaped with backslashes ('\'). 90 * 91 * @param _dev the parent device of @p _child 92 * @param _child the device which is being examined 93 * @param _buf the address of a buffer to receive the pnp 94 * string 95 * @param _buflen the size of the buffer pointed to by @p _buf 96 */ 97 98 static __inline int BUS_CHILD_PNPINFO_STR(device_t _dev, device_t _child, 99 char *_buf, size_t _buflen) 100 { 101 kobjop_t _m; 102 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_child_pnpinfo_str); 103 return ((bus_child_pnpinfo_str_t *) _m)(_dev, _child, _buf, _buflen); 104 } 105 106 /** @brief Unique descriptor for the BUS_CHILD_LOCATION_STR() method */ 107 extern struct kobjop_desc bus_child_location_str_desc; 108 /** @brief A function implementing the BUS_CHILD_LOCATION_STR() method */ 109 typedef int bus_child_location_str_t(device_t _dev, device_t _child, char *_buf, 110 size_t _buflen); 111 /** 112 * @brief Returns the location for this device. 113 * 114 * Return it as a string. If the storage is insufficient for the 115 * string, then return EOVERFLOW. 116 * 117 * The string must be formatted as a space-separated list of 118 * name=value pairs. Names may only contain alphanumeric characters, 119 * underscores ('_') and hyphens ('-'). Values can contain any 120 * non-whitespace characters. Values containing whitespace can be 121 * quoted with double quotes ('"'). Double quotes and backslashes in 122 * quoted values can be escaped with backslashes ('\'). 123 * 124 * @param _dev the parent device of @p _child 125 * @param _child the device which is being examined 126 * @param _buf the address of a buffer to receive the location 127 * string 128 * @param _buflen the size of the buffer pointed to by @p _buf 129 */ 130 131 static __inline int BUS_CHILD_LOCATION_STR(device_t _dev, device_t _child, 132 char *_buf, size_t _buflen) 133 { 134 kobjop_t _m; 135 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_child_location_str); 136 return ((bus_child_location_str_t *) _m)(_dev, _child, _buf, _buflen); 137 } 138 139 /** @brief Unique descriptor for the BUS_PRINT_CHILD() method */ 140 extern struct kobjop_desc bus_print_child_desc; 141 /** @brief A function implementing the BUS_PRINT_CHILD() method */ 142 typedef int bus_print_child_t(device_t _dev, device_t _child); 143 144 /** 145 * @brief Print a description of a child device 146 * 147 * This is called from system code which prints out a description of a 148 * device. It should describe the attachment that the child has with 149 * the parent. For instance the TurboLaser bus prints which node the 150 * device is attached to. See bus_generic_print_child() for more 151 * information. 152 * 153 * @param _dev the device whose child is being printed 154 * @param _child the child device to describe 155 * 156 * @returns the number of characters output. 157 */ 158 159 static __inline int BUS_PRINT_CHILD(device_t _dev, device_t _child) 160 { 161 kobjop_t _m; 162 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_print_child); 163 return ((bus_print_child_t *) _m)(_dev, _child); 164 } 165 166 /** @brief Unique descriptor for the BUS_PROBE_NOMATCH() method */ 167 extern struct kobjop_desc bus_probe_nomatch_desc; 168 /** @brief A function implementing the BUS_PROBE_NOMATCH() method */ 169 typedef void bus_probe_nomatch_t(device_t _dev, device_t _child); 170 /** 171 * @brief Print a notification about an unprobed child device. 172 * 173 * Called for each child device that did not succeed in probing for a 174 * driver. 175 * 176 * @param _dev the device whose child was being probed 177 * @param _child the child device which failed to probe 178 */ 179 180 static __inline void BUS_PROBE_NOMATCH(device_t _dev, device_t _child) 181 { 182 kobjop_t _m; 183 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_probe_nomatch); 184 ((bus_probe_nomatch_t *) _m)(_dev, _child); 185 } 186 187 /** @brief Unique descriptor for the BUS_READ_IVAR() method */ 188 extern struct kobjop_desc bus_read_ivar_desc; 189 /** @brief A function implementing the BUS_READ_IVAR() method */ 190 typedef int bus_read_ivar_t(device_t _dev, device_t _child, int _index, 191 uintptr_t *_result); 192 /** 193 * @brief Read the value of a bus-specific attribute of a device 194 * 195 * This method, along with BUS_WRITE_IVAR() manages a bus-specific set 196 * of instance variables of a child device. The intention is that 197 * each different type of bus defines a set of appropriate instance 198 * variables (such as ports and irqs for ISA bus etc.) 199 * 200 * This information could be given to the child device as a struct but 201 * that makes it hard for a bus to add or remove variables without 202 * forcing an edit and recompile for all drivers which may not be 203 * possible for vendor supplied binary drivers. 204 * 205 * This method copies the value of an instance variable to the 206 * location specified by @p *_result. 207 * 208 * @param _dev the device whose child was being examined 209 * @param _child the child device whose instance variable is 210 * being read 211 * @param _index the instance variable to read 212 * @param _result a location to receive the instance variable 213 * value 214 * 215 * @retval 0 success 216 * @retval ENOENT no such instance variable is supported by @p 217 * _dev 218 */ 219 220 static __inline int BUS_READ_IVAR(device_t _dev, device_t _child, int _index, 221 uintptr_t *_result) 222 { 223 kobjop_t _m; 224 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_read_ivar); 225 return ((bus_read_ivar_t *) _m)(_dev, _child, _index, _result); 226 } 227 228 /** @brief Unique descriptor for the BUS_WRITE_IVAR() method */ 229 extern struct kobjop_desc bus_write_ivar_desc; 230 /** @brief A function implementing the BUS_WRITE_IVAR() method */ 231 typedef int bus_write_ivar_t(device_t _dev, device_t _child, int _indx, 232 uintptr_t _value); 233 /** 234 * @brief Write the value of a bus-specific attribute of a device 235 * 236 * This method sets the value of an instance variable to @p _value. 237 * 238 * @param _dev the device whose child was being updated 239 * @param _child the child device whose instance variable is 240 * being written 241 * @param _index the instance variable to write 242 * @param _value the value to write to that instance variable 243 * 244 * @retval 0 success 245 * @retval ENOENT no such instance variable is supported by @p 246 * _dev 247 * @retval EINVAL the instance variable was recognised but 248 * contains a read-only value 249 */ 250 251 static __inline int BUS_WRITE_IVAR(device_t _dev, device_t _child, int _indx, 252 uintptr_t _value) 253 { 254 kobjop_t _m; 255 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_write_ivar); 256 return ((bus_write_ivar_t *) _m)(_dev, _child, _indx, _value); 257 } 258 259 /** @brief Unique descriptor for the BUS_CHILD_DELETED() method */ 260 extern struct kobjop_desc bus_child_deleted_desc; 261 /** @brief A function implementing the BUS_CHILD_DELETED() method */ 262 typedef void bus_child_deleted_t(device_t _dev, device_t _child); 263 /** 264 * @brief Notify a bus that a child was deleted 265 * 266 * Called at the beginning of device_delete_child() to allow the parent 267 * to teardown any bus-specific state for the child. 268 * 269 * @param _dev the device whose child is being deleted 270 * @param _child the child device which is being deleted 271 */ 272 273 static __inline void BUS_CHILD_DELETED(device_t _dev, device_t _child) 274 { 275 kobjop_t _m; 276 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_child_deleted); 277 ((bus_child_deleted_t *) _m)(_dev, _child); 278 } 279 280 /** @brief Unique descriptor for the BUS_CHILD_DETACHED() method */ 281 extern struct kobjop_desc bus_child_detached_desc; 282 /** @brief A function implementing the BUS_CHILD_DETACHED() method */ 283 typedef void bus_child_detached_t(device_t _dev, device_t _child); 284 /** 285 * @brief Notify a bus that a child was detached 286 * 287 * Called after the child's DEVICE_DETACH() method to allow the parent 288 * to reclaim any resources allocated on behalf of the child. 289 * 290 * @param _dev the device whose child changed state 291 * @param _child the child device which changed state 292 */ 293 294 static __inline void BUS_CHILD_DETACHED(device_t _dev, device_t _child) 295 { 296 kobjop_t _m; 297 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_child_detached); 298 ((bus_child_detached_t *) _m)(_dev, _child); 299 } 300 301 /** @brief Unique descriptor for the BUS_DRIVER_ADDED() method */ 302 extern struct kobjop_desc bus_driver_added_desc; 303 /** @brief A function implementing the BUS_DRIVER_ADDED() method */ 304 typedef void bus_driver_added_t(device_t _dev, driver_t *_driver); 305 /** 306 * @brief Notify a bus that a new driver was added 307 * 308 * Called when a new driver is added to the devclass which owns this 309 * bus. The generic implementation of this method attempts to probe and 310 * attach any un-matched children of the bus. 311 * 312 * @param _dev the device whose devclass had a new driver 313 * added to it 314 * @param _driver the new driver which was added 315 */ 316 317 static __inline void BUS_DRIVER_ADDED(device_t _dev, driver_t *_driver) 318 { 319 kobjop_t _m; 320 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_driver_added); 321 ((bus_driver_added_t *) _m)(_dev, _driver); 322 } 323 324 /** @brief Unique descriptor for the BUS_ADD_CHILD() method */ 325 extern struct kobjop_desc bus_add_child_desc; 326 /** @brief A function implementing the BUS_ADD_CHILD() method */ 327 typedef device_t bus_add_child_t(device_t _dev, u_int _order, const char *_name, 328 int _unit); 329 /** 330 * @brief Create a new child device 331 * 332 * For busses which use use drivers supporting DEVICE_IDENTIFY() to 333 * enumerate their devices, this method is used to create new 334 * device instances. The new device will be added after the last 335 * existing child with the same order. Implementations of bus_add_child 336 * call device_add_child_ordered to add the child and often add 337 * a suitable ivar to the device specific to that bus. 338 * 339 * @param _dev the bus device which will be the parent of the 340 * new child device 341 * @param _order a value which is used to partially sort the 342 * children of @p _dev - devices created using 343 * lower values of @p _order appear first in @p 344 * _dev's list of children 345 * @param _name devclass name for new device or @c NULL if not 346 * specified 347 * @param _unit unit number for new device or @c -1 if not 348 * specified 349 */ 350 351 static __inline device_t BUS_ADD_CHILD(device_t _dev, u_int _order, 352 const char *_name, int _unit) 353 { 354 kobjop_t _m; 355 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_add_child); 356 return ((bus_add_child_t *) _m)(_dev, _order, _name, _unit); 357 } 358 359 /** @brief Unique descriptor for the BUS_RESCAN() method */ 360 extern struct kobjop_desc bus_rescan_desc; 361 /** @brief A function implementing the BUS_RESCAN() method */ 362 typedef int bus_rescan_t(device_t _dev); 363 /** 364 * @brief Rescan the bus 365 * 366 * This method is called by a parent bridge or devctl to trigger a bus 367 * rescan. The rescan should delete devices no longer present and 368 * enumerate devices that have newly arrived. 369 * 370 * @param _dev the bus device 371 */ 372 373 static __inline int BUS_RESCAN(device_t _dev) 374 { 375 kobjop_t _m; 376 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_rescan); 377 return ((bus_rescan_t *) _m)(_dev); 378 } 379 380 /** @brief Unique descriptor for the BUS_CHILD_PRESENT() method */ 381 extern struct kobjop_desc bus_child_present_desc; 382 /** @brief A function implementing the BUS_CHILD_PRESENT() method */ 383 typedef int bus_child_present_t(device_t _dev, device_t _child); 384 /** 385 * @brief Is the hardware described by @p _child still attached to the 386 * system? 387 * 388 * This method should return 0 if the device is not present. It 389 * should return -1 if it is present. Any errors in determining 390 * should be returned as a normal errno value. Client drivers are to 391 * assume that the device is present, even if there is an error 392 * determining if it is there. Busses are to try to avoid returning 393 * errors, but newcard will return an error if the device fails to 394 * implement this method. 395 * 396 * @param _dev the parent device of @p _child 397 * @param _child the device which is being examined 398 */ 399 400 static __inline int BUS_CHILD_PRESENT(device_t _dev, device_t _child) 401 { 402 kobjop_t _m; 403 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_child_present); 404 return ((bus_child_present_t *) _m)(_dev, _child); 405 } 406 407 // delete resource and interrupt 408 409 /** @brief Unique descriptor for the BUS_HINTED_CHILD() method */ 410 extern struct kobjop_desc bus_hinted_child_desc; 411 /** @brief A function implementing the BUS_HINTED_CHILD() method */ 412 typedef void bus_hinted_child_t(device_t _dev, const char *_dname, int _dunit); 413 /** 414 * @brief Notify a (bus) driver about a child that the hints mechanism 415 * believes it has discovered. 416 * 417 * The bus is responsible for then adding the child in the right order 418 * and discovering other things about the child. The bus driver is 419 * free to ignore this hint, to do special things, etc. It is all up 420 * to the bus driver to interpret. 421 * 422 * This method is only called in response to the parent bus asking for 423 * hinted devices to be enumerated. 424 * 425 * @param _dev the bus device 426 * @param _dname the name of the device w/o unit numbers 427 * @param _dunit the unit number of the device 428 */ 429 430 static __inline void BUS_HINTED_CHILD(device_t _dev, const char *_dname, 431 int _dunit) 432 { 433 kobjop_t _m; 434 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_hinted_child); 435 ((bus_hinted_child_t *) _m)(_dev, _dname, _dunit); 436 } 437 438 // delete dma 439 440 /** @brief Unique descriptor for the BUS_HINT_DEVICE_UNIT() method */ 441 extern struct kobjop_desc bus_hint_device_unit_desc; 442 /** @brief A function implementing the BUS_HINT_DEVICE_UNIT() method */ 443 typedef void bus_hint_device_unit_t(device_t _dev, device_t _child, 444 const char *_name, int *_unitp); 445 /** 446 * @brief Allow the bus to determine the unit number of a device. 447 * 448 * @param _dev the parent device of @p _child 449 * @param _child the device whose unit is to be wired 450 * @param _name the name of the device's new devclass 451 * @param _unitp a pointer to the device's new unit value 452 */ 453 454 static __inline void BUS_HINT_DEVICE_UNIT(device_t _dev, device_t _child, 455 const char *_name, int *_unitp) 456 { 457 kobjop_t _m; 458 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_hint_device_unit); 459 ((bus_hint_device_unit_t *) _m)(_dev, _child, _name, _unitp); 460 } 461 462 /** @brief Unique descriptor for the BUS_NEW_PASS() method */ 463 extern struct kobjop_desc bus_new_pass_desc; 464 /** @brief A function implementing the BUS_NEW_PASS() method */ 465 typedef void bus_new_pass_t(device_t _dev); 466 /** 467 * @brief Notify a bus that the bus pass level has been changed 468 * 469 * @param _dev the bus device 470 */ 471 472 static __inline void BUS_NEW_PASS(device_t _dev) 473 { 474 kobjop_t _m; 475 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_new_pass); 476 ((bus_new_pass_t *) _m)(_dev); 477 } 478 479 /** @brief Unique descriptor for the BUS_SUSPEND_CHILD() method */ 480 extern struct kobjop_desc bus_suspend_child_desc; 481 /** @brief A function implementing the BUS_SUSPEND_CHILD() method */ 482 typedef int bus_suspend_child_t(device_t _dev, device_t _child); 483 /** 484 * @brief Suspend a given child 485 * 486 * @param _dev the parent device of @p _child 487 * @param _child the device to suspend 488 */ 489 490 static __inline int BUS_SUSPEND_CHILD(device_t _dev, device_t _child) 491 { 492 kobjop_t _m; 493 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_suspend_child); 494 return ((bus_suspend_child_t *) _m)(_dev, _child); 495 } 496 497 /** @brief Unique descriptor for the BUS_RESUME_CHILD() method */ 498 extern struct kobjop_desc bus_resume_child_desc; 499 /** @brief A function implementing the BUS_RESUME_CHILD() method */ 500 typedef int bus_resume_child_t(device_t _dev, device_t _child); 501 /** 502 * @brief Resume a given child 503 * 504 * @param _dev the parent device of @p _child 505 * @param _child the device to resume 506 */ 507 508 static __inline int BUS_RESUME_CHILD(device_t _dev, device_t _child) 509 { 510 kobjop_t _m; 511 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_resume_child); 512 return ((bus_resume_child_t *) _m)(_dev, _child); 513 } 514 515 /** @brief Unique descriptor for the BUS_GET_DOMAIN() method */ 516 extern struct kobjop_desc bus_get_domain_desc; 517 /** @brief A function implementing the BUS_GET_DOMAIN() method */ 518 typedef int bus_get_domain_t(device_t _dev, device_t _child, int *_domain); 519 /** 520 * @brief Get the VM domain handle for the given bus and child. 521 * 522 * @param _dev the bus device 523 * @param _child the child device 524 * @param _domain a pointer to the bus's domain handle identifier 525 */ 526 527 static __inline int BUS_GET_DOMAIN(device_t _dev, device_t _child, int *_domain) 528 { 529 kobjop_t _m; 530 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_get_domain); 531 return ((bus_get_domain_t *) _m)(_dev, _child, _domain); 532 } 533 534 535 /** @brief Unique descriptor for the BUS_RESET_PREPARE() method */ 536 extern struct kobjop_desc bus_reset_prepare_desc; 537 /** @brief A function implementing the BUS_RESET_PREPARE() method */ 538 typedef int bus_reset_prepare_t(device_t _dev, device_t _child); 539 /** 540 * @brief Prepares the given child of the bus for reset 541 * 542 * Typically bus detaches or suspends children' drivers, and then 543 * calls this method to save bus-specific information, for instance, 544 * PCI config space, which is damaged by reset. 545 * 546 * The bus_helper_reset_prepare() helper is provided to ease 547 * implementing bus reset methods. 548 * 549 * @param _dev the bus device 550 * @param _child the child device 551 */ 552 553 static __inline int BUS_RESET_PREPARE(device_t _dev, device_t _child) 554 { 555 kobjop_t _m; 556 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_reset_prepare); 557 return ((bus_reset_prepare_t *) _m)(_dev, _child); 558 } 559 560 /** @brief Unique descriptor for the BUS_RESET_POST() method */ 561 extern struct kobjop_desc bus_reset_post_desc; 562 /** @brief A function implementing the BUS_RESET_POST() method */ 563 typedef int bus_reset_post_t(device_t _dev, device_t _child); 564 /** 565 * @brief Restores the child operations after the reset 566 * 567 * The bus_helper_reset_post() helper is provided to ease 568 * implementing bus reset methods. 569 * 570 * @param _dev the bus device 571 * @param _child the child device 572 */ 573 574 static __inline int BUS_RESET_POST(device_t _dev, device_t _child) 575 { 576 kobjop_t _m; 577 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_reset_post); 578 return ((bus_reset_post_t *) _m)(_dev, _child); 579 } 580 581 /** @brief Unique descriptor for the BUS_RESET_CHILD() method */ 582 extern struct kobjop_desc bus_reset_child_desc; 583 /** @brief A function implementing the BUS_RESET_CHILD() method */ 584 typedef int bus_reset_child_t(device_t _dev, device_t _child, int _flags); 585 /** 586 * @brief Performs reset of the child 587 * 588 * @param _dev the bus device 589 * @param _child the child device 590 * @param _flags DEVF_RESET_ flags 591 */ 592 593 static __inline int BUS_RESET_CHILD(device_t _dev, device_t _child, int _flags) 594 { 595 kobjop_t _m; 596 KOBJOPLOOKUP(((kobj_t)_dev)->ops,bus_reset_child); 597 return ((bus_reset_child_t *) _m)(_dev, _child, _flags); 598 } 599 600 #endif /* _bus_if_h_ */ 601