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