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