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_next_cap ,
46 .Nm pci_find_next_extcap ,
47 .Nm pci_find_next_htcap ,
48 .Nm pci_find_pcie_root_port ,
50 .Nm pci_get_max_payload ,
51 .Nm pci_get_max_read_req ,
52 .Nm pci_get_powerstate ,
53 .Nm pci_get_vpd_ident ,
54 .Nm pci_get_vpd_readonly ,
56 .Nm pci_iov_attach_name ,
60 .Nm pci_msix_pba_bar ,
61 .Nm pci_msix_table_bar ,
62 .Nm pci_pending_msix ,
66 .Nm pci_restore_state ,
68 .Nm pci_set_max_read_req ,
69 .Nm pci_set_powerstate ,
70 .Nm pci_write_config ,
71 .Nm pcie_adjust_config ,
73 .Nm pcie_get_max_completion_timeout ,
74 .Nm pcie_read_config ,
75 .Nm pcie_wait_for_pending_transactions ,
83 .Fn pci_alloc_msi "device_t dev" "int *count"
85 .Fn pci_alloc_msix "device_t dev" "int *count"
87 .Fn pci_disable_busmaster "device_t dev"
89 .Fn pci_disable_io "device_t dev" "int space"
91 .Fn pci_enable_busmaster "device_t dev"
93 .Fn pci_enable_io "device_t dev" "int space"
95 .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
97 .Fn pci_find_cap "device_t dev" "int capability" "int *capreg"
99 .Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func"
101 .Fn pci_find_device "uint16_t vendor" "uint16_t device"
103 .Fn pci_find_extcap "device_t dev" "int capability" "int *capreg"
105 .Fn pci_find_htcap "device_t dev" "int capability" "int *capreg"
107 .Fn pci_find_next_cap "device_t dev" "int capability" "int start" "int *capreg"
109 .Fn pci_find_next_extcap "device_t dev" "int capability" "int start" "int *capreg"
111 .Fn pci_find_next_htcap "device_t dev" "int capability" "int start" "int *capreg"
113 .Fn pci_find_pcie_root_port "device_t dev"
115 .Fn pci_get_id "device_t dev" "enum pci_id_type type" "uintptr_t *id"
117 .Fn pci_get_max_payload "device_t dev"
119 .Fn pci_get_max_read_req "device_t dev"
121 .Fn pci_get_powerstate "device_t dev"
123 .Fn pci_get_vpd_ident "device_t dev" "const char **identptr"
125 .Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr"
127 .Fn pci_msi_count "device_t dev"
129 .Fn pci_msix_count "device_t dev"
131 .Fn pci_msix_pba_bar "device_t dev"
133 .Fn pci_msix_table_bar "device_t dev"
135 .Fn pci_pending_msix "device_t dev" "u_int index"
137 .Fn pci_read_config "device_t dev" "int reg" "int width"
139 .Fn pci_release_msi "device_t dev"
141 .Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors"
143 .Fn pci_restore_state "device_t dev"
145 .Fn pci_save_state "device_t dev"
147 .Fn pci_set_max_read_req "device_t dev" "int size"
149 .Fn pci_set_powerstate "device_t dev" "int state"
151 .Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width"
153 .Fo pcie_adjust_config
161 .Fn pcie_flr "device_t dev" "u_int max_delay" "bool force"
163 .Fn pcie_get_max_completion_timeout "device_t dev"
165 .Fn pcie_read_config "device_t dev" "int reg" "int width"
167 .Fn pcie_wait_for_pending_transactions "device_t dev" "u_int max_delay"
169 .Fn pcie_write_config "device_t dev" "int reg" "uint32_t val" "int width"
171 .Fn pci_event_fn "void *arg" "device_t dev"
172 .Fn EVENTHANDLER_REGISTER "pci_add_device" "pci_event_fn"
173 .Fn EVENTHANDLER_DEREGISTER "pci_delete_resource" "pci_event_fn"
174 .In dev/pci/pci_iov.h
176 .Fn pci_iov_attach "device_t dev" "nvlist_t *pf_schema" "nvlist_t *vf_schema"
178 .Fo pci_iov_attach_name
180 .Fa "nvlist_t *pf_schema"
181 .Fa "nvlist_t *vf_schema"
182 .Fa "const char *fmt"
186 .Fn pci_iov_detach "device_t dev"
190 set of functions are used for managing PCI devices.
191 The functions are split into several groups:
192 raw configuration access,
195 device configuration,
197 message signaled interrupts.
198 .Ss Raw Configuration Access
201 function is used to read data from the PCI configuration
208 specifying the size of the access.
212 function is used to write the value
214 to the PCI configuration
221 specifying the size of the access.
224 .Fn pcie_adjust_config
225 function is used to modify the value of a register in the PCI-express
226 capability register set of device
230 specifies a relative offset in the register set with
232 specifying the size of the access.
233 The new value of the register is computed by modifying bits set in
237 Any bits not specified in
240 The previous value of the register is returned.
244 function is used to read the value of a register in the PCI-express
245 capability register set of device
249 specifies a relative offset in the register set with
251 specifying the size of the access.
254 .Fn pcie_write_config
255 function is used to write the value
257 to a register in the PCI-express capability register set of device
261 specifies a relative offset in the register set with
263 specifying the size of the access.
266 Device drivers should only use these functions for functionality that
267 is not available via another
273 function looks up the
275 of a PCI device, given its
282 number actually refers to the number of the device on the bus,
283 which does not necessarily indicate its geographic location
284 in terms of a physical slot.
285 Note that in case the system has multiple PCI domains,
288 function only searches the first one.
289 Actually, it is equivalent to:
290 .Bd -literal -offset indent
291 pci_find_dbsf(0, bus, slot, func);
296 function looks up the
298 of a PCI device, given its
306 number actually refers to the number of the device on the bus,
307 which does not necessarily indicate its geographic location
308 in terms of a physical slot.
312 function looks up the
314 of a PCI device, given its
319 Note that there can be multiple matches for this search; this function
320 only returns the first matching device.
321 .Ss Device Information
324 function is used to locate the first instance of a PCI capability
325 register set for the device
327 The capability to locate is specified by ID via
329 Constant macros of the form
331 for standard capability IDs are defined in
332 .In dev/pci/pcireg.h .
333 If the capability is found, then
335 is set to the offset in configuration space of the capability register set,
339 If the capability is not found or the device does not support capabilities,
343 .Fn pci_find_next_cap
344 function is used to locate the next instance of a PCI capability
345 register set for the device
354 .Fn pci_find_next_cap .
355 When no more instances are located
356 .Fn pci_find_next_cap
361 function is used to locate the first instance of a PCI-express
362 extended capability register set for the device
364 The extended capability to locate is specified by ID via
366 Constant macros of the form
368 for standard extended capability IDs are defined in
369 .In dev/pci/pcireg.h .
370 If the extended capability is found, then
372 is set to the offset in configuration space of the extended capability
376 If the extended capability is not found or the device is not a
381 .Fn pci_find_next_extcap
382 function is used to locate the next instance of a PCI-express
383 extended capability register set for the device
392 .Fn pci_find_next_extcap .
393 When no more instances are located
394 .Fn pci_find_next_extcap
399 function is used to locate the first instance of a HyperTransport capability
400 register set for the device
402 The capability to locate is specified by type via
404 Constant macros of the form
406 for standard HyperTransport capability types are defined in
407 .In dev/pci/pcireg.h .
408 If the capability is found, then
410 is set to the offset in configuration space of the capability register set,
414 If the capability is not found or the device is not a HyperTransport device,
418 .Fn pci_find_next_htcap
419 function is used to locate the next instance of a HyperTransport capability
420 register set for the device
429 .Fn pci_find_next_htcap .
430 When no more instances are located
431 .Fn pci_find_next_htcap
435 .Fn pci_find_pcie_root_port
436 function walks up the PCI device hierarchy to locate the PCI-express root
439 If a root port is not found,
440 .Fn pci_find_pcie_root_port
446 function is used to read an identifier from a device.
449 flag is used to specify which identifier to read.
450 The following flags are supported:
451 .Bl -hang -width ".Dv PCI_ID_RID"
453 Read the routing identifier for the device.
455 Read the MSI routing ID.
456 This is needed by some interrupt controllers to route MSI and MSI-X interrupts.
460 .Fn pci_get_vpd_ident
461 function is used to fetch a device's Vital Product Data
466 supports VPD and provides an identifier string,
469 is set to point at a read-only, null-terminated copy of the identifier
472 .Fn pci_get_vpd_ident
474 If the device does not support VPD or does not provide an identifier
477 .Fn pci_get_vpd_ident
481 .Fn pci_get_vpd_readonly
482 function is used to fetch the value of a single VPD read-only keyword
485 The keyword to fetch is identified by the two character string
487 If the device supports VPD and provides a read-only value for the
491 is set to point at a read-only, null-terminated copy of the value,
493 .Fn pci_get_vpd_readonly
495 If the device does not support VPD or does not provide the requested
498 .Fn pci_get_vpd_readonly
502 .Fn pcie_get_max_completion_timeout
503 function returns the maximum completion timeout configured for the device
508 device is not a PCI-express device,
509 .Fn pcie_get_max_completion_timeout
511 When completion timeouts are disabled for
513 this function returns the maxmimum timeout that would be used if timeouts
517 .Fn pcie_wait_for_pending_transactions
518 function waits for any pending transactions initiated by the
521 The function checks for pending transactions by polling the transactions
522 pending flag in the PCI-express device status register.
525 once the transaction pending flag is clear.
526 If transactions are still pending after
529 .Fn pcie_wait_for_pending_transactions
535 .Fn pcie_wait_for_pending_transactions
536 performs a single check;
538 this function may sleep while polling the transactions pending flag.
539 .Nm pcie_wait_for_pending_transactions
544 is not a PCI-express device.
545 .Ss Device Configuration
547 .Fn pci_enable_busmaster
548 function enables PCI bus mastering for the device
551 .Dv PCIM_CMD_BUSMASTEREN
556 .Fn pci_disable_busmaster
557 function clears this bit.
561 function enables memory or I/O port address decoding for the device
569 register appropriately.
572 function clears the appropriate bit.
575 argument specifies which resource is affected; this can be either
580 Device drivers should generally not use these routines directly.
581 The PCI bus will enable decoding automatically when a
585 resource is activated via
586 .Xr bus_alloc_resource 9
588 .Xr bus_activate_resource 9 .
591 .Fn pci_get_max_payload
592 function returns the current maximum TLP payload size in bytes for a
596 device is not a PCI-express device,
597 .Fn pci_get_max_payload
601 .Fn pci_get_max_read_req
602 function returns the current maximum read request size in bytes for a
606 device is not a PCI-express device,
607 .Fn pci_get_max_read_req
611 .Fn pci_set_max_read_req
612 sets the PCI-express maximum read request size for
618 .Fn pci_set_max_read_req
619 returns the actual size set in bytes.
622 device is not a PCI-express device,
623 .Fn pci_set_max_read_req
627 .Fn pci_get_powerstate
628 function returns the current power state of the device
630 If the device does not support power management capabilities, then the default
632 .Dv PCI_POWERSTATE_D0
634 The following power states are defined by PCI:
635 .Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN"
636 .It Dv PCI_POWERSTATE_D0
637 State in which device is on and running.
638 It is receiving full power from the system and delivering
639 full functionality to the user.
640 .It Dv PCI_POWERSTATE_D1
641 Class-specific low-power state in which device context may or
643 Buses in this state cannot do anything to the bus, to
644 force devices to lose context.
645 .It Dv PCI_POWERSTATE_D2
646 Class-specific low-power state in which device context may or
648 Attains greater power savings than
649 .Dv PCI_POWERSTATE_D1 .
650 Buses in this state can cause devices to lose some context.
653 be prepared for the bus to be in this state or higher.
654 .It Dv PCI_POWERSTATE_D3
655 State in which the device is off and not running.
656 Device context is lost, and power from the device can
658 .It Dv PCI_POWERSTATE_UNKNOWN
659 State of the device is unknown.
663 .Fn pci_set_powerstate
664 function is used to transition the device
666 to the PCI power state
668 If the device does not support power management capabilities or
669 it does not support the specific power state
671 then the function will fail with
676 function is used to advertise that the given device
677 .Pq and associated device driver
678 supports PCI Single-Root I/O Virtualization
680 A driver that supports SR-IOV must implement the
686 This function should be called during the
689 If this function returns an error, it is recommended that the device driver
690 still successfully attaches, but runs with SR-IOV disabled.
695 parameters are used to define what device-specific configuration parameters the
696 device driver accepts when SR-IOV is enabled for the Physical Function
698 and for individual Virtual Functions
703 for details on how to construct the schema.
708 is invalid or specifies parameter names that conflict with parameter names that
711 will return an error and SR-IOV will not be available on the PF device.
712 If a driver does not accept configuration parameters for either the PF device
713 or the VF devices, the driver must pass an empty schema for that device.
714 The SR-IOV infrastructure takes ownership of the
718 and is responsible for freeing them.
719 The driver must never free the schemas itself.
722 .Fn pci_iov_attach_name
723 function is a variant of
725 that allows the name of the associated character device in
731 function uses the name of
737 function is used to advise the SR-IOV infrastructure that the driver for the
738 given device is attempting to detach and that all SR-IOV resources for the
739 device must be released.
740 This function must be called during the
744 was successfully called on the device and
746 has not subsequently been called on the device and returned no error.
747 If this function returns an error, the
749 method must fail and return an error, as detaching the PF driver while VF
750 devices are active would cause system instability.
751 This function is safe to call and will always succeed if
753 previously failed with an error on the given device, or if
755 was never called on the device.
760 .Fn pci_restore_state
761 functions can be used by a device driver to save and restore standard PCI
765 function must be invoked while the device has valid state before
766 .Fn pci_restore_state
768 If the device is not in the fully-powered state
769 .Pq Dv PCI_POWERSTATE_D0
771 .Fn pci_restore_state
773 then the device will be transitioned to
774 .Dv PCI_POWERSTATE_D0
775 before any config registers are restored.
779 function requests a Function Level Reset
785 is not a PCI-express device or does not support Function Level Resets via
786 the PCI-express device control register,
789 Pending transactions are drained by disabling busmastering and calling
790 .Fn pcie_wait_for_pending_transactions
791 before resetting the device.
794 argument specifies the maximum timeout to wait for pending transactions as
796 .Fn pcie_wait_for_pending_transactions .
798 .Fn pcie_wait_for_pending_transactions
799 fails with a timeout and
803 busmastering is re-enabled and
807 .Fn pcie_wait_for_pending_transactions
808 fails with a timeout and
812 the device is reset despite the timeout.
813 After the reset has been requested,
815 sleeps for at least 100 milliseconds before returning
819 does not save and restore any state around the reset.
820 The caller should save and restore state as needed.
821 .Ss Message Signaled Interrupts
822 Message Signaled Interrupts
825 Enhanced Message Signaled Interrupts
827 are PCI capabilities that provide an alternate method for PCI
828 devices to signal interrupts.
829 The legacy INTx interrupt is available to PCI devices as a
831 resource with a resource ID of zero.
832 MSI and MSI-X interrupts are available to PCI devices as one or more
834 resources with resource IDs greater than zero.
835 A driver must ask the PCI bus to allocate MSI or MSI-X interrupts
840 before it can use MSI or MSI-X
843 A driver is not allowed to use the legacy INTx
845 resource if MSI or MSI-X interrupts have been allocated,
846 and attempts to allocate MSI or MSI-X interrupts will fail if the
847 driver is currently using the legacy INTx
850 A driver is only allowed to use either MSI or MSI-X,
855 function returns the maximum number of MSI messages supported by the
858 If the device does not support MSI,
865 function attempts to allocate
867 MSI messages for the device
871 function may allocate fewer messages than requested for various
872 reasons including requests for more messages than the device
875 or if the system has a shortage of available MSI messages.
878 is set to the number of messages allocated and
883 resources for the allocated messages will be available at consecutive
884 resource IDs beginning with one.
887 is not able to allocate any messages,
889 Note that MSI only supports message counts that are powers of two;
890 requests to allocate a non-power of two count of messages will fail.
894 function is used to release any allocated MSI or MSI-X messages back
898 resources are allocated by the driver or have a configured interrupt
900 this function will fail with
904 function returns zero on success and an error on failure.
908 function returns the maximum number of MSI-X messages supported by the
911 If the device does not support MSI-X,
918 function returns the offset in configuration space of the Base Address Register
920 containing the MSI-X Pending Bit Array (PBA) for device
922 The returned value can be used as the resource ID with
923 .Xr bus_alloc_resource 9
925 .Xr bus_release_resource 9
927 If the device does not support MSI-X,
933 .Fn pci_msix_table_bar
934 function returns the offset in configuration space of the BAR
935 containing the MSI-X vector table for device
937 The returned value can be used as the resource ID with
938 .Xr bus_alloc_resource 9
940 .Xr bus_release_resource 9
942 If the device does not support MSI-X,
944 .Fn pci_msix_table_bar
949 function attempts to allocate
951 MSI-X messages for the device
955 function may allocate fewer messages than requested for various
956 reasons including requests for more messages than the device
959 or if the system has a shortage of available MSI-X messages.
962 is set to the number of messages allocated and
966 the resource ID for each
968 resource identifies the index in the MSI-X table of the
969 corresponding message.
970 A resource ID of one maps to the first index of the MSI-X table;
971 a resource ID two identifies the second index in the table, etc.
976 messages allocated to the first
981 is not able to allocate any messages,
984 MSI-X does not require message counts that are powers of two.
986 The BARs containing the MSI-X vector table and PBA must be
988 .Xr bus_alloc_resource 9
991 and must not be released until after calling
992 .Fn pci_release_msi .
993 Note that the vector table and PBA may be stored in the same BAR or in
998 function examines the
1001 to determine the pending status of the MSI-X message at table index
1003 If the indicated message is pending,
1004 this function returns a non-zero value;
1009 to this function will result in undefined behavior.
1011 As mentioned in the description of
1012 .Fn pci_alloc_msix ,
1013 MSI-X messages are initially assigned to the first N table entries.
1014 A driver may use a different distribution of available messages to
1015 table entries via the
1018 Note that this function must be called after a successful call to
1020 but before any of the
1022 resources are allocated.
1025 function returns zero on success,
1026 or an error on failure.
1030 array should contain
1033 The array maps directly to the MSI-X table in that the first entry in
1034 the array specifies the message used for the first entry in the MSI-X
1036 the second entry in the array corresponds to the second entry in the
1039 The vector value in each array index can either be zero to indicate
1040 that no message should be assigned to the corresponding MSI-X table entry,
1041 or it can be a number from one to N
1043 where N is the count returned from the previous call to
1046 to indicate which of the allocated messages should be assigned to the
1047 corresponding MSI-X table entry.
1052 each MSI-X table entry with a non-zero vector will have an associated
1054 resource whose resource ID corresponds to the table index as described
1056 .Fn pci_alloc_msix .
1057 MSI-X table entries that with a vector of zero will not have an
1062 if any of the original messages allocated by
1064 are not used in the new distribution of messages in the MSI-X table,
1065 they will be released automatically.
1066 Note that if a driver wishes to use fewer messages than were allocated by
1067 .Fn pci_alloc_msix ,
1068 the driver must use a single, contiguous range of messages beginning
1069 with one in the new distribution.
1072 function will fail if this condition is not met.
1076 event handler is invoked every time a new PCI device is added to the system.
1077 This includes the creation of Virtual Functions via SR-IOV.
1080 .Va pci_delete_device
1081 event handler is invoked every time a PCI device is removed from the system.
1083 Both event handlers pass the
1085 object of the relevant PCI device as
1087 to each callback function.
1088 Both event handlers are invoked while
1090 is unattached but with valid instance variables.
1094 .Xr bus_alloc_resource 9 ,
1096 .Xr bus_release_resource 9 ,
1097 .Xr bus_setup_intr 9 ,
1098 .Xr bus_teardown_intr 9 ,
1102 .Xr eventhandler 9 ,
1105 .%B FreeBSD Developers' Handbook
1107 .%U https://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
1112 .%B PCI System Architecture
1115 .%O ISBN 0-201-30974-2
1119 This manual page was written by
1120 .An Bruce M Simpson Aq Mt bms@FreeBSD.org
1122 .An John Baldwin Aq Mt jhb@FreeBSD.org .
1124 The kernel PCI code has a number of references to
1125 .Dq "slot numbers" .
1126 These do not refer to the geographic location of PCI devices,
1127 but to the device number assigned by the combination of the PCI IDSEL
1128 mechanism and the platform firmware.
1129 This should be taken note of when working with the kernel PCI code.
1131 The PCI bus driver should allocate the MSI-X vector table and PBA internally
1132 as necessary rather than requiring the caller to do so.