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 ,
65 .Nm pcie_read_config ,
73 .Fn pci_alloc_msi "device_t dev" "int *count"
75 .Fn pci_alloc_msix "device_t dev" "int *count"
77 .Fn pci_disable_busmaster "device_t dev"
79 .Fn pci_disable_io "device_t dev" "int space"
81 .Fn pci_enable_busmaster "device_t dev"
83 .Fn pci_enable_io "device_t dev" "int space"
85 .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
87 .Fn pci_find_cap "device_t dev" "int capability" "int *capreg"
89 .Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func"
91 .Fn pci_find_device "uint16_t vendor" "uint16_t device"
93 .Fn pci_find_extcap "device_t dev" "int capability" "int *capreg"
95 .Fn pci_find_htcap "device_t dev" "int capability" "int *capreg"
97 .Fn pci_find_pcie_root_port "device_t dev"
99 .Fn pci_get_max_payload "device_t dev"
101 .Fn pci_get_max_read_req "device_t dev"
103 .Fn pci_get_powerstate "device_t dev"
105 .Fn pci_get_vpd_ident "device_t dev" "const char **identptr"
107 .Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr"
109 .Fn pci_msi_count "device_t dev"
111 .Fn pci_msix_count "device_t dev"
113 .Fn pci_msix_pba_bar "device_t dev"
115 .Fn pci_msix_table_bar "device_t dev"
117 .Fn pci_pending_msix "device_t dev" "u_int index"
119 .Fn pci_read_config "device_t dev" "int reg" "int width"
121 .Fn pci_release_msi "device_t dev"
123 .Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors"
125 .Fn pci_restore_state "device_t dev"
127 .Fn pci_save_state "device_t dev"
129 .Fn pci_set_max_read_req "device_t dev" "int size"
131 .Fn pci_set_powerstate "device_t dev" "int state"
133 .Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width"
135 .Fo pcie_adjust_config
143 .Fn pcie_read_config "device_t dev" "int reg" "int width"
145 .Fn pcie_write_config "device_t dev" "int reg" "uint32_t val" "int width"
149 set of functions are used for managing PCI devices.
150 The functions are split into several groups:
151 raw configuration access,
154 device configuration,
156 message signaled interrupts.
157 .Ss Raw Configuration Access
160 function is used to read data from the PCI configuration
167 specifying the size of the access.
171 function is used to write the value
173 to the PCI configuration
180 specifying the size of the access.
183 .Fn pcie_adjust_config
184 function is used to modify the value of a register in the PCI-express
185 capability register set of device
189 specifies a relative offset in the register set with
191 specifying the size of the access.
192 The new value of the register is computed by modifying bits set in
196 Any bits not specified in
199 The previous value of the register is returned.
203 function is used to read the value of a register in the PCI-express
204 capability register set of device
208 specifies a relative offset in the register set with
210 specifying the size of the access.
213 .Fn pcie_write_config
214 function is used to write the value
216 to a register in the PCI-express capability register set of device
220 specifies a relative offset in the register set with
222 specifying the size of the access.
225 Device drivers should only use these functions for functionality that
226 is not available via another
232 function looks up the
234 of a PCI device, given its
241 number actually refers to the number of the device on the bus,
242 which does not necessarily indicate its geographic location
243 in terms of a physical slot.
244 Note that in case the system has multiple PCI domains,
247 function only searches the first one.
248 Actually, it is equivalent to:
249 .Bd -literal -offset indent
250 pci_find_dbsf(0, bus, slot, func);
255 function looks up the
257 of a PCI device, given its
265 number actually refers to the number of the device on the bus,
266 which does not necessarily indicate its geographic location
267 in terms of a physical slot.
271 function looks up the
273 of a PCI device, given its
278 Note that there can be multiple matches for this search; this function
279 only returns the first matching device.
280 .Ss Device Information
283 function is used to locate the first instance of a PCI capability
284 register set for the device
286 The capability to locate is specified by ID via
288 Constant macros of the form
290 for standard capability IDs are defined in
291 .In dev/pci/pcireg.h .
292 If the capability is found, then
294 is set to the offset in configuration space of the capability register set,
298 If the capability is not found or the device does not support capabilities,
304 function is used to locate the first instance of a PCI-express
305 extended capability register set for the device
307 The extended capability to locate is specified by ID via
309 Constant macros of the form
311 for standard extended capability IDs are defined in
312 .In dev/pci/pcireg.h .
313 If the extended capability is found, then
315 is set to the offset in configuration space of the extended capability
319 If the extended capability is not found or the device is not a
326 function is used to locate the first instance of a HyperTransport capability
327 register set for the device
329 The capability to locate is specified by type via
331 Constant macros of the form
333 for standard HyperTransport capability types are defined in
334 .In dev/pci/pcireg.h .
335 If the capability is found, then
337 is set to the offset in configuration space of the capability register set,
341 If the capability is not found or the device is not a HyperTransport device,
346 .Fn pci_find_pcie_root_port
347 function walks up the PCI device hierarchy to locate the PCI-express root
350 If a root port is not found,
351 .Fn pci_find_pcie_root_port
356 .Fn pci_get_vpd_ident
357 function is used to fetch a device's Vital Product Data
362 supports VPD and provides an identifier string,
365 is set to point at a read-only, null-terminated copy of the identifier
368 .Fn pci_get_vpd_ident
370 If the device does not support VPD or does not provide an identifier
373 .Fn pci_get_vpd_ident
377 .Fn pci_get_vpd_readonly
378 function is used to fetch the value of a single VPD read-only keyword
381 The keyword to fetch is identified by the two character string
383 If the device supports VPD and provides a read-only value for the
387 is set to point at a read-only, null-terminated copy of the value,
389 .Fn pci_get_vpd_readonly
391 If the device does not support VPD or does not provide the requested
394 .Fn pci_get_vpd_readonly
396 .Ss Device Configuration
398 .Fn pci_enable_busmaster
399 function enables PCI bus mastering for the device
402 .Dv PCIM_CMD_BUSMASTEREN
407 .Fn pci_disable_busmaster
408 function clears this bit.
412 function enables memory or I/O port address decoding for the device
420 register appropriately.
423 function clears the appropriate bit.
426 argument specifies which resource is affected; this can be either
431 Device drivers should generally not use these routines directly.
432 The PCI bus will enable decoding automatically when a
436 resource is activated via
437 .Xr bus_alloc_resource 9
439 .Xr bus_activate_resource 9 .
442 .Fn pci_get_max_payload
443 function returns the current maximum TLP payload size in bytes for a
447 device is not a PCI-express device,
448 .Fn pci_get_max_payload
452 .Fn pci_get_max_read_req
453 function returns the current maximum read request size in bytes for a
457 device is not a PCI-express device,
458 .Fn pci_get_max_read_req
462 .Fn pci_set_max_read_req
463 sets the PCI-express maximum read request size for
469 .Fn pci_set_max_read_req
470 returns the actual size set in bytes.
473 device is not a PCI-express device,
474 .Fn pci_set_max_read_req
478 .Fn pci_get_powerstate
479 function returns the current power state of the device
481 If the device does not support power management capabilities, then the default
483 .Dv PCI_POWERSTATE_D0
485 The following power states are defined by PCI:
486 .Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN"
487 .It Dv PCI_POWERSTATE_D0
488 State in which device is on and running.
489 It is receiving full power from the system and delivering
490 full functionality to the user.
491 .It Dv PCI_POWERSTATE_D1
492 Class-specific low-power state in which device context may or
494 Busses in this state cannot do anything to the bus, to
495 force devices to lose context.
496 .It Dv PCI_POWERSTATE_D2
497 Class-specific low-power state in which device context may or
499 Attains greater power savings than
500 .Dv PCI_POWERSTATE_D1 .
501 Busses in this state can cause devices to lose some context.
504 be prepared for the bus to be in this state or higher.
505 .It Dv PCI_POWERSTATE_D3
506 State in which the device is off and not running.
507 Device context is lost, and power from the device can
509 .It Dv PCI_POWERSTATE_UNKNOWN
510 State of the device is unknown.
514 .Fn pci_set_powerstate
515 function is used to transition the device
517 to the PCI power state
519 If the device does not support power management capabilities or
520 it does not support the specific power state
522 then the function will fail with
528 .Fn pci_restore_state
529 functions can be used by a device driver to save and restore standard PCI
533 function must be invoked while the device has valid state before
534 .Fn pci_restore_state
536 If the device is not in the fully-powered state
537 .Pq Dv PCI_POWERSTATE_D0
539 .Fn pci_restore_state
541 then the device will be transitioned to
542 .Dv PCI_POWERSTATE_D0
543 before any config registers are restored.
544 .Ss Message Signaled Interrupts
545 Message Signaled Interrupts
548 Enhanced Message Signaled Interrupts
550 are PCI capabilities that provide an alternate method for PCI
551 devices to signal interrupts.
552 The legacy INTx interrupt is available to PCI devices as a
554 resource with a resource ID of zero.
555 MSI and MSI-X interrupts are available to PCI devices as one or more
557 resources with resource IDs greater than zero.
558 A driver must ask the PCI bus to allocate MSI or MSI-X interrupts
563 before it can use MSI or MSI-X
566 A driver is not allowed to use the legacy INTx
568 resource if MSI or MSI-X interrupts have been allocated,
569 and attempts to allocate MSI or MSI-X interrupts will fail if the
570 driver is currently using the legacy INTx
573 A driver is only allowed to use either MSI or MSI-X,
578 function returns the maximum number of MSI messages supported by the
581 If the device does not support MSI,
588 function attempts to allocate
590 MSI messages for the device
594 function may allocate fewer messages than requested for various
595 reasons including requests for more messages than the device
598 or if the system has a shortage of available MSI messages.
601 is set to the number of messages allocated and
606 resources for the allocated messages will be available at consecutive
607 resource IDs beginning with one.
610 is not able to allocate any messages,
612 Note that MSI only supports message counts that are powers of two;
613 requests to allocate a non-power of two count of messages will fail.
617 function is used to release any allocated MSI or MSI-X messages back
621 resources are allocated by the driver or have a configured interrupt
623 this function will fail with
627 function returns zero on success and an error on failure.
631 function returns the maximum number of MSI-X messages supported by the
634 If the device does not support MSI-X,
641 function returns the offset in configuration space of the Base Address Register
643 containing the MSI-X Pending Bit Array (PBA) for device
645 The returned value can be used as the resource ID with
646 .Xr bus_alloc_resource 9
648 .Xr bus_release_resource 9
650 If the device does not support MSI-X,
656 .Fn pci_msix_table_bar
657 function returns the offset in configuration space of the BAR
658 containing the MSI-X vector table for device
660 The returned value can be used as the resource ID with
661 .Xr bus_alloc_resource 9
663 .Xr bus_release_resource 9
665 If the device does not support MSI-X,
667 .Fn pci_msix_table_bar
672 function attempts to allocate
674 MSI-X messages for the device
678 function may allocate fewer messages than requested for various
679 reasons including requests for more messages than the device
682 or if the system has a shortage of available MSI-X messages.
685 is set to the number of messages allocated and
689 the resource ID for each
691 resource identifies the index in the MSI-X table of the
692 corresponding message.
693 A resource ID of one maps to the first index of the MSI-X table;
694 a resource ID two identifies the second index in the table, etc.
699 messages allocated to the first
704 is not able to allocate any messages,
707 MSI-X does not require message counts that are powers of two.
709 The BARs containing the MSI-X vector table and PBA must be
711 .Xr bus_alloc_resource 9
714 and must not be released until after calling
715 .Fn pci_release_msi .
716 Note that the vector table and PBA may be stored in the same BAR or in
721 function examines the
724 to determine the pending status of the MSI-X message at table index
726 If the indicated message is pending,
727 this function returns a non-zero value;
732 to this function will result in undefined behavior.
734 As mentioned in the description of
736 MSI-X messages are initially assigned to the first N table entries.
737 A driver may use a different distribution of available messages to
738 table entries via the
741 Note that this function must be called after a successful call to
743 but before any of the
745 resources are allocated.
748 function returns zero on success,
749 or an error on failure.
756 The array maps directly to the MSI-X table in that the first entry in
757 the array specifies the message used for the first entry in the MSI-X
759 the second entry in the array corresponds to the second entry in the
762 The vector value in each array index can either be zero to indicate
763 that no message should be assigned to the corresponding MSI-X table entry,
764 or it can be a number from one to N
766 where N is the count returned from the previous call to
769 to indicate which of the allocated messages should be assigned to the
770 corresponding MSI-X table entry.
775 each MSI-X table entry with a non-zero vector will have an associated
777 resource whose resource ID corresponds to the table index as described
780 MSI-X table entries that with a vector of zero will not have an
785 if any of the original messages allocated by
787 are not used in the new distribution of messages in the MSI-X table,
788 they will be released automatically.
789 Note that if a driver wishes to use fewer messages than were allocated by
791 the driver must use a single, contiguous range of messages beginning
792 with one in the new distribution.
795 function will fail if this condition is not met.
799 .Xr bus_alloc_resource 9 ,
801 .Xr bus_release_resource 9 ,
802 .Xr bus_setup_intr 9 ,
803 .Xr bus_teardown_intr 9 ,
809 .%B FreeBSD Developers' Handbook
811 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
816 .%B PCI System Architecture
819 .%O ISBN 0-201-30974-2
822 This manual page was written by
823 .An Bruce M Simpson Aq bms@FreeBSD.org
825 .An John Baldwin Aq jhb@FreeBSD.org .
827 The kernel PCI code has a number of references to
829 These do not refer to the geographic location of PCI devices,
830 but to the device number assigned by the combination of the PCI IDSEL
831 mechanism and the platform firmware.
832 This should be taken note of when working with the kernel PCI code.
834 The PCI bus driver should allocate the MSI-X vector table and PBA internally
835 as necessary rather than requiring the caller to do so.