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