share/man/man9/pci.9

   1 .\"
   2 .\" Copyright (c) 2005 Bruce M Simpson <bms@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd January 15, 2017
  29 .Dt PCI 9
  30 .Os
  31 .Sh NAME
  32 .Nm pci ,
  33 .Nm pci_alloc_msi ,
  34 .Nm pci_alloc_msix ,
  35 .Nm pci_disable_busmaster ,
  36 .Nm pci_disable_io ,
  37 .Nm pci_enable_busmaster ,
  38 .Nm pci_enable_io ,
  39 .Nm pci_find_bsf ,
  40 .Nm pci_find_cap ,
  41 .Nm pci_find_dbsf ,
  42 .Nm pci_find_device ,
  43 .Nm pci_find_extcap ,
  44 .Nm pci_find_htcap ,
  45 .Nm pci_find_next_cap ,
  46 .Nm pci_find_next_extcap ,
  47 .Nm pci_find_next_htcap ,
  48 .Nm pci_find_pcie_root_port ,
  49 .Nm pci_get_id ,
  50 .Nm pci_get_max_payload ,
  51 .Nm pci_get_max_read_req ,
  52 .Nm pci_get_powerstate ,
  53 .Nm pci_get_vpd_ident ,
  54 .Nm pci_get_vpd_readonly ,
  55 .Nm pci_iov_attach ,
  56 .Nm pci_iov_attach_name ,
  57 .Nm pci_iov_detach ,
  58 .Nm pci_msi_count ,
  59 .Nm pci_msix_count ,
  60 .Nm pci_msix_pba_bar ,
  61 .Nm pci_msix_table_bar ,
  62 .Nm pci_pending_msix ,
  63 .Nm pci_read_config ,
  64 .Nm pci_release_msi ,
  65 .Nm pci_remap_msix ,
  66 .Nm pci_restore_state ,
  67 .Nm pci_save_state ,
  68 .Nm pci_set_max_read_req ,
  69 .Nm pci_set_powerstate ,
  70 .Nm pci_write_config ,
  71 .Nm pcie_adjust_config ,
  72 .Nm pcie_flr ,
  73 .Nm pcie_get_max_completion_timeout ,
  74 .Nm pcie_read_config ,
  75 .Nm pcie_wait_for_pending_transactions ,
  76 .Nm pcie_write_config
  77 .Nd PCI bus interface
  78 .Sh SYNOPSIS
  79 .In sys/bus.h
  80 .In dev/pci/pcireg.h
  81 .In dev/pci/pcivar.h
  82 .Ft int
  83 .Fn pci_alloc_msi "device_t dev" "int *count"
  84 .Ft int
  85 .Fn pci_alloc_msix "device_t dev" "int *count"
  86 .Ft int
  87 .Fn pci_disable_busmaster "device_t dev"
  88 .Ft int
  89 .Fn pci_disable_io "device_t dev" "int space"
  90 .Ft int
  91 .Fn pci_enable_busmaster "device_t dev"
  92 .Ft int
  93 .Fn pci_enable_io "device_t dev" "int space"
  94 .Ft device_t
  95 .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
  96 .Ft int
  97 .Fn pci_find_cap "device_t dev" "int capability" "int *capreg"
  98 .Ft device_t
  99 .Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func"
 100 .Ft device_t
 101 .Fn pci_find_device "uint16_t vendor" "uint16_t device"
 102 .Ft int
 103 .Fn pci_find_extcap "device_t dev" "int capability" "int *capreg"
 104 .Ft int
 105 .Fn pci_find_htcap "device_t dev" "int capability" "int *capreg"
 106 .Ft int
 107 .Fn pci_find_next_cap "device_t dev" "int capability" "int start" "int *capreg"
 108 .Ft int
 109 .Fn pci_find_next_extcap "device_t dev" "int capability" "int start" "int *capreg"
 110 .Ft int
 111 .Fn pci_find_next_htcap "device_t dev" "int capability" "int start" "int *capreg"
 112 .Ft device_t
 113 .Fn pci_find_pcie_root_port "device_t dev"
 114 .Ft int
 115 .Fn pci_get_id "device_t dev" "enum pci_id_type type" "uintptr_t *id"
 116 .Ft int
 117 .Fn pci_get_max_payload "device_t dev"
 118 .Ft int
 119 .Fn pci_get_max_read_req "device_t dev"
 120 .Ft int
 121 .Fn pci_get_powerstate "device_t dev"
 122 .Ft int
 123 .Fn pci_get_vpd_ident "device_t dev" "const char **identptr"
 124 .Ft int
 125 .Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr"
 126 .Ft int
 127 .Fn pci_msi_count "device_t dev"
 128 .Ft int
 129 .Fn pci_msix_count "device_t dev"
 130 .Ft int
 131 .Fn pci_msix_pba_bar "device_t dev"
 132 .Ft int
 133 .Fn pci_msix_table_bar "device_t dev"
 134 .Ft int
 135 .Fn pci_pending_msix "device_t dev" "u_int index"
 136 .Ft uint32_t
 137 .Fn pci_read_config "device_t dev" "int reg" "int width"
 138 .Ft int
 139 .Fn pci_release_msi "device_t dev"
 140 .Ft int
 141 .Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors"
 142 .Ft void
 143 .Fn pci_restore_state "device_t dev"
 144 .Ft void
 145 .Fn pci_save_state "device_t dev"
 146 .Ft int
 147 .Fn pci_set_max_read_req "device_t dev" "int size"
 148 .Ft int
 149 .Fn pci_set_powerstate "device_t dev" "int state"
 150 .Ft void
 151 .Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width"
 152 .Ft uint32_t
 153 .Fo pcie_adjust_config
 154 .Fa "device_t dev"
 155 .Fa "int reg"
 156 .Fa "uint32_t mask"
 157 .Fa "uint32_t val"
 158 .Fa "int width"
 159 .Fc
 160 .Ft bool
 161 .Fn pcie_flr "device_t dev" "u_int max_delay" "bool force"
 162 .Ft int
 163 .Fn pcie_get_max_completion_timeout "device_t dev"
 164 .Ft uint32_t
 165 .Fn pcie_read_config "device_t dev" "int reg" "int width"
 166 .Ft bool
 167 .Fn pcie_wait_for_pending_transactions "device_t dev" "u_int max_delay"
 168 .Ft void
 169 .Fn pcie_write_config "device_t dev" "int reg" "uint32_t val" "int width"
 170 .Ft void
 171 .Fn pci_event_fn "void *arg" "device_t dev"
 172 .Fn EVENTHANDLER_REGISTER "pci_add_device" "pci_event_fn"
 173 .Fn EVENTHANDLER_DEREGISTER "pci_delete_resource" "pci_event_fn"
 174 .In dev/pci/pci_iov.h
 175 .Ft int
 176 .Fn pci_iov_attach "device_t dev" "nvlist_t *pf_schema" "nvlist_t *vf_schema"
 177 .Ft int
 178 .Fo pci_iov_attach_name
 179 .Fa "device_t dev"
 180 .Fa "nvlist_t *pf_schema"
 181 .Fa "nvlist_t *vf_schema"
 182 .Fa "const char *fmt"
 183 .Fa "..."
 184 .Fc
 185 .Ft int
 186 .Fn pci_iov_detach "device_t dev"
 187 .Sh DESCRIPTION
 188 The
 189 .Nm
 190 set of functions are used for managing PCI devices.
 191 The functions are split into several groups:
 192 raw configuration access,
 193 locating devices,
 194 device information,
 195 device configuration,
 196 and
 197 message signaled interrupts.
 198 .Ss Raw Configuration Access
 199 The
 200 .Fn pci_read_config
 201 function is used to read data from the PCI configuration
 202 space of the device
 203 .Fa dev ,
 204 at offset
 205 .Fa reg ,
 206 with
 207 .Fa width
 208 specifying the size of the access.
 209 .Pp
 210 The
 211 .Fn pci_write_config
 212 function is used to write the value
 213 .Fa val
 214 to the PCI configuration
 215 space of the device
 216 .Fa dev ,
 217 at offset
 218 .Fa reg ,
 219 with
 220 .Fa width
 221 specifying the size of the access.
 222 .Pp
 223 The
 224 .Fn pcie_adjust_config
 225 function is used to modify the value of a register in the PCI-express
 226 capability register set of device
 227 .Fa dev .
 228 The offset
 229 .Fa reg
 230 specifies a relative offset in the register set with
 231 .Fa width
 232 specifying the size of the access.
 233 The new value of the register is computed by modifying bits set in
 234 .Fa mask
 235 to the value in
 236 .Fa val .
 237 Any bits not specified in
 238 .Fa mask
 239 are preserved.
 240 The previous value of the register is returned.
 241 .Pp
 242 The
 243 .Fn pcie_read_config
 244 function is used to read the value of a register in the PCI-express
 245 capability register set of device
 246 .Fa dev .
 247 The offset
 248 .Fa reg
 249 specifies a relative offset in the register set with
 250 .Fa width
 251 specifying the size of the access.
 252 .Pp
 253 The
 254 .Fn pcie_write_config
 255 function is used to write the value
 256 .Fa val
 257 to a register in the PCI-express capability register set of device
 258 .Fa dev .
 259 The offset
 260 .Fa reg
 261 specifies a relative offset in the register set with
 262 .Fa width
 263 specifying the size of the access.
 264 .Pp
 265 .Em NOTE :
 266 Device drivers should only use these functions for functionality that
 267 is not available via another
 268 .Fn pci
 269 function.
 270 .Ss Locating Devices
 271 The
 272 .Fn pci_find_bsf
 273 function looks up the
 274 .Vt device_t
 275 of a PCI device, given its
 276 .Fa bus ,
 277 .Fa slot ,
 278 and
 279 .Fa func .
 280 The
 281 .Fa slot
 282 number actually refers to the number of the device on the bus,
 283 which does not necessarily indicate its geographic location
 284 in terms of a physical slot.
 285 Note that in case the system has multiple PCI domains,
 286 the
 287 .Fn pci_find_bsf
 288 function only searches the first one.
 289 Actually, it is equivalent to:
 290 .Bd -literal -offset indent
 291 pci_find_dbsf(0, bus, slot, func);
 292 .Ed
 293 .Pp
 294 The
 295 .Fn pci_find_dbsf
 296 function looks up the
 297 .Vt device_t
 298 of a PCI device, given its
 299 .Fa domain ,
 300 .Fa bus ,
 301 .Fa slot ,
 302 and
 303 .Fa func .
 304 The
 305 .Fa slot
 306 number actually refers to the number of the device on the bus,
 307 which does not necessarily indicate its geographic location
 308 in terms of a physical slot.
 309 .Pp
 310 The
 311 .Fn pci_find_device
 312 function looks up the
 313 .Vt device_t
 314 of a PCI device, given its
 315 .Fa vendor
 316 and
 317 .Fa device
 318 IDs.
 319 Note that there can be multiple matches for this search; this function
 320 only returns the first matching device.
 321 .Ss Device Information
 322 The
 323 .Fn pci_find_cap
 324 function is used to locate the first instance of a PCI capability
 325 register set for the device
 326 .Fa dev .
 327 The capability to locate is specified by ID via
 328 .Fa capability .
 329 Constant macros of the form
 330 .Dv PCIY_xxx
 331 for standard capability IDs are defined in
 332 .In dev/pci/pcireg.h .
 333 If the capability is found, then
 334 .Fa *capreg
 335 is set to the offset in configuration space of the capability register set,
 336 and
 337 .Fn pci_find_cap
 338 returns zero.
 339 If the capability is not found or the device does not support capabilities,
 340 .Fn pci_find_cap
 341 returns an error.
 342 The
 343 .Fn pci_find_next_cap
 344 function is used to locate the next instance of a PCI capability
 345 register set for the device
 346 .Fa dev .
 347 The
 348 .Fa start
 349 should be the
 350 .Fa *capreg
 351 returned by a prior
 352 .Fn pci_find_cap
 353 or
 354 .Fn pci_find_next_cap .
 355 When no more instances are located
 356 .Fn pci_find_next_cap
 357 returns an error.
 358 .Pp
 359 The
 360 .Fn pci_find_extcap
 361 function is used to locate the first instance of a PCI-express
 362 extended capability register set for the device
 363 .Fa dev .
 364 The extended capability to locate is specified by ID via
 365 .Fa capability .
 366 Constant macros of the form
 367 .Dv PCIZ_xxx
 368 for standard extended capability IDs are defined in
 369 .In dev/pci/pcireg.h .
 370 If the extended capability is found, then
 371 .Fa *capreg
 372 is set to the offset in configuration space of the extended capability
 373 register set, and
 374 .Fn pci_find_extcap
 375 returns zero.
 376 If the extended capability is not found or the device is not a
 377 PCI-express device,
 378 .Fn pci_find_extcap
 379 returns an error.
 380 The
 381 .Fn pci_find_next_extcap
 382 function is used to locate the next instance of a PCI-express
 383 extended capability register set for the device
 384 .Fa dev .
 385 The
 386 .Fa start
 387 should be the
 388 .Fa *capreg
 389 returned by a prior
 390 .Fn pci_find_extcap
 391 or
 392 .Fn pci_find_next_extcap .
 393 When no more instances are located
 394 .Fn pci_find_next_extcap
 395 returns an error.
 396 .Pp
 397 The
 398 .Fn pci_find_htcap
 399 function is used to locate the first instance of a HyperTransport capability
 400 register set for the device
 401 .Fa dev .
 402 The capability to locate is specified by type via
 403 .Fa capability .
 404 Constant macros of the form
 405 .Dv PCIM_HTCAP_xxx
 406 for standard HyperTransport capability types are defined in
 407 .In dev/pci/pcireg.h .
 408 If the capability is found, then
 409 .Fa *capreg
 410 is set to the offset in configuration space of the capability register set,
 411 and
 412 .Fn pci_find_htcap
 413 returns zero.
 414 If the capability is not found or the device is not a HyperTransport device,
 415 .Fn pci_find_htcap
 416 returns an error.
 417 The
 418 .Fn pci_find_next_htcap
 419 function is used to locate the next instance of a HyperTransport capability
 420 register set for the device
 421 .Fa dev .
 422 The
 423 .Fa start
 424 should be the
 425 .Fa *capreg
 426 returned by a prior
 427 .Fn pci_find_htcap
 428 or
 429 .Fn pci_find_next_htcap .
 430 When no more instances are located
 431 .Fn pci_find_next_htcap
 432 returns an error.
 433 .Pp
 434 The
 435 .Fn pci_find_pcie_root_port
 436 function walks up the PCI device hierarchy to locate the PCI-express root
 437 port upstream of
 438 .Fa dev .
 439 If a root port is not found,
 440 .Fn pci_find_pcie_root_port
 441 returns
 442 .Dv NULL .
 443 .Pp
 444 The
 445 .Fn pci_get_id
 446 function is used to read an identifier from a device.
 447 The
 448 .Fa type
 449 flag is used to specify which identifier to read.
 450 The following flags are supported:
 451 .Bl -hang -width ".Dv PCI_ID_RID"
 452 .It Dv PCI_ID_RID
 453 Read the routing identifier for the device.
 454 .It Dv PCI_ID_MSI
 455 Read the MSI routing ID.
 456 This is needed by some interrupt controllers to route MSI and MSI-X interrupts.
 457 .El
 458 .Pp
 459 The
 460 .Fn pci_get_vpd_ident
 461 function is used to fetch a device's Vital Product Data
 462 .Pq VPD
 463 identifier string.
 464 If the device
 465 .Fa dev
 466 supports VPD and provides an identifier string,
 467 then
 468 .Fa *identptr
 469 is set to point at a read-only, null-terminated copy of the identifier
 470 string,
 471 and
 472 .Fn pci_get_vpd_ident
 473 returns zero.
 474 If the device does not support VPD or does not provide an identifier
 475 string,
 476 then
 477 .Fn pci_get_vpd_ident
 478 returns an error.
 479 .Pp
 480 The
 481 .Fn pci_get_vpd_readonly
 482 function is used to fetch the value of a single VPD read-only keyword
 483 for the device
 484 .Fa dev .
 485 The keyword to fetch is identified by the two character string
 486 .Fa kw .
 487 If the device supports VPD and provides a read-only value for the
 488 requested keyword,
 489 then
 490 .Fa *vptr
 491 is set to point at a read-only, null-terminated copy of the value,
 492 and
 493 .Fn pci_get_vpd_readonly
 494 returns zero.
 495 If the device does not support VPD or does not provide the requested
 496 keyword,
 497 then
 498 .Fn pci_get_vpd_readonly
 499 returns an error.
 500 .Pp
 501 The
 502 .Fn pcie_get_max_completion_timeout
 503 function returns the maximum completion timeout configured for the device
 504 .Fa dev
 505 in microseconds.
 506 If the
 507 .Fa dev
 508 device is not a PCI-express device,
 509 .Fn pcie_get_max_completion_timeout
 510 returns zero.
 511 When completion timeouts are disabled for
 512 .Fa dev ,
 513 this function returns the maxmimum timeout that would be used if timeouts
 514 were enabled.
 515 .Pp
 516 The
 517 .Fn pcie_wait_for_pending_transactions
 518 function waits for any pending transactions initiated by the
 519 .Fa dev
 520 device to complete.
 521 The function checks for pending transactions by polling the transactions
 522 pending flag in the PCI-express device status register.
 523 It returns
 524 .Dv true
 525 once the transaction pending flag is clear.
 526 If transactions are still pending after
 527 .Fa max_delay
 528 milliseconds,
 529 .Fn pcie_wait_for_pending_transactions
 530 returns
 531 .Dv false .
 532 If
 533 .Fa max_delay
 534 is set to zero,
 535 .Fn pcie_wait_for_pending_transactions
 536 performs a single check;
 537 otherwise,
 538 this function may sleep while polling the transactions pending flag.
 539 .Nm pcie_wait_for_pending_transactions
 540 returns
 541 .Dv true
 542 if
 543 .Fa dev
 544 is not a PCI-express device.
 545 .Ss Device Configuration
 546 The
 547 .Fn pci_enable_busmaster
 548 function enables PCI bus mastering for the device
 549 .Fa dev ,
 550 by setting the
 551 .Dv PCIM_CMD_BUSMASTEREN
 552 bit in the
 553 .Dv PCIR_COMMAND
 554 register.
 555 The
 556 .Fn pci_disable_busmaster
 557 function clears this bit.
 558 .Pp
 559 The
 560 .Fn pci_enable_io
 561 function enables memory or I/O port address decoding for the device
 562 .Fa dev ,
 563 by setting the
 564 .Dv PCIM_CMD_MEMEN
 565 or
 566 .Dv PCIM_CMD_PORTEN
 567 bit in the
 568 .Dv PCIR_COMMAND
 569 register appropriately.
 570 The
 571 .Fn pci_disable_io
 572 function clears the appropriate bit.
 573 The
 574 .Fa space
 575 argument specifies which resource is affected; this can be either
 576 .Dv SYS_RES_MEMORY
 577 or
 578 .Dv SYS_RES_IOPORT
 579 as appropriate.
 580 Device drivers should generally not use these routines directly.
 581 The PCI bus will enable decoding automatically when a
 582 .Dv SYS_RES_MEMORY
 583 or
 584 .Dv SYS_RES_IOPORT
 585 resource is activated via
 586 .Xr bus_alloc_resource 9
 587 or
 588 .Xr bus_activate_resource 9 .
 589 .Pp
 590 The
 591 .Fn pci_get_max_payload
 592 function returns the current maximum TLP payload size in bytes for a
 593 PCI-express device.
 594 If the
 595 .Fa dev
 596 device is not a PCI-express device,
 597 .Fn pci_get_max_payload
 598 returns zero.
 599 .Pp
 600 The
 601 .Fn pci_get_max_read_req
 602 function returns the current maximum read request size in bytes for a
 603 PCI-express device.
 604 If the
 605 .Fa dev
 606 device is not a PCI-express device,
 607 .Fn pci_get_max_read_req
 608 returns zero.
 609 .Pp
 610 The
 611 .Fn pci_set_max_read_req
 612 sets the PCI-express maximum read request size for
 613 .Fa dev .
 614 The requested
 615 .Fa size
 616 may be adjusted,
 617 and
 618 .Fn pci_set_max_read_req
 619 returns the actual size set in bytes.
 620 If the
 621 .Fa dev
 622 device is not a PCI-express device,
 623 .Fn pci_set_max_read_req
 624 returns zero.
 625 .Pp
 626 The
 627 .Fn pci_get_powerstate
 628 function returns the current power state of the device
 629 .Fa dev .
 630 If the device does not support power management capabilities, then the default
 631 state of
 632 .Dv PCI_POWERSTATE_D0
 633 is returned.
 634 The following power states are defined by PCI:
 635 .Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN"
 636 .It Dv PCI_POWERSTATE_D0
 637 State in which device is on and running.
 638 It is receiving full power from the system and delivering
 639 full functionality to the user.
 640 .It Dv PCI_POWERSTATE_D1
 641 Class-specific low-power state in which device context may or
 642 may not be lost.
 643 Buses in this state cannot do anything to the bus, to
 644 force devices to lose context.
 645 .It Dv PCI_POWERSTATE_D2
 646 Class-specific low-power state in which device context may or
 647 may not be lost.
 648 Attains greater power savings than
 649 .Dv PCI_POWERSTATE_D1 .
 650 Buses in this state can cause devices to lose some context.
 651 Devices
 652 .Em must
 653 be prepared for the bus to be in this state or higher.
 654 .It Dv PCI_POWERSTATE_D3
 655 State in which the device is off and not running.
 656 Device context is lost, and power from the device can
 657 be removed.
 658 .It Dv PCI_POWERSTATE_UNKNOWN
 659 State of the device is unknown.
 660 .El
 661 .Pp
 662 The
 663 .Fn pci_set_powerstate
 664 function is used to transition the device
 665 .Fa dev
 666 to the PCI power state
 667 .Fa state .
 668 If the device does not support power management capabilities or
 669 it does not support the specific power state
 670 .Fa state ,
 671 then the function will fail with
 672 .Er EOPNOTSUPP .
 673 .Pp
 674 The
 675 .Fn pci_iov_attach
 676 function is used to advertise that the given device
 677 .Pq and associated device driver
 678 supports PCI Single-Root I/O Virtualization
 679 .Pq SR-IOV .
 680 A driver that supports SR-IOV must implement the
 681 .Xr PCI_IOV_INIT 9 ,
 682 .Xr PCI_IOV_ADD_VF 9
 683 and
 684 .Xr PCI_IOV_UNINIT 9
 685 methods.
 686 This function should be called during the
 687 .Xr DEVICE_ATTACH 9
 688 method.
 689 If this function returns an error, it is recommended that the device driver
 690 still successfully attaches, but runs with SR-IOV disabled.
 691 The
 692 .Fa pf_schema
 693 and
 694 .Fa vf_schema
 695 parameters are used to define what device-specific configuration parameters the
 696 device driver accepts when SR-IOV is enabled for the Physical Function
 697 .Pq PF
 698 and for individual Virtual Functions
 699 .Pq VFs
 700 respectively.
 701 See
 702 .Xr pci_iov_schema 9
 703 for details on how to construct the schema.
 704 If either the
 705 .Pa pf_schema
 706 or
 707 .Pa vf_schema
 708 is invalid or specifies parameter names that conflict with parameter names that
 709 are already in use,
 710 .Fn pci_iov_attach
 711 will return an error and SR-IOV will not be available on the PF device.
 712 If a driver does not accept configuration parameters for either the PF device
 713 or the VF devices, the driver must pass an empty schema for that device.
 714 The SR-IOV infrastructure takes ownership of the
 715 .Fa pf_schema
 716 and
 717 .Fa vf_schema
 718 and is responsible for freeing them.
 719 The driver must never free the schemas itself.
 720 .Pp
 721 The
 722 .Fn pci_iov_attach_name
 723 function is a variant of
 724 .Fn pci_iov_attach
 725 that allows the name of the associated character device in
 726 .Pa /dev/iov
 727 to be specified by
 728 .Fa fmt .
 729 The
 730 .Fn pci_iov_attach
 731 function uses the name of
 732 .Fa dev
 733 as the device name.
 734 .Pp
 735 The
 736 .Fn pci_iov_detach
 737 function is used to advise the SR-IOV infrastructure that the driver for the
 738 given device is attempting to detach and that all SR-IOV resources for the
 739 device must be released.
 740 This function must be called during the
 741 .Xr DEVICE_DETACH 9
 742 method if
 743 .Fn pci_iov_attach
 744 was successfully called on the device and
 745 .Fn pci_iov_detach
 746 has not subsequently been called on the device and returned no error.
 747 If this function returns an error, the
 748 .Xr DEVICE_DETACH 9
 749 method must fail and return an error, as detaching the PF driver while VF
 750 devices are active would cause system instability.
 751 This function is safe to call and will always succeed if
 752 .Fn pci_iov_attach
 753 previously failed with an error on the given device, or if
 754 .Fn pci_iov_attach
 755 was never called on the device.
 756 .Pp
 757 The
 758 .Fn pci_save_state
 759 and
 760 .Fn pci_restore_state
 761 functions can be used by a device driver to save and restore standard PCI
 762 config registers.
 763 The
 764 .Fn pci_save_state
 765 function must be invoked while the device has valid state before
 766 .Fn pci_restore_state
 767 can be used.
 768 If the device is not in the fully-powered state
 769 .Pq Dv PCI_POWERSTATE_D0
 770 when
 771 .Fn pci_restore_state
 772 is invoked,
 773 then the device will be transitioned to
 774 .Dv PCI_POWERSTATE_D0
 775 before any config registers are restored.
 776 .Pp
 777 The
 778 .Fn pcie_flr
 779 function requests a Function Level Reset
 780 .Pq FLR
 781 of
 782 .Fa dev .
 783 If
 784 .Fa dev
 785 is not a PCI-express device or does not support Function Level Resets via
 786 the PCI-express device control register,
 787 .Dv false
 788 is returned.
 789 Pending transactions are drained by disabling busmastering and calling
 790 .Fn pcie_wait_for_pending_transactions
 791 before resetting the device.
 792 The
 793 .Fa max_delay
 794 argument specifies the maximum timeout to wait for pending transactions as
 795 described for
 796 .Fn pcie_wait_for_pending_transactions .
 797 If
 798 .Fn pcie_wait_for_pending_transactions
 799 fails with a timeout and
 800 .Fa force
 801 is
 802 .Dv false ,
 803 busmastering is re-enabled and
 804 .Dv false
 805 is returned.
 806 If
 807 .Fn pcie_wait_for_pending_transactions
 808 fails with a timeout and
 809 .Fa force
 810 is
 811 .Dv true ,
 812 the device is reset despite the timeout.
 813 After the reset has been requested,
 814 .Nm pcie_flr
 815 sleeps for at least 100 milliseconds before returning
 816 .Dv true .
 817 Note that
 818 .Nm pcie_flr
 819 does not save and restore any state around the reset.
 820 The caller should save and restore state as needed.
 821 .Ss Message Signaled Interrupts
 822 Message Signaled Interrupts
 823 .Pq MSI
 824 and
 825 Enhanced Message Signaled Interrupts
 826 .Pq MSI-X
 827 are PCI capabilities that provide an alternate method for PCI
 828 devices to signal interrupts.
 829 The legacy INTx interrupt is available to PCI devices as a
 830 .Dv SYS_RES_IRQ
 831 resource with a resource ID of zero.
 832 MSI and MSI-X interrupts are available to PCI devices as one or more
 833 .Dv SYS_RES_IRQ
 834 resources with resource IDs greater than zero.
 835 A driver must ask the PCI bus to allocate MSI or MSI-X interrupts
 836 using
 837 .Fn pci_alloc_msi
 838 or
 839 .Fn pci_alloc_msix
 840 before it can use MSI or MSI-X
 841 .Dv SYS_RES_IRQ
 842 resources.
 843 A driver is not allowed to use the legacy INTx
 844 .Dv SYS_RES_IRQ
 845 resource if MSI or MSI-X interrupts have been allocated,
 846 and attempts to allocate MSI or MSI-X interrupts will fail if the
 847 driver is currently using the legacy INTx
 848 .Dv SYS_RES_IRQ
 849 resource.
 850 A driver is only allowed to use either MSI or MSI-X,
 851 but not both.
 852 .Pp
 853 The
 854 .Fn pci_msi_count
 855 function returns the maximum number of MSI messages supported by the
 856 device
 857 .Fa dev .
 858 If the device does not support MSI,
 859 then
 860 .Fn pci_msi_count
 861 returns zero.
 862 .Pp
 863 The
 864 .Fn pci_alloc_msi
 865 function attempts to allocate
 866 .Fa *count
 867 MSI messages for the device
 868 .Fa dev .
 869 The
 870 .Fn pci_alloc_msi
 871 function may allocate fewer messages than requested for various
 872 reasons including requests for more messages than the device
 873 .Fa dev
 874 supports,
 875 or if the system has a shortage of available MSI messages.
 876 On success,
 877 .Fa *count
 878 is set to the number of messages allocated and
 879 .Fn pci_alloc_msi
 880 returns zero.
 881 The
 882 .Dv SYS_RES_IRQ
 883 resources for the allocated messages will be available at consecutive
 884 resource IDs beginning with one.
 885 If
 886 .Fn pci_alloc_msi
 887 is not able to allocate any messages,
 888 it returns an error.
 889 Note that MSI only supports message counts that are powers of two;
 890 requests to allocate a non-power of two count of messages will fail.
 891 .Pp
 892 The
 893 .Fn pci_release_msi
 894 function is used to release any allocated MSI or MSI-X messages back
 895 to the system.
 896 If any MSI or MSI-X
 897 .Dv SYS_RES_IRQ
 898 resources are allocated by the driver or have a configured interrupt
 899 handler,
 900 this function will fail with
 901 .Er EBUSY .
 902 The
 903 .Fn pci_release_msi
 904 function returns zero on success and an error on failure.
 905 .Pp
 906 The
 907 .Fn pci_msix_count
 908 function returns the maximum number of MSI-X messages supported by the
 909 device
 910 .Fa dev .
 911 If the device does not support MSI-X,
 912 then
 913 .Fn pci_msix_count
 914 returns zero.
 915 .Pp
 916 The
 917 .Fn pci_msix_pba_bar
 918 function returns the offset in configuration space of the Base Address Register
 919 .Pq BAR
 920 containing the MSI-X Pending Bit Array (PBA) for device
 921 .Fa dev .
 922 The returned value can be used as the resource ID with
 923 .Xr bus_alloc_resource 9
 924 and
 925 .Xr bus_release_resource 9
 926 to allocate the BAR.
 927 If the device does not support MSI-X,
 928 then
 929 .Fn pci_msix_pba_bar
 930 returns -1.
 931 .Pp
 932 The
 933 .Fn pci_msix_table_bar
 934 function returns the offset in configuration space of the BAR
 935 containing the MSI-X vector table for device
 936 .Fa dev .
 937 The returned value can be used as the resource ID with
 938 .Xr bus_alloc_resource 9
 939 and
 940 .Xr bus_release_resource 9
 941 to allocate the BAR.
 942 If the device does not support MSI-X,
 943 then
 944 .Fn pci_msix_table_bar
 945 returns -1.
 946 .Pp
 947 The
 948 .Fn pci_alloc_msix
 949 function attempts to allocate
 950 .Fa *count
 951 MSI-X messages for the device
 952 .Fa dev .
 953 The
 954 .Fn pci_alloc_msix
 955 function may allocate fewer messages than requested for various
 956 reasons including requests for more messages than the device
 957 .Fa dev
 958 supports,
 959 or if the system has a shortage of available MSI-X messages.
 960 On success,
 961 .Fa *count
 962 is set to the number of messages allocated and
 963 .Fn pci_alloc_msix
 964 returns zero.
 965 For MSI-X messages,
 966 the resource ID for each
 967 .Dv SYS_RES_IRQ
 968 resource identifies the index in the MSI-X table of the
 969 corresponding message.
 970 A resource ID of one maps to the first index of the MSI-X table;
 971 a resource ID two identifies the second index in the table, etc.
 972 The
 973 .Fn pci_alloc_msix
 974 function assigns the
 975 .Fa *count
 976 messages allocated to the first
 977 .Fa *count
 978 table indices.
 979 If
 980 .Fn pci_alloc_msix
 981 is not able to allocate any messages,
 982 it returns an error.
 983 Unlike MSI,
 984 MSI-X does not require message counts that are powers of two.
 985 .Pp
 986 The BARs containing the MSI-X vector table and PBA must be
 987 allocated via
 988 .Xr bus_alloc_resource 9
 989 before calling
 990 .Fn pci_alloc_msix
 991 and must not be released until after calling
 992 .Fn pci_release_msi .
 993 Note that the vector table and PBA may be stored in the same BAR or in
 994 different BARs.
 995 .Pp
 996 The
 997 .Fn pci_pending_msix
 998 function examines the
 999 .Fa dev
