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