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 */ 24extern struct kobjop_desc bus_alloc_resource_desc; 25/** @brief A function implementing the BUS_ALLOC_RESOURCE() method */ 26typedef 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 60static __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 */ 73extern struct kobjop_desc bus_child_pnpinfo_str_desc; 74/** @brief A function implementing the BUS_CHILD_PNPINFO_STR() method */ 75typedef 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 98static __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 */ 107extern struct kobjop_desc bus_child_location_str_desc; 108/** @brief A function implementing the BUS_CHILD_LOCATION_STR() method */ 109typedef 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 131static __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 */ 140extern struct kobjop_desc bus_print_child_desc; 141/** @brief A function implementing the BUS_PRINT_CHILD() method */ 142typedef 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 159static __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 */ 167extern struct kobjop_desc bus_probe_nomatch_desc; 168/** @brief A function implementing the BUS_PROBE_NOMATCH() method */ 169typedef 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 180static __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 */ 188extern struct kobjop_desc bus_read_ivar_desc; 189/** @brief A function implementing the BUS_READ_IVAR() method */ 190typedef 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 220static __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 */ 229extern struct kobjop_desc bus_write_ivar_desc; 230/** @brief A function implementing the BUS_WRITE_IVAR() method */ 231typedef 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 251static __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 */ 260extern struct kobjop_desc bus_child_deleted_desc; 261/** @brief A function implementing the BUS_CHILD_DELETED() method */ 262typedef 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 273static __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 */ 281extern struct kobjop_desc bus_child_detached_desc; 282/** @brief A function implementing the BUS_CHILD_DETACHED() method */ 283typedef 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 294static __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 */ 302extern struct kobjop_desc bus_driver_added_desc; 303/** @brief A function implementing the BUS_DRIVER_ADDED() method */ 304typedef 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 317static __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 */ 325extern struct kobjop_desc bus_add_child_desc; 326/** @brief A function implementing the BUS_ADD_CHILD() method */ 327typedef 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 351static __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 */ 360extern struct kobjop_desc bus_rescan_desc; 361/** @brief A function implementing the BUS_RESCAN() method */ 362typedef 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 373static __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 */ 381extern struct kobjop_desc bus_child_present_desc; 382/** @brief A function implementing the BUS_CHILD_PRESENT() method */ 383typedef 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 400static __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 */ 410extern struct kobjop_desc bus_hinted_child_desc; 411/** @brief A function implementing the BUS_HINTED_CHILD() method */ 412typedef 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 430static __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 */ 441extern struct kobjop_desc bus_hint_device_unit_desc; 442/** @brief A function implementing the BUS_HINT_DEVICE_UNIT() method */ 443typedef 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 454static __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 */ 463extern struct kobjop_desc bus_new_pass_desc; 464/** @brief A function implementing the BUS_NEW_PASS() method */ 465typedef 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 472static __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 */ 480extern struct kobjop_desc bus_suspend_child_desc; 481/** @brief A function implementing the BUS_SUSPEND_CHILD() method */ 482typedef 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 490static __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 */ 498extern struct kobjop_desc bus_resume_child_desc; 499/** @brief A function implementing the BUS_RESUME_CHILD() method */ 500typedef 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 508static __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 */ 516extern struct kobjop_desc bus_get_domain_desc; 517/** @brief A function implementing the BUS_GET_DOMAIN() method */ 518typedef 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 527static __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 */ 536extern struct kobjop_desc bus_reset_prepare_desc; 537/** @brief A function implementing the BUS_RESET_PREPARE() method */ 538typedef 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 553static __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 */ 561extern struct kobjop_desc bus_reset_post_desc; 562/** @brief A function implementing the BUS_RESET_POST() method */ 563typedef 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 574static __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 */ 582extern struct kobjop_desc bus_reset_child_desc; 583/** @brief A function implementing the BUS_RESET_CHILD() method */ 584typedef 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 593static __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