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