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