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