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 ,
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 ,
53 .Nm pci_iov_attach_name ,
57 .Nm pci_msix_pba_bar ,
58 .Nm pci_msix_table_bar ,
59 .Nm pci_pending_msix ,
63 .Nm pci_restore_state ,
65 .Nm pci_set_max_read_req ,
66 .Nm pci_set_powerstate ,
67 .Nm pci_write_config ,
68 .Nm pcie_adjust_config ,
70 .Nm pcie_get_max_completion_timeout ,
71 .Nm pcie_read_config ,
72 .Nm pcie_wait_for_pending_transactions ,
80 .Fn pci_alloc_msi "device_t dev" "int *count"
82 .Fn pci_alloc_msix "device_t dev" "int *count"
84 .Fn pci_disable_busmaster "device_t dev"
86 .Fn pci_disable_io "device_t dev" "int space"
88 .Fn pci_enable_busmaster "device_t dev"
90 .Fn pci_enable_io "device_t dev" "int space"
92 .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
94 .Fn pci_find_cap "device_t dev" "int capability" "int *capreg"
96 .Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func"
98 .Fn pci_find_device "uint16_t vendor" "uint16_t device"
100 .Fn pci_find_extcap "device_t dev" "int capability" "int *capreg"
102 .Fn pci_find_htcap "device_t dev" "int capability" "int *capreg"
104 .Fn pci_find_pcie_root_port "device_t dev"
106 .Fn pci_get_id "device_t dev" "enum pci_id_type type" "uintptr_t *id"
108 .Fn pci_get_max_payload "device_t dev"
110 .Fn pci_get_max_read_req "device_t dev"
112 .Fn pci_get_powerstate "device_t dev"
114 .Fn pci_get_vpd_ident "device_t dev" "const char **identptr"
116 .Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr"
118 .Fn pci_msi_count "device_t dev"
120 .Fn pci_msix_count "device_t dev"
122 .Fn pci_msix_pba_bar "device_t dev"
124 .Fn pci_msix_table_bar "device_t dev"
126 .Fn pci_pending_msix "device_t dev" "u_int index"
128 .Fn pci_read_config "device_t dev" "int reg" "int width"
130 .Fn pci_release_msi "device_t dev"
132 .Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors"
134 .Fn pci_restore_state "device_t dev"
136 .Fn pci_save_state "device_t dev"
138 .Fn pci_set_max_read_req "device_t dev" "int size"
140 .Fn pci_set_powerstate "device_t dev" "int state"
142 .Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width"
144 .Fo pcie_adjust_config
152 .Fn pcie_flr "device_t dev" "u_int max_delay" "bool force"
154 .Fn pcie_get_max_completion_timeout "device_t dev"
156 .Fn pcie_read_config "device_t dev" "int reg" "int width"
158 .Fn pcie_wait_for_pending_transactions "device_t dev" "u_int max_delay"
160 .Fn pcie_write_config "device_t dev" "int reg" "uint32_t val" "int width"
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
167 .Fn pci_iov_attach "device_t dev" "nvlist_t *pf_schema" "nvlist_t *vf_schema"
169 .Fo pci_iov_attach_name
171 .Fa "nvlist_t *pf_schema"
172 .Fa "nvlist_t *vf_schema"
173 .Fa "const char *fmt"
177 .Fn pci_iov_detach "device_t dev"
181 set of functions are used for managing PCI devices.
182 The functions are split into several groups:
183 raw configuration access,
186 device configuration,
188 message signaled interrupts.
189 .Ss Raw Configuration Access
192 function is used to read data from the PCI configuration
199 specifying the size of the access.
203 function is used to write the value
205 to the PCI configuration
212 specifying the size of the access.
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
221 specifies a relative offset in the register set with
223 specifying the size of the access.
224 The new value of the register is computed by modifying bits set in
228 Any bits not specified in
231 The previous value of the register is returned.
235 function is used to read the value of a register in the PCI-express
236 capability register set of device
240 specifies a relative offset in the register set with
242 specifying the size of the access.
245 .Fn pcie_write_config
246 function is used to write the value
248 to a register in the PCI-express capability register set of device
252 specifies a relative offset in the register set with
254 specifying the size of the access.
257 Device drivers should only use these functions for functionality that
258 is not available via another
264 function looks up the
266 of a PCI device, given its
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,
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);
287 function looks up the
289 of a PCI device, given its
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.
303 function looks up the
305 of a PCI device, given its
310 Note that there can be multiple matches for this search; this function
311 only returns the first matching device.
312 .Ss Device Information
315 function is used to locate the first instance of a PCI capability
316 register set for the device
318 The capability to locate is specified by ID via
320 Constant macros of the form
322 for standard capability IDs are defined in
323 .In dev/pci/pcireg.h .
324 If the capability is found, then
326 is set to the offset in configuration space of the capability register set,
330 If the capability is not found or the device does not support capabilities,
336 function is used to locate the first instance of a PCI-express
337 extended capability register set for the device
339 The extended capability to locate is specified by ID via
341 Constant macros of the form
343 for standard extended capability IDs are defined in
344 .In dev/pci/pcireg.h .
345 If the extended capability is found, then
347 is set to the offset in configuration space of the extended capability
351 If the extended capability is not found or the device is not a
358 function is used to locate the first instance of a HyperTransport capability
359 register set for the device
361 The capability to locate is specified by type via
363 Constant macros of the form
365 for standard HyperTransport capability types are defined in
366 .In dev/pci/pcireg.h .
367 If the capability is found, then
369 is set to the offset in configuration space of the capability register set,
373 If the capability is not found or the device is not a HyperTransport device,
378 .Fn pci_find_pcie_root_port
379 function walks up the PCI device hierarchy to locate the PCI-express root
382 If a root port is not found,
383 .Fn pci_find_pcie_root_port
389 function is used to read an identifier from a device.
392 flag is used to specify which identifier to read.
393 The following flags are supported:
394 .Bl -hang -width ".Dv PCI_ID_RID"
396 Read the routing identifier for the device.
398 Read the MSI routing ID.
399 This is needed by some interrupt controllers to route MSI and MSI-X interrupts.
403 .Fn pci_get_vpd_ident
404 function is used to fetch a device's Vital Product Data
409 supports VPD and provides an identifier string,
412 is set to point at a read-only, null-terminated copy of the identifier
415 .Fn pci_get_vpd_ident
417 If the device does not support VPD or does not provide an identifier
420 .Fn pci_get_vpd_ident
424 .Fn pci_get_vpd_readonly
425 function is used to fetch the value of a single VPD read-only keyword
428 The keyword to fetch is identified by the two character string
430 If the device supports VPD and provides a read-only value for the
434 is set to point at a read-only, null-terminated copy of the value,
436 .Fn pci_get_vpd_readonly
438 If the device does not support VPD or does not provide the requested
441 .Fn pci_get_vpd_readonly
445 .Fn pcie_get_max_completion_timeout
446 function returns the maximum completion timeout configured for the device
451 device is not a PCI-express device,
452 .Fn pcie_get_max_completion_timeout
454 When completion timeouts are disabled for
456 this function returns the maxmimum timeout that would be used if timeouts
460 .Fn pcie_wait_for_pending_transactions
461 function waits for any pending transactions initiated by the
464 The function checks for pending transactions by polling the transactions
465 pending flag in the PCI-express device status register.
468 once the transaction pending flag is clear.
469 If transactions are still pending after
472 .Fn pcie_wait_for_pending_transactions
478 .Fn pcie_wait_for_pending_transactions
479 performs a single check;
481 this function may sleep while polling the transactions pending flag.
482 .Nm pcie_wait_for_pending_transactions
487 is not a PCI-express device.
488 .Ss Device Configuration
490 .Fn pci_enable_busmaster
491 function enables PCI bus mastering for the device
494 .Dv PCIM_CMD_BUSMASTEREN
499 .Fn pci_disable_busmaster
500 function clears this bit.
504 function enables memory or I/O port address decoding for the device
512 register appropriately.
515 function clears the appropriate bit.
518 argument specifies which resource is affected; this can be either
523 Device drivers should generally not use these routines directly.
524 The PCI bus will enable decoding automatically when a
528 resource is activated via
529 .Xr bus_alloc_resource 9
531 .Xr bus_activate_resource 9 .
534 .Fn pci_get_max_payload
535 function returns the current maximum TLP payload size in bytes for a
539 device is not a PCI-express device,
540 .Fn pci_get_max_payload
544 .Fn pci_get_max_read_req
545 function returns the current maximum read request size in bytes for a
549 device is not a PCI-express device,
550 .Fn pci_get_max_read_req
554 .Fn pci_set_max_read_req
555 sets the PCI-express maximum read request size for
561 .Fn pci_set_max_read_req
562 returns the actual size set in bytes.
565 device is not a PCI-express device,
566 .Fn pci_set_max_read_req
570 .Fn pci_get_powerstate
571 function returns the current power state of the device
573 If the device does not support power management capabilities, then the default
575 .Dv PCI_POWERSTATE_D0
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
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
591 Attains greater power savings than
592 .Dv PCI_POWERSTATE_D1 .
593 Buses in this state can cause devices to lose some context.
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
601 .It Dv PCI_POWERSTATE_UNKNOWN
602 State of the device is unknown.
606 .Fn pci_set_powerstate
607 function is used to transition the device
609 to the PCI power state
611 If the device does not support power management capabilities or
612 it does not support the specific power state
614 then the function will fail with
619 function is used to advertise that the given device
620 .Pq and associated device driver
621 supports PCI Single-Root I/O Virtualization
623 A driver that supports SR-IOV must implement the
629 This function should be called during the
632 If this function returns an error, it is recommended that the device driver
633 still successfully attaches, but runs with SR-IOV disabled.
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
641 and for individual Virtual Functions
646 for details on how to construct the schema.
651 is invalid or specifies parameter names that conflict with parameter names that
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
661 and is responsible for freeing them.
662 The driver must never free the schemas itself.
665 .Fn pci_iov_attach_name
666 function is a variant of
668 that allows the name of the associated character device in
674 function uses the name of
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
687 was successfully called on the device and
689 has not subsequently been called on the device and returned no error.
690 If this function returns an error, the
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
696 previously failed with an error on the given device, or if
698 was never called on the device.
703 .Fn pci_restore_state
704 functions can be used by a device driver to save and restore standard PCI
708 function must be invoked while the device has valid state before
709 .Fn pci_restore_state
711 If the device is not in the fully-powered state
712 .Pq Dv PCI_POWERSTATE_D0
714 .Fn pci_restore_state
716 then the device will be transitioned to
717 .Dv PCI_POWERSTATE_D0
718 before any config registers are restored.
722 function requests a Function Level Reset
728 is not a PCI-express device or does not support Function Level Resets via
729 the PCI-express device control register,
732 Pending transactions are drained by disabling busmastering and calling
733 .Fn pcie_wait_for_pending_transactions
734 before resetting the device.
737 argument specifies the maximum timeout to wait for pending transactions as
739 .Fn pcie_wait_for_pending_transactions .
741 .Fn pcie_wait_for_pending_transactions
742 fails with a timeout and
746 busmastering is re-enabled and
750 .Fn pcie_wait_for_pending_transactions
751 fails with a timeout and
755 the device is reset despite the timeout.
756 After the reset has been requested,
758 sleeps for at least 100 milliseconds before returning
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
768 Enhanced Message Signaled Interrupts
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
774 resource with a resource ID of zero.
775 MSI and MSI-X interrupts are available to PCI devices as one or more
777 resources with resource IDs greater than zero.
778 A driver must ask the PCI bus to allocate MSI or MSI-X interrupts
783 before it can use MSI or MSI-X
786 A driver is not allowed to use the legacy INTx
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
793 A driver is only allowed to use either MSI or MSI-X,
798 function returns the maximum number of MSI messages supported by the
801 If the device does not support MSI,
808 function attempts to allocate
810 MSI messages for the device
814 function may allocate fewer messages than requested for various
815 reasons including requests for more messages than the device
818 or if the system has a shortage of available MSI messages.
821 is set to the number of messages allocated and
826 resources for the allocated messages will be available at consecutive
827 resource IDs beginning with one.
830 is not able to allocate any messages,
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.
837 function is used to release any allocated MSI or MSI-X messages back
841 resources are allocated by the driver or have a configured interrupt
843 this function will fail with
847 function returns zero on success and an error on failure.
851 function returns the maximum number of MSI-X messages supported by the
854 If the device does not support MSI-X,
861 function returns the offset in configuration space of the Base Address Register
863 containing the MSI-X Pending Bit Array (PBA) for device
865 The returned value can be used as the resource ID with
866 .Xr bus_alloc_resource 9
868 .Xr bus_release_resource 9
870 If the device does not support MSI-X,
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
880 The returned value can be used as the resource ID with
881 .Xr bus_alloc_resource 9
883 .Xr bus_release_resource 9
885 If the device does not support MSI-X,
887 .Fn pci_msix_table_bar
892 function attempts to allocate
894 MSI-X messages for the device
898 function may allocate fewer messages than requested for various
899 reasons including requests for more messages than the device
902 or if the system has a shortage of available MSI-X messages.
905 is set to the number of messages allocated and
909 the resource ID for each
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.
919 messages allocated to the first
924 is not able to allocate any messages,
927 MSI-X does not require message counts that are powers of two.
929 The BARs containing the MSI-X vector table and PBA must be
931 .Xr bus_alloc_resource 9
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
941 function examines the
944 to determine the pending status of the MSI-X message at table index
946 If the indicated message is pending,
947 this function returns a non-zero value;
952 to this function will result in undefined behavior.
954 As mentioned in the description of
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
961 Note that this function must be called after a successful call to
963 but before any of the
965 resources are allocated.
968 function returns zero on success,
969 or an error on failure.
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
979 the second entry in the array corresponds to the second entry in the
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
986 where N is the count returned from the previous call to
989 to indicate which of the allocated messages should be assigned to the
990 corresponding MSI-X table entry.
995 each MSI-X table entry with a non-zero vector will have an associated
997 resource whose resource ID corresponds to the table index as described
1000 MSI-X table entries that with a vector of zero will not have an
1005 if any of the original messages allocated by
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.
1015 function will fail if this condition is not met.
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.
1023 .Va pci_delete_device
1024 event handler is invoked every time a PCI device is removed from the system.
1026 Both event handlers pass the
1028 object of the relevant PCI device as
1030 to each callback function.
1031 Both event handlers are invoked while
1033 is unattached but with valid instance variables.
1037 .Xr bus_alloc_resource 9 ,
1039 .Xr bus_release_resource 9 ,
1040 .Xr bus_setup_intr 9 ,
1041 .Xr bus_teardown_intr 9 ,
1045 .Xr eventhandler 9 ,
1048 .%B FreeBSD Developers' Handbook
1050 .%U https://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
1055 .%B PCI System Architecture
1058 .%O ISBN 0-201-30974-2
1062 This manual page was written by
1063 .An Bruce M Simpson Aq Mt bms@FreeBSD.org
1065 .An John Baldwin Aq Mt jhb@FreeBSD.org .
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.
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.