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