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