2 .\" Copyright (c) 2005 Bruce M Simpson <bms@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
35 .Nm pci_disable_busmaster ,
37 .Nm pci_enable_busmaster ,
45 .Nm pci_find_pcie_root_port ,
46 .Nm pci_get_max_payload ,
47 .Nm pci_get_max_read_req ,
48 .Nm pci_get_powerstate ,
49 .Nm pci_get_vpd_ident ,
50 .Nm pci_get_vpd_readonly ,
53 .Nm pci_msix_pba_bar ,
54 .Nm pci_msix_table_bar ,
55 .Nm pci_pending_msix ,
59 .Nm pci_restore_state ,
61 .Nm pci_set_max_read_req ,
62 .Nm pci_set_powerstate ,
63 .Nm pci_write_config ,
64 .Nm pcie_adjust_config ,
66 .Nm pcie_get_max_completion_timeout ,
67 .Nm pcie_read_config ,
68 .Nm pcie_wait_for_pending_transactions ,
76 .Fn pci_alloc_msi "device_t dev" "int *count"
78 .Fn pci_alloc_msix "device_t dev" "int *count"
80 .Fn pci_disable_busmaster "device_t dev"
82 .Fn pci_disable_io "device_t dev" "int space"
84 .Fn pci_enable_busmaster "device_t dev"
86 .Fn pci_enable_io "device_t dev" "int space"
88 .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
90 .Fn pci_find_cap "device_t dev" "int capability" "int *capreg"
92 .Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func"
94 .Fn pci_find_device "uint16_t vendor" "uint16_t device"
96 .Fn pci_find_extcap "device_t dev" "int capability" "int *capreg"
98 .Fn pci_find_htcap "device_t dev" "int capability" "int *capreg"
100 .Fn pci_find_pcie_root_port "device_t dev"
102 .Fn pci_get_max_payload "device_t dev"
104 .Fn pci_get_max_read_req "device_t dev"
106 .Fn pci_get_powerstate "device_t dev"
108 .Fn pci_get_vpd_ident "device_t dev" "const char **identptr"
110 .Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr"
112 .Fn pci_msi_count "device_t dev"
114 .Fn pci_msix_count "device_t dev"
116 .Fn pci_msix_pba_bar "device_t dev"
118 .Fn pci_msix_table_bar "device_t dev"
120 .Fn pci_pending_msix "device_t dev" "u_int index"
122 .Fn pci_read_config "device_t dev" "int reg" "int width"
124 .Fn pci_release_msi "device_t dev"
126 .Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors"
128 .Fn pci_restore_state "device_t dev"
130 .Fn pci_save_state "device_t dev"
132 .Fn pci_set_max_read_req "device_t dev" "int size"
134 .Fn pci_set_powerstate "device_t dev" "int state"
136 .Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width"
138 .Fo pcie_adjust_config
146 .Fn pcie_flr "device_t dev" "u_int max_delay" "bool force"
148 .Fn pcie_get_max_completion_timeout "device_t dev"
150 .Fn pcie_read_config "device_t dev" "int reg" "int width"
152 .Fn pcie_wait_for_pending_transactions "device_t dev" "u_int max_delay"
154 .Fn pcie_write_config "device_t dev" "int reg" "uint32_t val" "int width"
158 set of functions are used for managing PCI devices.
159 The functions are split into several groups:
160 raw configuration access,
163 device configuration,
165 message signaled interrupts.
166 .Ss Raw Configuration Access
169 function is used to read data from the PCI configuration
176 specifying the size of the access.
180 function is used to write the value
182 to the PCI configuration
189 specifying the size of the access.
192 .Fn pcie_adjust_config
193 function is used to modify the value of a register in the PCI-express
194 capability register set of device
198 specifies a relative offset in the register set with
200 specifying the size of the access.
201 The new value of the register is computed by modifying bits set in
205 Any bits not specified in
208 The previous value of the register is returned.
212 function is used to read the value of a register in the PCI-express
213 capability register set of device
217 specifies a relative offset in the register set with
219 specifying the size of the access.
222 .Fn pcie_write_config
223 function is used to write the value
225 to a register in the PCI-express capability register set of device
229 specifies a relative offset in the register set with
231 specifying the size of the access.
234 Device drivers should only use these functions for functionality that
235 is not available via another
241 function looks up the
243 of a PCI device, given its
250 number actually refers to the number of the device on the bus,
251 which does not necessarily indicate its geographic location
252 in terms of a physical slot.
253 Note that in case the system has multiple PCI domains,
256 function only searches the first one.
257 Actually, it is equivalent to:
258 .Bd -literal -offset indent
259 pci_find_dbsf(0, bus, slot, func);
264 function looks up the
266 of a PCI device, given its
274 number actually refers to the number of the device on the bus,
275 which does not necessarily indicate its geographic location
276 in terms of a physical slot.
280 function looks up the
282 of a PCI device, given its
287 Note that there can be multiple matches for this search; this function
288 only returns the first matching device.
289 .Ss Device Information
292 function is used to locate the first instance of a PCI capability
293 register set for the device
295 The capability to locate is specified by ID via
297 Constant macros of the form
299 for standard capability IDs are defined in
300 .In dev/pci/pcireg.h .
301 If the capability is found, then
303 is set to the offset in configuration space of the capability register set,
307 If the capability is not found or the device does not support capabilities,
313 function is used to locate the first instance of a PCI-express
314 extended capability register set for the device
316 The extended capability to locate is specified by ID via
318 Constant macros of the form
320 for standard extended capability IDs are defined in
321 .In dev/pci/pcireg.h .
322 If the extended capability is found, then
324 is set to the offset in configuration space of the extended capability
328 If the extended capability is not found or the device is not a
335 function is used to locate the first instance of a HyperTransport capability
336 register set for the device
338 The capability to locate is specified by type via
340 Constant macros of the form
342 for standard HyperTransport capability types are defined in
343 .In dev/pci/pcireg.h .
344 If the capability is found, then
346 is set to the offset in configuration space of the capability register set,
350 If the capability is not found or the device is not a HyperTransport device,
355 .Fn pci_find_pcie_root_port
356 function walks up the PCI device hierarchy to locate the PCI-express root
359 If a root port is not found,
360 .Fn pci_find_pcie_root_port
365 .Fn pci_get_vpd_ident
366 function is used to fetch a device's Vital Product Data
371 supports VPD and provides an identifier string,
374 is set to point at a read-only, null-terminated copy of the identifier
377 .Fn pci_get_vpd_ident
379 If the device does not support VPD or does not provide an identifier
382 .Fn pci_get_vpd_ident
386 .Fn pci_get_vpd_readonly
387 function is used to fetch the value of a single VPD read-only keyword
390 The keyword to fetch is identified by the two character string
392 If the device supports VPD and provides a read-only value for the
396 is set to point at a read-only, null-terminated copy of the value,
398 .Fn pci_get_vpd_readonly
400 If the device does not support VPD or does not provide the requested
403 .Fn pci_get_vpd_readonly
407 .Fn pcie_get_max_completion_timeout
408 function returns the maximum completion timeout configured for the device
413 device is not a PCI-express device,
414 .Fn pcie_get_max_completion_timeout
416 When completion timeouts are disabled for
418 this function returns the maxmimum timeout that would be used if timeouts
422 .Fn pcie_wait_for_pending_transactions
423 function waits for any pending transactions initiated by the
426 The function checks for pending transactions by polling the transactions
427 pending flag in the PCI-express device status register.
430 once the transaction pending flag is clear.
431 If transactions are still pending after
434 .Fn pcie_wait_for_pending_transactions
440 .Fn pcie_wait_for_pending_transactions
441 performs a single check;
443 this function may sleep while polling the transactions pending flag.
444 .Nm pcie_wait_for_pending_transactions
449 is not a PCI-express device.
450 .Ss Device Configuration
452 .Fn pci_enable_busmaster
453 function enables PCI bus mastering for the device
456 .Dv PCIM_CMD_BUSMASTEREN
461 .Fn pci_disable_busmaster
462 function clears this bit.
466 function enables memory or I/O port address decoding for the device
474 register appropriately.
477 function clears the appropriate bit.
480 argument specifies which resource is affected; this can be either
485 Device drivers should generally not use these routines directly.
486 The PCI bus will enable decoding automatically when a
490 resource is activated via
491 .Xr bus_alloc_resource 9
493 .Xr bus_activate_resource 9 .
496 .Fn pci_get_max_payload
497 function returns the current maximum TLP payload size in bytes for a
501 device is not a PCI-express device,
502 .Fn pci_get_max_payload
506 .Fn pci_get_max_read_req
507 function returns the current maximum read request size in bytes for a
511 device is not a PCI-express device,
512 .Fn pci_get_max_read_req
516 .Fn pci_set_max_read_req
517 sets the PCI-express maximum read request size for
523 .Fn pci_set_max_read_req
524 returns the actual size set in bytes.
527 device is not a PCI-express device,
528 .Fn pci_set_max_read_req
532 .Fn pci_get_powerstate
533 function returns the current power state of the device
535 If the device does not support power management capabilities, then the default
537 .Dv PCI_POWERSTATE_D0
539 The following power states are defined by PCI:
540 .Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN"
541 .It Dv PCI_POWERSTATE_D0
542 State in which device is on and running.
543 It is receiving full power from the system and delivering
544 full functionality to the user.
545 .It Dv PCI_POWERSTATE_D1
546 Class-specific low-power state in which device context may or
548 Busses in this state cannot do anything to the bus, to
549 force devices to lose context.
550 .It Dv PCI_POWERSTATE_D2
551 Class-specific low-power state in which device context may or
553 Attains greater power savings than
554 .Dv PCI_POWERSTATE_D1 .
555 Busses in this state can cause devices to lose some context.
558 be prepared for the bus to be in this state or higher.
559 .It Dv PCI_POWERSTATE_D3
560 State in which the device is off and not running.
561 Device context is lost, and power from the device can
563 .It Dv PCI_POWERSTATE_UNKNOWN
564 State of the device is unknown.
568 .Fn pci_set_powerstate
569 function is used to transition the device
571 to the PCI power state
573 If the device does not support power management capabilities or
574 it does not support the specific power state
576 then the function will fail with
582 .Fn pci_restore_state
583 functions can be used by a device driver to save and restore standard PCI
587 function must be invoked while the device has valid state before
588 .Fn pci_restore_state
590 If the device is not in the fully-powered state
591 .Pq Dv PCI_POWERSTATE_D0
593 .Fn pci_restore_state
595 then the device will be transitioned to
596 .Dv PCI_POWERSTATE_D0
597 before any config registers are restored.
601 function requests a Function Level Reset
607 is not a PCI-express device or does not support Function Level Resets via
608 the PCI-express device control register,
611 Pending transactions are drained by disabling busmastering and calling
612 .Fn pcie_wait_for_pending_transactions
613 before resetting the device.
616 argument specifies the maximum timeout to wait for pending transactions as
618 .Fn pcie_wait_for_pending_transactions .
620 .Fn pcie_wait_for_pending_transactions
621 fails with a timeout and
625 busmastering is re-enabled and
629 .Fn pcie_wait_for_pending_transactions
630 fails with a timeout and
634 the device is reset despite the timeout.
635 After the reset has been requested,
637 sleeps for at least 100 milliseconds before returning
641 does not save and restore any state around the reset.
642 The caller should save and restore state as needed.
643 .Ss Message Signaled Interrupts
644 Message Signaled Interrupts
647 Enhanced Message Signaled Interrupts
649 are PCI capabilities that provide an alternate method for PCI
650 devices to signal interrupts.
651 The legacy INTx interrupt is available to PCI devices as a
653 resource with a resource ID of zero.
654 MSI and MSI-X interrupts are available to PCI devices as one or more
656 resources with resource IDs greater than zero.
657 A driver must ask the PCI bus to allocate MSI or MSI-X interrupts
662 before it can use MSI or MSI-X
665 A driver is not allowed to use the legacy INTx
667 resource if MSI or MSI-X interrupts have been allocated,
668 and attempts to allocate MSI or MSI-X interrupts will fail if the
669 driver is currently using the legacy INTx
672 A driver is only allowed to use either MSI or MSI-X,
677 function returns the maximum number of MSI messages supported by the
680 If the device does not support MSI,
687 function attempts to allocate
689 MSI messages for the device
693 function may allocate fewer messages than requested for various
694 reasons including requests for more messages than the device
697 or if the system has a shortage of available MSI messages.
700 is set to the number of messages allocated and
705 resources for the allocated messages will be available at consecutive
706 resource IDs beginning with one.
709 is not able to allocate any messages,
711 Note that MSI only supports message counts that are powers of two;
712 requests to allocate a non-power of two count of messages will fail.
716 function is used to release any allocated MSI or MSI-X messages back
720 resources are allocated by the driver or have a configured interrupt
722 this function will fail with
726 function returns zero on success and an error on failure.
730 function returns the maximum number of MSI-X messages supported by the
733 If the device does not support MSI-X,
740 function returns the offset in configuration space of the Base Address Register
742 containing the MSI-X Pending Bit Array (PBA) for device
744 The returned value can be used as the resource ID with
745 .Xr bus_alloc_resource 9
747 .Xr bus_release_resource 9
749 If the device does not support MSI-X,
755 .Fn pci_msix_table_bar
756 function returns the offset in configuration space of the BAR
757 containing the MSI-X vector table for device
759 The returned value can be used as the resource ID with
760 .Xr bus_alloc_resource 9
762 .Xr bus_release_resource 9
764 If the device does not support MSI-X,
766 .Fn pci_msix_table_bar
771 function attempts to allocate
773 MSI-X messages for the device
777 function may allocate fewer messages than requested for various
778 reasons including requests for more messages than the device
781 or if the system has a shortage of available MSI-X messages.
784 is set to the number of messages allocated and
788 the resource ID for each
790 resource identifies the index in the MSI-X table of the
791 corresponding message.
792 A resource ID of one maps to the first index of the MSI-X table;
793 a resource ID two identifies the second index in the table, etc.
798 messages allocated to the first
803 is not able to allocate any messages,
806 MSI-X does not require message counts that are powers of two.
808 The BARs containing the MSI-X vector table and PBA must be
810 .Xr bus_alloc_resource 9
813 and must not be released until after calling
814 .Fn pci_release_msi .
815 Note that the vector table and PBA may be stored in the same BAR or in
820 function examines the
823 to determine the pending status of the MSI-X message at table index
825 If the indicated message is pending,
826 this function returns a non-zero value;
831 to this function will result in undefined behavior.
833 As mentioned in the description of
835 MSI-X messages are initially assigned to the first N table entries.
836 A driver may use a different distribution of available messages to
837 table entries via the
840 Note that this function must be called after a successful call to
842 but before any of the
844 resources are allocated.
847 function returns zero on success,
848 or an error on failure.
855 The array maps directly to the MSI-X table in that the first entry in
856 the array specifies the message used for the first entry in the MSI-X
858 the second entry in the array corresponds to the second entry in the
861 The vector value in each array index can either be zero to indicate
862 that no message should be assigned to the corresponding MSI-X table entry,
863 or it can be a number from one to N
865 where N is the count returned from the previous call to
868 to indicate which of the allocated messages should be assigned to the
869 corresponding MSI-X table entry.
874 each MSI-X table entry with a non-zero vector will have an associated
876 resource whose resource ID corresponds to the table index as described
879 MSI-X table entries that with a vector of zero will not have an
884 if any of the original messages allocated by
886 are not used in the new distribution of messages in the MSI-X table,
887 they will be released automatically.
888 Note that if a driver wishes to use fewer messages than were allocated by
890 the driver must use a single, contiguous range of messages beginning
891 with one in the new distribution.
894 function will fail if this condition is not met.
898 .Xr bus_alloc_resource 9 ,
900 .Xr bus_release_resource 9 ,
901 .Xr bus_setup_intr 9 ,
902 .Xr bus_teardown_intr 9 ,
908 .%B FreeBSD Developers' Handbook
910 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
915 .%B PCI System Architecture
918 .%O ISBN 0-201-30974-2
921 This manual page was written by
922 .An Bruce M Simpson Aq bms@FreeBSD.org
924 .An John Baldwin Aq jhb@FreeBSD.org .
926 The kernel PCI code has a number of references to
928 These do not refer to the geographic location of PCI devices,
929 but to the device number assigned by the combination of the PCI IDSEL
930 mechanism and the platform firmware.
931 This should be taken note of when working with the kernel PCI code.
933 The PCI bus driver should allocate the MSI-X vector table and PBA internally
934 as necessary rather than requiring the caller to do so.