1000 device's PBA
1001 to determine the pending status of the MSI-X message at table index
1002 .Fa index .
1003 If the indicated message is pending,
1004 this function returns a non-zero value;
1005 otherwise,
1006 it returns zero.
1007 Passing an invalid
1008 .Fa index
1009 to this function will result in undefined behavior.
1010 .Pp
1011 As mentioned in the description of
1012 .Fn pci_alloc_msix ,
1013 MSI-X messages are initially assigned to the first N table entries.
1014 A driver may use a different distribution of available messages to
1015 table entries via the
1016 .Fn pci_remap_msix
1017 function.
1018 Note that this function must be called after a successful call to
1019 .Fn pci_alloc_msix
1020 but before any of the
1021 .Dv SYS_RES_IRQ
1022 resources are allocated.
1023 The
1024 .Fn pci_remap_msix
1025 function returns zero on success,
1026 or an error on failure.
1027 .Pp
1028 The
1029 .Fa vectors
1030 array should contain
1031 .Fa count
1032 message vectors.
1033 The array maps directly to the MSI-X table in that the first entry in
1034 the array specifies the message used for the first entry in the MSI-X
1035 table,
1036 the second entry in the array corresponds to the second entry in the
1037 MSI-X table,
1038 etc.
1039 The vector value in each array index can either be zero to indicate
1040 that no message should be assigned to the corresponding MSI-X table entry,
1041 or it can be a number from one to N
1042 .Po
1043 where N is the count returned from the previous call to
1044 .Fn pci_alloc_msix
1045 .Pc
1046 to indicate which of the allocated messages should be assigned to the
1047 corresponding MSI-X table entry.
1048 .Pp
1049 If
1050 .Fn pci_remap_msix
1051 succeeds,
1052 each MSI-X table entry with a non-zero vector will have an associated
1053 .Dv SYS_RES_IRQ
1054 resource whose resource ID corresponds to the table index as described
1055 above for
1056 .Fn pci_alloc_msix .
1057 MSI-X table entries that with a vector of zero will not have an
1058 associated
1059 .Dv SYS_RES_IRQ
1060 resource.
1061 Additionally,
1062 if any of the original messages allocated by
1063 .Fn pci_alloc_msix
1064 are not used in the new distribution of messages in the MSI-X table,
1065 they will be released automatically.
1066 Note that if a driver wishes to use fewer messages than were allocated by
1067 .Fn pci_alloc_msix ,
1068 the driver must use a single, contiguous range of messages beginning
1069 with one in the new distribution.
1070 The
1071 .Fn pci_remap_msix
1072 function will fail if this condition is not met.
1073 .Ss Device Events
1074 The
1075 .Va pci_add_device
1076 event handler is invoked every time a new PCI device is added to the system.
1077 This includes the creation of Virtual Functions via SR-IOV.
1078 .Pp
1079 The
1080 .Va pci_delete_device
1081 event handler is invoked every time a PCI device is removed from the system.
1082 .Pp
1083 Both event handlers pass the
1084 .Vt device_t
1085 object of the relevant PCI device as
1086 .Fa dev
1087 to each callback function.
1088 Both event handlers are invoked while
1089 .Fa dev
1090 is unattached but with valid instance variables.
1091 .Sh SEE ALSO
1092 .Xr pci 4 ,
1093 .Xr pciconf 8 ,
1094 .Xr bus_alloc_resource 9 ,
1095 .Xr bus_dma 9 ,
1096 .Xr bus_release_resource 9 ,
1097 .Xr bus_setup_intr 9 ,
1098 .Xr bus_teardown_intr 9 ,
1099 .Xr devclass 9 ,
1100 .Xr device 9 ,
1101 .Xr driver 9 ,
1102 .Xr eventhandler 9 ,
1103 .Xr rman 9
1104 .Rs
1105 .%B FreeBSD Developers' Handbook
1106 .%T NewBus
1107 .%U https://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
1108 .Re
1109 .Rs
1110 .%A Shanley
1111 .%A Anderson
1112 .%B PCI System Architecture
1113 .%N 2nd Edition
1114 .%I Addison-Wesley
1115 .%O ISBN 0-201-30974-2
1116 .Re
1117 .Sh AUTHORS
1118 .An -nosplit
1119 This manual page was written by
1120 .An Bruce M Simpson Aq Mt bms@FreeBSD.org
1121 and
1122 .An John Baldwin Aq Mt jhb@FreeBSD.org .
1123 .Sh BUGS
1124 The kernel PCI code has a number of references to
1125 .Dq "slot numbers" .
1126 These do not refer to the geographic location of PCI devices,
1127 but to the device number assigned by the combination of the PCI IDSEL
1128 mechanism and the platform firmware.
1129 This should be taken note of when working with the kernel PCI code.
1130 .Pp
1131 The PCI bus driver should allocate the MSI-X vector table and PBA internally
1132 as necessary rather than requiring the caller to do so.