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_get_max_read_req ,
46 .Nm pci_get_powerstate ,
47 .Nm pci_get_vpd_ident ,
48 .Nm pci_get_vpd_readonly ,
51 .Nm pci_pending_msix ,
55 .Nm pci_restore_state ,
57 .Nm pci_set_max_read_req ,
58 .Nm pci_set_powerstate ,
66 .Fn pci_alloc_msi "device_t dev" "int *count"
68 .Fn pci_alloc_msix "device_t dev" "int *count"
70 .Fn pci_disable_busmaster "device_t dev"
72 .Fn pci_disable_io "device_t dev" "int space"
74 .Fn pci_enable_busmaster "device_t dev"
76 .Fn pci_enable_io "device_t dev" "int space"
78 .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
80 .Fn pci_find_cap "device_t dev" "int capability" "int *capreg"
82 .Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func"
84 .Fn pci_find_device "uint16_t vendor" "uint16_t device"
86 .Fn pci_find_extcap "device_t dev" "int capability" "int *capreg"
88 .Fn pci_find_htcap "device_t dev" "int capability" "int *capreg"
90 .Fn pci_get_max_read_req "device_t dev"
92 .Fn pci_get_powerstate "device_t dev"
94 .Fn pci_get_vpd_ident "device_t dev" "const char **identptr"
96 .Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr"
98 .Fn pci_msi_count "device_t dev"
100 .Fn pci_msix_count "device_t dev"
102 .Fn pci_pending_msix "device_t dev" "u_int index"
104 .Fn pci_read_config "device_t dev" "int reg" "int width"
106 .Fn pci_release_msi "device_t dev"
108 .Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors"
110 .Fn pci_restore_state "device_t dev"
112 .Fn pci_save_state "device_t dev"
114 .Fn pci_set_max_read_req "device_t dev" "int size"
116 .Fn pci_set_powerstate "device_t dev" "int state"
118 .Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width"
122 set of functions are used for managing PCI devices.
123 The functions are split into several groups:
124 raw configuration access,
127 device configuration,
129 message signaled interrupts.
130 .Ss Raw Configuration Access
133 function is used to read data from the PCI configuration
140 specifying the size of the access.
144 function is used to write the value
146 to the PCI configuration
153 specifying the size of the access.
156 Device drivers should only use these functions for functionality that
157 is not available via another
163 function looks up the
165 of a PCI device, given its
172 number actually refers to the number of the device on the bus,
173 which does not necessarily indicate its geographic location
174 in terms of a physical slot.
175 Note that in case the system has multiple PCI domains,
178 function only searches the first one.
179 Actually, it is equivalent to:
180 .Bd -literal -offset indent
181 pci_find_dbsf(0, bus, slot, func);
186 function looks up the
188 of a PCI device, given its
196 number actually refers to the number of the device on the bus,
197 which does not necessarily indicate its geographic location
198 in terms of a physical slot.
202 function looks up the
204 of a PCI device, given its
209 Note that there can be multiple matches for this search; this function
210 only returns the first matching device.
211 .Ss Device Information
214 function is used to locate the first instance of a PCI capability
215 register set for the device
217 The capability to locate is specified by ID via
219 Constant macros of the form
221 for standard capability IDs are defined in
222 .In dev/pci/pcireg.h .
223 If the capability is found, then
225 is set to the offset in configuration space of the capability register set,
229 If the capability is not found or the device does not support capabilities,
235 function is used to locate the first instance of a PCI-express
236 extended capability register set for the device
238 The extended capability to locate is specified by ID via
240 Constant macros of the form
242 for standard extended capability IDs are defined in
243 .In dev/pci/pcireg.h .
244 If the extended capability is found, then
246 is set to the offset in configuration space of the extended capability
250 If the extended capability is not found or the device is not a
257 function is used to locate the first instance of a HyperTransport capability
258 register set for the device
260 The capability to locate is specified by type via
262 Constant macros of the form
264 for standard HyperTransport capability types are defined in
265 .In dev/pci/pcireg.h .
266 If the capability is found, then
268 is set to the offset in configuration space of the capability register set,
272 If the capability is not found or the device is not a HyperTransport device,
277 .Fn pci_get_vpd_ident
278 function is used to fetch a device's Vital Product Data
283 supports VPD and provides an identifier string,
286 is set to point at a read-only, null-terminated copy of the identifier
289 .Fn pci_get_vpd_ident
291 If the device does not support VPD or does not provide an identifier
294 .Fn pci_get_vpd_ident
298 .Fn pci_get_vpd_readonly
299 function is used to fetch the value of a single VPD read-only keyword
302 The keyword to fetch is identified by the two character string
304 If the device supports VPD and provides a read-only value for the
308 is set to point at a read-only, null-terminated copy of the value,
310 .Fn pci_get_vpd_readonly
312 If the device does not support VPD or does not provide the requested
315 .Fn pci_get_vpd_readonly
317 .Ss Device Configuration
319 .Fn pci_enable_busmaster
320 function enables PCI bus mastering for the device
323 .Dv PCIM_CMD_BUSMASTEREN
328 .Fn pci_disable_busmaster
329 function clears this bit.
333 function enables memory or I/O port address decoding for the device
341 register appropriately.
344 function clears the appropriate bit.
347 argument specifies which resource is affected; this can be either
352 Device drivers should generally not use these routines directly.
353 The PCI bus will enable decoding automatically when a
357 resource is activated via
358 .Xr bus_alloc_resource 9
360 .Xr bus_activate_resource 9 .
363 .Fn pci_get_max_read_req
364 function returns the current maximum read request size in bytes for a
368 device is not a PCI-express device,
369 .Fn pci_get_max_read_req
373 .Fn pci_set_max_read_req
374 sets the PCI-express maximum read request size for
380 .Fn pci_set_max_read_req
381 returns the actual size set in bytes.
384 device is not a PCI-express device,
385 .Fn pci_set_max_read_req
389 .Fn pci_get_powerstate
390 function returns the current power state of the device
392 If the device does not support power management capabilities, then the default
394 .Dv PCI_POWERSTATE_D0
396 The following power states are defined by PCI:
397 .Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN"
398 .It Dv PCI_POWERSTATE_D0
399 State in which device is on and running.
400 It is receiving full power from the system and delivering
401 full functionality to the user.
402 .It Dv PCI_POWERSTATE_D1
403 Class-specific low-power state in which device context may or
405 Busses in this state cannot do anything to the bus, to
406 force devices to lose context.
407 .It Dv PCI_POWERSTATE_D2
408 Class-specific low-power state in which device context may or
410 Attains greater power savings than
411 .Dv PCI_POWERSTATE_D1 .
412 Busses in this state can cause devices to lose some context.
415 be prepared for the bus to be in this state or higher.
416 .It Dv PCI_POWERSTATE_D3
417 State in which the device is off and not running.
418 Device context is lost, and power from the device can
420 .It Dv PCI_POWERSTATE_UNKNOWN
421 State of the device is unknown.
425 .Fn pci_set_powerstate
426 function is used to transition the device
428 to the PCI power state
430 If the device does not support power management capabilities or
431 it does not support the specific power state
433 then the function will fail with
439 .Fn pci_restore_state
440 functions can be used by a device driver to save and restore standard PCI
444 function must be invoked while the device has valid state before
445 .Fn pci_restore_state
447 If the device is not in the fully-powered state
448 .Pq Dv PCI_POWERSTATE_D0
450 .Fn pci_restore_state
452 then the device will be transitioned to
453 .Dv PCI_POWERSTATE_D0
454 before any config registers are restored.
455 .Ss Message Signaled Interrupts
456 Message Signaled Interrupts
459 Enhanced Message Signaled Interrupts
461 are PCI capabilities that provide an alternate method for PCI
462 devices to signal interrupts.
463 The legacy INTx interrupt is available to PCI devices as a
465 resource with a resource ID of zero.
466 MSI and MSI-X interrupts are available to PCI devices as one or more
468 resources with resource IDs greater than zero.
469 A driver must ask the PCI bus to allocate MSI or MSI-X interrupts
474 before it can use MSI or MSI-X
477 A driver is not allowed to use the legacy INTx
479 resource if MSI or MSI-X interrupts have been allocated,
480 and attempts to allocate MSI or MSI-X interrupts will fail if the
481 driver is currently using the legacy INTx
484 A driver is only allowed to use either MSI or MSI-X,
489 function returns the maximum number of MSI messages supported by the
492 If the device does not support MSI,
499 function attempts to allocate
501 MSI messages for the device
505 function may allocate fewer messages than requested for various
506 reasons including requests for more messages than the device
509 or if the system has a shortage of available MSI messages.
512 is set to the number of messages allocated and
517 resources for the allocated messages will be available at consecutive
518 resource IDs beginning with one.
521 is not able to allocate any messages,
523 Note that MSI only supports message counts that are powers of two;
524 requests to allocate a non-power of two count of messages will fail.
528 function is used to release any allocated MSI or MSI-X messages back
532 resources are allocated by the driver or have a configured interrupt
534 this function will fail with
538 function returns zero on success and an error on failure.
542 function returns the maximum number of MSI-X messages supported by the
545 If the device does not support MSI-X,
552 function attempts to allocate
554 MSI-X messages for the device
558 function may allocate fewer messages than requested for various
559 reasons including requests for more messages than the device
562 or if the system has a shortage of available MSI-X messages.
565 is set to the number of messages allocated and
569 the resource ID for each
571 resource identifies the index in the MSI-X table of the
572 corresponding message.
573 A resource ID of one maps to the first index of the MSI-X table;
574 a resource ID two identifies the second index in the table, etc.
579 messages allocated to the first
584 is not able to allocate any messages,
587 MSI-X does not require message counts that are powers of two.
591 function examines the
593 device's Pending Bit Array
595 to determine the pending status of the MSI-X message at table index
597 If the indicated message is pending,
598 this function returns a non-zero value;
603 to this function will result in undefined behavior.
605 As mentioned in the description of
607 MSI-X messages are initially assigned to the first N table entries.
608 A driver may use a different distribution of available messages to
609 table entries via the
612 Note that this function must be called after a successful call to
614 but before any of the
616 resources are allocated.
619 function returns zero on success,
620 or an error on failure.
627 The array maps directly to the MSI-X table in that the first entry in
628 the array specifies the message used for the first entry in the MSI-X
630 the second entry in the array corresponds to the second entry in the
633 The vector value in each array index can either be zero to indicate
634 that no message should be assigned to the corresponding MSI-X table entry,
635 or it can be a number from one to N
637 where N is the count returned from the previous call to
640 to indicate which of the allocated messages should be assigned to the
641 corresponding MSI-X table entry.
646 each MSI-X table entry with a non-zero vector will have an associated
648 resource whose resource ID corresponds to the table index as described
651 MSI-X table entries that with a vector of zero will not have an
656 if any of the original messages allocated by
658 are not used in the new distribution of messages in the MSI-X table,
659 they will be released automatically.
660 Note that if a driver wishes to use fewer messages than were allocated by
662 the driver must use a single, contiguous range of messages beginning
663 with one in the new distribution.
666 function will fail if this condition is not met.
667 .Sh IMPLEMENTATION NOTES
670 type varies according to the size of the PCI bus address
671 space on the target architecture.
675 .Xr bus_alloc_resource 9 ,
677 .Xr bus_release_resource 9 ,
678 .Xr bus_setup_intr 9 ,
679 .Xr bus_teardown_intr 9 ,
685 .%B FreeBSD Developers' Handbook
687 .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
692 .%B PCI System Architecture
695 .%O ISBN 0-201-30974-2
698 This manual page was written by
699 .An Bruce M Simpson Aq bms@FreeBSD.org
701 .An John Baldwin Aq jhb@FreeBSD.org .
703 The kernel PCI code has a number of references to
705 These do not refer to the geographic location of PCI devices,
706 but to the device number assigned by the combination of the PCI IDSEL
707 mechanism and the platform firmware.
708 This should be taken note of when working with the kernel PCI code.