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