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 December 23, 2015
  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_pcie_root_port ,
  46 .Nm pci_get_max_read_req ,
  47 .Nm pci_get_powerstate ,
  48 .Nm pci_get_vpd_ident ,
  49 .Nm pci_get_vpd_readonly ,
  50 .Nm pci_iov_attach ,
  51 .Nm pci_iov_detach ,
  52 .Nm pci_msi_count ,
  53 .Nm pci_msix_count ,
  54 .Nm pci_msix_pba_bar ,
  55 .Nm pci_msix_table_bar ,
  56 .Nm pci_pending_msix ,
  57 .Nm pci_read_config ,
  58 .Nm pci_release_msi ,
  59 .Nm pci_remap_msix ,
  60 .Nm pci_restore_state ,
  61 .Nm pci_save_state ,
  62 .Nm pci_set_max_read_req ,
  63 .Nm pci_set_powerstate ,
  64 .Nm pci_write_config ,
  65 .Nm pcie_adjust_config ,
  66 .Nm pcie_read_config ,
  67 .Nm pcie_write_config
  68 .Nd PCI bus interface
  69 .Sh SYNOPSIS
  70 .In sys/bus.h
  71 .In dev/pci/pcireg.h
  72 .In dev/pci/pcivar.h
  73 .Ft int
  74 .Fn pci_alloc_msi "device_t dev" "int *count"
  75 .Ft int
  76 .Fn pci_alloc_msix "device_t dev" "int *count"
  77 .Ft int
  78 .Fn pci_disable_busmaster "device_t dev"
  79 .Ft int
  80 .Fn pci_disable_io "device_t dev" "int space"
  81 .Ft int
  82 .Fn pci_enable_busmaster "device_t dev"
  83 .Ft int
  84 .Fn pci_enable_io "device_t dev" "int space"
  85 .Ft device_t
  86 .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
  87 .Ft int
  88 .Fn pci_find_cap "device_t dev" "int capability" "int *capreg"
  89 .Ft device_t
  90 .Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func"
  91 .Ft device_t
  92 .Fn pci_find_device "uint16_t vendor" "uint16_t device"
  93 .Ft int
  94 .Fn pci_find_extcap "device_t dev" "int capability" "int *capreg"
  95 .Ft int
  96 .Fn pci_find_htcap "device_t dev" "int capability" "int *capreg"
  97 .Ft device_t
  98 .Fn pci_find_pcie_root_port "device_t dev"
  99 .Ft int
 100 .Fn pci_get_max_read_req "device_t dev"
 101 .Ft int
 102 .Fn pci_get_powerstate "device_t dev"
 103 .Ft int
 104 .Fn pci_get_vpd_ident "device_t dev" "const char **identptr"
 105 .Ft int
 106 .Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr"
 107 .Ft int
 108 .Fn pci_msi_count "device_t dev"
 109 .Ft int
 110 .Fn pci_msix_count "device_t dev"
 111 .Ft int
 112 .Fn pci_msix_pba_bar "device_t dev"
 113 .Ft int
 114 .Fn pci_msix_table_bar "device_t dev"
 115 .Ft int
 116 .Fn pci_pending_msix "device_t dev" "u_int index"
 117 .Ft uint32_t
 118 .Fn pci_read_config "device_t dev" "int reg" "int width"
 119 .Ft int
 120 .Fn pci_release_msi "device_t dev"
 121 .Ft int
 122 .Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors"
 123 .Ft void
 124 .Fn pci_restore_state "device_t dev"
 125 .Ft void
 126 .Fn pci_save_state "device_t dev"
 127 .Ft int
 128 .Fn pci_set_max_read_req "device_t dev" "int size"
 129 .Ft int
 130 .Fn pci_set_powerstate "device_t dev" "int state"
 131 .Ft void
 132 .Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width"
 133 .Ft uint32_t
 134 .Fo pcie_adjust_config
 135 .Fa "device_t dev"
 136 .Fa "int reg"
 137 .Fa "uint32_t mask"
 138 .Fa "uint32_t val"
 139 .Fa "int width"
 140 .Fc
 141 .Ft uint32_t
 142 .Fn pcie_read_config "device_t dev" "int reg" "int width"
 143 .Ft void
 144 .Fn pcie_write_config "device_t dev" "int reg" "uint32_t val" "int width"
 145 .In dev/pci/pci_iov.h
 146 .Ft int
 147 .Fn pci_iov_attach "device_t dev" "nvlist_t *pf_schema" "nvlist_t *vf_schema"
 148 .Ft int
 149 .Fn pci_iov_detach "device_t dev"
 150 .Sh DESCRIPTION
 151 The
 152 .Nm
 153 set of functions are used for managing PCI devices.
 154 The functions are split into several groups:
 155 raw configuration access,
 156 locating devices,
 157 device information,
 158 device configuration,
 159 and
 160 message signaled interrupts.
 161 .Ss Raw Configuration Access
 162 The
 163 .Fn pci_read_config
 164 function is used to read data from the PCI configuration
 165 space of the device
 166 .Fa dev ,
 167 at offset
 168 .Fa reg ,
 169 with
 170 .Fa width
 171 specifying the size of the access.
 172 .Pp
 173 The
 174 .Fn pci_write_config
 175 function is used to write the value
 176 .Fa val
 177 to the PCI configuration
 178 space of the device
 179 .Fa dev ,
 180 at offset
 181 .Fa reg ,
 182 with
 183 .Fa width
 184 specifying the size of the access.
 185 .Pp
 186 The
 187 .Fn pcie_adjust_config
 188 function is used to modify the value of a register in the PCI-express
 189 capability register set of device
 190 .Fa dev .
 191 The offset
 192 .Fa reg
 193 specifies a relative offset in the register set with
 194 .Fa width
 195 specifying the size of the access.
 196 The new value of the register is computed by modifying bits set in
 197 .Fa mask
 198 to the value in
 199 .Fa val .
 200 Any bits not specified in
 201 .Fa mask
 202 are preserved.
 203 The previous value of the register is returned.
 204 .Pp
 205 The
 206 .Fn pcie_read_config
 207 function is used to read the value of a register in the PCI-express
 208 capability register set of device
 209 .Fa dev .
 210 The offset
 211 .Fa reg
 212 specifies a relative offset in the register set with
 213 .Fa width
 214 specifying the size of the access.
 215 .Pp
 216 The
 217 .Fn pcie_write_config
 218 function is used to write the value
 219 .Fa val
 220 to a register in the PCI-express capability register set of device
 221 .Fa dev .
 222 The offset
 223 .Fa reg
 224 specifies a relative offset in the register set with
 225 .Fa width
 226 specifying the size of the access.
 227 .Pp
 228 .Em NOTE :
 229 Device drivers should only use these functions for functionality that
 230 is not available via another
 231 .Fn pci
 232 function.
 233 .Ss Locating Devices
 234 The
 235 .Fn pci_find_bsf
 236 function looks up the
 237 .Vt device_t
 238 of a PCI device, given its
 239 .Fa bus ,
 240 .Fa slot ,
 241 and
 242 .Fa func .
 243 The
 244 .Fa slot
 245 number actually refers to the number of the device on the bus,
 246 which does not necessarily indicate its geographic location
 247 in terms of a physical slot.
 248 Note that in case the system has multiple PCI domains,
 249 the
 250 .Fn pci_find_bsf
 251 function only searches the first one.
 252 Actually, it is equivalent to:
 253 .Bd -literal -offset indent
 254 pci_find_dbsf(0, bus, slot, func);
 255 .Ed
 256 .Pp
 257 The
 258 .Fn pci_find_dbsf
 259 function looks up the
 260 .Vt device_t
 261 of a PCI device, given its
 262 .Fa domain ,
 263 .Fa bus ,
 264 .Fa slot ,
 265 and
 266 .Fa func .
 267 The
 268 .Fa slot
 269 number actually refers to the number of the device on the bus,
 270 which does not necessarily indicate its geographic location
 271 in terms of a physical slot.
 272 .Pp
 273 The
 274 .Fn pci_find_device
 275 function looks up the
 276 .Vt device_t
 277 of a PCI device, given its
 278 .Fa vendor
 279 and
 280 .Fa device
 281 IDs.
 282 Note that there can be multiple matches for this search; this function
 283 only returns the first matching device.
 284 .Ss Device Information
 285 The
 286 .Fn pci_find_cap
 287 function is used to locate the first instance of a PCI capability
 288 register set for the device
 289 .Fa dev .
 290 The capability to locate is specified by ID via
 291 .Fa capability .
 292 Constant macros of the form
 293 .Dv PCIY_xxx
 294 for standard capability IDs are defined in
 295 .In dev/pci/pcireg.h .
 296 If the capability is found, then
 297 .Fa *capreg
 298 is set to the offset in configuration space of the capability register set,
 299 and
 300 .Fn pci_find_cap
 301 returns zero.
 302 If the capability is not found or the device does not support capabilities,
 303 .Fn pci_find_cap
 304 returns an error.
 305 .Pp
 306 The
 307 .Fn pci_find_extcap
 308 function is used to locate the first instance of a PCI-express
 309 extended capability register set for the device
 310 .Fa dev .
 311 The extended capability to locate is specified by ID via
 312 .Fa capability .
 313 Constant macros of the form
 314 .Dv PCIZ_xxx
 315 for standard extended capability IDs are defined in
 316 .In dev/pci/pcireg.h .
 317 If the extended capability is found, then
 318 .Fa *capreg
 319 is set to the offset in configuration space of the extended capability
 320 register set, and
 321 .Fn pci_find_extcap
 322 returns zero.
 323 If the extended capability is not found or the device is not a
 324 PCI-express device,
 325 .Fn pci_find_extcap
 326 returns an error.
 327 .Pp
 328 The
 329 .Fn pci_find_htcap
 330 function is used to locate the first instance of a HyperTransport capability
 331 register set for the device
 332 .Fa dev .
 333 The capability to locate is specified by type via
 334 .Fa capability .
 335 Constant macros of the form
 336 .Dv PCIM_HTCAP_xxx
 337 for standard HyperTransport capability types are defined in
 338 .In dev/pci/pcireg.h .
 339 If the capability is found, then
 340 .Fa *capreg
 341 is set to the offset in configuration space of the capability register set,
 342 and
 343 .Fn pci_find_htcap
 344 returns zero.
 345 If the capability is not found or the device is not a HyperTransport device,
 346 .Fn pci_find_htcap
 347 returns an error.
 348 .Pp
 349 The
 350 .Fn pci_find_pcie_root_port
 351 function walks up the PCI device hierarchy to locate the PCI-express root
 352 port upstream of
 353 .Fa dev .
 354 If a root port is not found,
 355 .Fn pci_find_pcie_root_port
 356 returns
 357 .Dv NULL .
 358 .Pp
 359 The
 360 .Fn pci_get_vpd_ident
 361 function is used to fetch a device's Vital Product Data
 362 .Pq VPD
 363 identifier string.
 364 If the device
 365 .Fa dev
 366 supports VPD and provides an identifier string,
 367 then
 368 .Fa *identptr
 369 is set to point at a read-only, null-terminated copy of the identifier
 370 string,
 371 and
 372 .Fn pci_get_vpd_ident
 373 returns zero.
 374 If the device does not support VPD or does not provide an identifier
 375 string,
 376 then
 377 .Fn pci_get_vpd_ident
 378 returns an error.
 379 .Pp
 380 The
 381 .Fn pci_get_vpd_readonly
 382 function is used to fetch the value of a single VPD read-only keyword
 383 for the device
 384 .Fa dev .
 385 The keyword to fetch is identified by the two character string
 386 .Fa kw .
 387 If the device supports VPD and provides a read-only value for the
 388 requested keyword,
 389 then
 390 .Fa *vptr
 391 is set to point at a read-only, null-terminated copy of the value,
 392 and
 393 .Fn pci_get_vpd_readonly
 394 returns zero.
 395 If the device does not support VPD or does not provide the requested
 396 keyword,
 397 then
 398 .Fn pci_get_vpd_readonly
 399 returns an error.
 400 .Ss Device Configuration
 401 The
 402 .Fn pci_enable_busmaster
 403 function enables PCI bus mastering for the device
 404 .Fa dev ,
 405 by setting the
 406 .Dv PCIM_CMD_BUSMASTEREN
 407 bit in the
 408 .Dv PCIR_COMMAND
 409 register.
 410 The
 411 .Fn pci_disable_busmaster
 412 function clears this bit.
 413 .Pp
 414 The
 415 .Fn pci_enable_io
 416 function enables memory or I/O port address decoding for the device
 417 .Fa dev ,
 418 by setting the
 419 .Dv PCIM_CMD_MEMEN
 420 or
 421 .Dv PCIM_CMD_PORTEN
 422 bit in the
 423 .Dv PCIR_COMMAND
 424 register appropriately.
 425 The
 426 .Fn pci_disable_io
 427 function clears the appropriate bit.
 428 The
 429 .Fa space
 430 argument specifies which resource is affected; this can be either
 431 .Dv SYS_RES_MEMORY
 432 or
 433 .Dv SYS_RES_IOPORT
 434 as appropriate.
 435 Device drivers should generally not use these routines directly.
 436 The PCI bus will enable decoding automatically when a
 437 .Dv SYS_RES_MEMORY
 438 or
 439 .Dv SYS_RES_IOPORT
 440 resource is activated via
 441 .Xr bus_alloc_resource 9
 442 or
 443 .Xr bus_activate_resource 9 .
 444 .Pp
 445 The
 446 .Fn pci_get_max_read_req
 447 function returns the current maximum read request size in bytes for a
 448 PCI-express device.
 449 If the
 450 .Fa dev
 451 device is not a PCI-express device,
 452 .Fn pci_get_max_read_req
 453 returns zero.
 454 .Pp
 455 The
 456 .Fn pci_set_max_read_req
 457 sets the PCI-express maximum read request size for
 458 .Fa dev .
 459 The requested
 460 .Fa size
 461 may be adjusted,
 462 and
 463 .Fn pci_set_max_read_req
 464 returns the actual size set in bytes.
 465 If the
 466 .Fa dev
 467 device is not a PCI-express device,
 468 .Fn pci_set_max_read_req
 469 returns zero.
 470 .Pp
 471 The
 472 .Fn pci_get_powerstate
 473 function returns the current power state of the device
 474 .Fa dev .
 475 If the device does not support power management capabilities, then the default
 476 state of
 477 .Dv PCI_POWERSTATE_D0
 478 is returned.
 479 The following power states are defined by PCI:
 480 .Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN"
 481 .It Dv PCI_POWERSTATE_D0
 482 State in which device is on and running.
 483 It is receiving full power from the system and delivering
 484 full functionality to the user.
 485 .It Dv PCI_POWERSTATE_D1
 486 Class-specific low-power state in which device context may or
 487 may not be lost.
 488 Busses in this state cannot do anything to the bus, to
 489 force devices to lose context.
 490 .It Dv PCI_POWERSTATE_D2
 491 Class-specific low-power state in which device context may or
 492 may not be lost.
 493 Attains greater power savings than
 494 .Dv PCI_POWERSTATE_D1 .
 495 Busses in this state can cause devices to lose some context.
 496 Devices
 497 .Em must
 498 be prepared for the bus to be in this state or higher.
 499 .It Dv PCI_POWERSTATE_D3
 500 State in which the device is off and not running.
 501 Device context is lost, and power from the device can
 502 be removed.
 503 .It Dv PCI_POWERSTATE_UNKNOWN
 504 State of the device is unknown.
 505 .El
 506 .Pp
 507 The
 508 .Fn pci_set_powerstate
 509 function is used to transition the device
 510 .Fa dev
 511 to the PCI power state
 512 .Fa state .
 513 If the device does not support power management capabilities or
 514 it does not support the specific power state
 515 .Fa state ,
 516 then the function will fail with
 517 .Er EOPNOTSUPP .
 518 .Pp
 519 The
 520 .Fn pci_iov_attach
 521 function is used to advertise that the given device
 522 .Pq and associated device driver
 523 supports PCI Single-Root I/O Virtualization
 524 .Pq SR-IOV .
 525 A driver that supports SR-IOV must implement the
 526 .Xr PCI_IOV_INIT 9 ,
 527 .Xr PCI_IOV_ADD_VF 9
 528 and
 529 .Xr PCI_IOV_UNINIT 9
 530 methods.
 531 This function should be called during the
 532 .Xr DEVICE_ATTACH 9
 533 method.
 534 If this function returns an error, it is recommended that the device driver
 535 still successfully attaches, but runs with SR-IOV disabled.
 536 The
 537 .Fa pf_schema
 538 and
 539 .Fa vf_schema
 540 parameters are used to define what device-specific configuration parameters the
 541 device driver accepts when SR-IOV is enabled for the Physical Function
 542 .Pq PF
 543 and for individual Virtual Functions
 544 .Pq VFs
 545 respectively.
 546 See
 547 .Xr pci_iov_schema 9
 548 for details on how to construct the schema.
 549 If either the
 550 .Pa pf_schema
 551 or
 552 .Pa vf_schema
 553 is invalid or specifies parameter names that conflict with parameter names that
 554 are already in use,
 555 .Fn pci_iov_attach
 556 will return an error and SR-IOV will not be available on the PF device.
 557 If a driver does not accept configuration parameters for either the PF device
 558 or the VF devices, the driver must pass an empty schema for that device.
 559 The SR-IOV infrastructure takes ownership of the
 560 .Fa pf_schema
 561 and
 562 .Fa vf_schema
 563 and is responsible for freeing them.
 564 The driver must never free the schemas itself.
 565 .Pp
 566 The
 567 .Fn pci_iov_detach
 568 function is used to advise the SR-IOV infrastructure that the driver for the
 569 given device is attempting to detach and that all SR-IOV resources for the
 570 device must be released.
 571 This function must be called during the
 572 .Xr DEVICE_DETACH 9
 573 method if
 574 .Fn pci_iov_attach
 575 was successfully called on the device and
 576 .Fn pci_iov_detach
 577 has not subsequently been called on the device and returned no error.
 578 If this function returns an error, the
 579 .Xr DEVICE_DETACH 9
 580 method must fail and return an error, as detaching the PF driver while VF
 581 devices are active would cause system instability.
 582 This function is safe to call and will always succeed if
 583 .Fn pci_iov_attach
 584 previously failed with an error on the given device, or if
 585 .Fn pci_iov_attach
 586 was never called on the device.
 587 .Pp
 588 The
 589 .Fn pci_save_state
 590 and
 591 .Fn pci_restore_state
 592 functions can be used by a device driver to save and restore standard PCI
 593 config registers.
 594 The
 595 .Fn pci_save_state
 596 function must be invoked while the device has valid state before
 597 .Fn pci_restore_state
 598 can be used.
 599 If the device is not in the fully-powered state
 600 .Pq Dv PCI_POWERSTATE_D0
 601 when
 602 .Fn pci_restore_state
 603 is invoked,
 604 then the device will be transitioned to
 605 .Dv PCI_POWERSTATE_D0
 606 before any config registers are restored.
 607 .Ss Message Signaled Interrupts
 608 Message Signaled Interrupts
 609 .Pq MSI
 610 and
 611 Enhanced Message Signaled Interrupts
 612 .Pq MSI-X
 613 are PCI capabilities that provide an alternate method for PCI
 614 devices to signal interrupts.
 615 The legacy INTx interrupt is available to PCI devices as a
 616 .Dv SYS_RES_IRQ
 617 resource with a resource ID of zero.
 618 MSI and MSI-X interrupts are available to PCI devices as one or more
 619 .Dv SYS_RES_IRQ
 620 resources with resource IDs greater than zero.
 621 A driver must ask the PCI bus to allocate MSI or MSI-X interrupts
 622 using
 623 .Fn pci_alloc_msi
 624 or
 625 .Fn pci_alloc_msix
 626 before it can use MSI or MSI-X
 627 .Dv SYS_RES_IRQ
 628 resources.
 629 A driver is not allowed to use the legacy INTx
 630 .Dv SYS_RES_IRQ
 631 resource if MSI or MSI-X interrupts have been allocated,
 632 and attempts to allocate MSI or MSI-X interrupts will fail if the
 633 driver is currently using the legacy INTx
 634 .Dv SYS_RES_IRQ
 635 resource.
 636 A driver is only allowed to use either MSI or MSI-X,
 637 but not both.
 638 .Pp
 639 The
 640 .Fn pci_msi_count
 641 function returns the maximum number of MSI messages supported by the
 642 device
 643 .Fa dev .
 644 If the device does not support MSI,
 645 then
 646 .Fn pci_msi_count
 647 returns zero.
 648 .Pp
 649 The
 650 .Fn pci_alloc_msi
 651 function attempts to allocate
 652 .Fa *count
 653 MSI messages for the device
 654 .Fa dev .
 655 The
 656 .Fn pci_alloc_msi
 657 function may allocate fewer messages than requested for various
 658 reasons including requests for more messages than the device
 659 .Fa dev
 660 supports,
 661 or if the system has a shortage of available MSI messages.
 662 On success,
 663 .Fa *count
 664 is set to the number of messages allocated and
 665 .Fn pci_alloc_msi
 666 returns zero.
 667 The
 668 .Dv SYS_RES_IRQ
 669 resources for the allocated messages will be available at consecutive
 670 resource IDs beginning with one.
 671 If
 672 .Fn pci_alloc_msi
 673 is not able to allocate any messages,
 674 it returns an error.
 675 Note that MSI only supports message counts that are powers of two;
 676 requests to allocate a non-power of two count of messages will fail.
 677 .Pp
 678 The
 679 .Fn pci_release_msi
 680 function is used to release any allocated MSI or MSI-X messages back
 681 to the system.
 682 If any MSI or MSI-X
 683 .Dv SYS_RES_IRQ
 684 resources are allocated by the driver or have a configured interrupt
 685 handler,
 686 this function will fail with
 687 .Er EBUSY .
 688 The
 689 .Fn pci_release_msi
 690 function returns zero on success and an error on failure.
 691 .Pp
 692 The
 693 .Fn pci_msix_count
 694 function returns the maximum number of MSI-X messages supported by the
 695 device
 696 .Fa dev .
 697 If the device does not support MSI-X,
 698 then
 699 .Fn pci_msix_count
 700 returns zero.
 701 .Pp
 702 The
 703 .Fn pci_msix_pba_bar
 704 function returns the offset in configuration space of the Base Address Register
 705 .Pq BAR
 706 containing the MSI-X Pending Bit Array (PBA) for device
 707 .Fa dev .
 708 The returned value can be used as the resource ID with
 709 .Xr bus_alloc_resource 9
 710 and
 711 .Xr bus_release_resource 9
 712 to allocate the BAR.
 713 If the device does not support MSI-X,
 714 then
 715 .Fn pci_msix_pba_bar
 716 returns -1.
 717 .Pp
 718 The
 719 .Fn pci_msix_table_bar
 720 function returns the offset in configuration space of the BAR
 721 containing the MSI-X vector table for device
 722 .Fa dev .
 723 The returned value can be used as the resource ID with
 724 .Xr bus_alloc_resource 9
 725 and
 726 .Xr bus_release_resource 9
 727 to allocate the BAR.
 728 If the device does not support MSI-X,
 729 then
 730 .Fn pci_msix_table_bar
 731 returns -1.
 732 .Pp
 733 The
 734 .Fn pci_alloc_msix
 735 function attempts to allocate
 736 .Fa *count
 737 MSI-X messages for the device
 738 .Fa dev .
 739 The
 740 .Fn pci_alloc_msix
 741 function may allocate fewer messages than requested for various
 742 reasons including requests for more messages than the device
 743 .Fa dev
 744 supports,
 745 or if the system has a shortage of available MSI-X messages.
 746 On success,
 747 .Fa *count
 748 is set to the number of messages allocated and
 749 .Fn pci_alloc_msix
 750 returns zero.
 751 For MSI-X messages,
 752 the resource ID for each
 753 .Dv SYS_RES_IRQ
 754 resource identifies the index in the MSI-X table of the
 755 corresponding message.
 756 A resource ID of one maps to the first index of the MSI-X table;
 757 a resource ID two identifies the second index in the table, etc.
 758 The
 759 .Fn pci_alloc_msix
 760 function assigns the
 761 .Fa *count
 762 messages allocated to the first
 763 .Fa *count
 764 table indicies.
 765 If
 766 .Fn pci_alloc_msix
 767 is not able to allocate any messages,
 768 it returns an error.
 769 Unlike MSI,
 770 MSI-X does not require message counts that are powers of two.
 771 .Pp
 772 The BARs containing the MSI-X vector table and PBA must be
 773 allocated via
 774 .Xr bus_alloc_resource 9
 775 before calling
 776 .Fn pci_alloc_msix
 777 and must not be released until after calling
 778 .Fn pci_release_msi .
 779 Note that the vector table and PBA may be stored in the same BAR or in
 780 different BARs.
 781 .Pp
 782 The
 783 .Fn pci_pending_msix
 784 function examines the
 785 .Fa dev
 786 device's PBA
 787 to determine the pending status of the MSI-X message at table index
 788 .Fa index .
 789 If the indicated message is pending,
 790 this function returns a non-zero value;
 791 otherwise,
 792 it returns zero.
 793 Passing an invalid
 794 .Fa index
 795 to this function will result in undefined behavior.
 796 .Pp
 797 As mentioned in the description of
 798 .Fn pci_alloc_msix ,
 799 MSI-X messages are initially assigned to the first N table entries.
 800 A driver may use a different distribution of available messages to
 801 table entries via the
 802 .Fn pci_remap_msix
 803 function.
 804 Note that this function must be called after a successful call to
 805 .Fn pci_alloc_msix
 806 but before any of the
 807 .Dv SYS_RES_IRQ
 808 resources are allocated.
 809 The
 810 .Fn pci_remap_msix
 811 function returns zero on success,
 812 or an error on failure.
 813 .Pp
 814 The
 815 .Fa vectors
 816 array should contain
 817 .Fa count
 818 message vectors.
 819 The array maps directly to the MSI-X table in that the first entry in
 820 the array specifies the message used for the first entry in the MSI-X
 821 table,
 822 the second entry in the array corresponds to the second entry in the
 823 MSI-X table,
 824 etc.
 825 The vector value in each array index can either be zero to indicate
 826 that no message should be assigned to the corresponding MSI-X table entry,
 827 or it can be a number from one to N
 828 .Po
 829 where N is the count returned from the previous call to
 830 .Fn pci_alloc_msix
 831 .Pc
 832 to indicate which of the allocated messages should be assigned to the
 833 corresponding MSI-X table entry.
 834 .Pp
 835 If
 836 .Fn pci_remap_msix
 837 succeeds,
 838 each MSI-X table entry with a non-zero vector will have an associated
 839 .Dv SYS_RES_IRQ
 840 resource whose resource ID corresponds to the table index as described
 841 above for
 842 .Fn pci_alloc_msix .
 843 MSI-X table entries that with a vector of zero will not have an
 844 associated
 845 .Dv SYS_RES_IRQ
 846 resource.
 847 Additionally,
 848 if any of the original messages allocated by
 849 .Fn pci_alloc_msix
 850 are not used in the new distribution of messages in the MSI-X table,
 851 they will be released automatically.
 852 Note that if a driver wishes to use fewer messages than were allocated by
 853 .Fn pci_alloc_msix ,
 854 the driver must use a single, contiguous range of messages beginning
 855 with one in the new distribution.
 856 The
 857 .Fn pci_remap_msix
 858 function will fail if this condition is not met.
 859 .Sh IMPLEMENTATION NOTES
 860 The
 861 .Vt pci_addr_t
 862 type varies according to the size of the PCI bus address
 863 space on the target architecture.
 864 .Sh SEE ALSO
 865 .Xr pci 4 ,
 866 .Xr pciconf 8 ,
 867 .Xr bus_alloc_resource 9 ,
 868 .Xr bus_dma 9 ,
 869 .Xr bus_release_resource 9 ,
 870 .Xr bus_setup_intr 9 ,
 871 .Xr bus_teardown_intr 9 ,
 872 .Xr devclass 9 ,
 873 .Xr device 9 ,
 874 .Xr driver 9 ,
 875 .Xr rman 9
 876 .Rs
 877 .%B FreeBSD Developers' Handbook
 878 .%T NewBus
 879 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
 880 .Re
 881 .Rs
 882 .%A Shanley
 883 .%A Anderson
 884 .%B PCI System Architecture
 885 .%N 2nd Edition
 886 .%I Addison-Wesley
 887 .%O ISBN 0-201-30974-2
 888 .Re
 889 .Sh AUTHORS
 890 .An -nosplit
 891 This manual page was written by
 892 .An Bruce M Simpson Aq Mt bms@FreeBSD.org
 893 and
 894 .An John Baldwin Aq Mt jhb@FreeBSD.org .
 895 .Sh BUGS
 896 The kernel PCI code has a number of references to
 897 .Dq "slot numbers" .
 898 These do not refer to the geographic location of PCI devices,
 899 but to the device number assigned by the combination of the PCI IDSEL
 900 mechanism and the platform firmware.
 901 This should be taken note of when working with the kernel PCI code.
 902 .Pp
 903 The PCI bus driver should allocate the MSI-X vector table and PBA internally
 904 as necessary rather than requiring the caller to do so.