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
26 .\" $FreeBSD: src/share/man/man9/pci.9,v 1.11 2008/02/15 23:56:33 danger Exp $
34 .Nm pci_write_config ,
35 .Nm pci_enable_busmaster ,
36 .Nm pci_disable_busmaster ,
39 .Nm pci_set_powerstate ,
40 .Nm pci_get_powerstate ,
50 .In bus/pci/pci_cfgreg.h
52 .Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width"
54 .Fn pci_enable_busmaster "device_t dev"
56 .Fn pci_disable_busmaster "device_t dev"
58 .Fn pci_enable_io "device_t dev" "int space"
60 .Fn pci_disable_io "device_t dev" "int space"
62 .Fn pci_set_powerstate "device_t dev" "int state"
64 .Fn pci_get_powerstate "device_t dev"
66 .Fn pci_read_config "device_t dev" "int reg" "int width"
68 .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
70 .Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func"
72 .Fn pci_find_device "uint16_t vendor" "uint16_t device"
74 .Fn pci_find_extcap "device_t dev" "int capability" "int *capreg"
78 set of functions are used for managing PCI devices.
82 function is used to read data from the PCI configuration
89 specifying the size of the access.
93 function is used to write the value
95 to the PCI configuration
102 specifying the size of the access.
105 .Fn pci_enable_busmaster
106 function enables PCI bus mastering for the device
109 .Dv PCIM_CMD_BUSMASTEREN
114 .Fn pci_disable_busmaster
115 function clears this bit.
119 function enables memory or I/O port address decoding for the device
127 register appropriately.
130 function clears the appropriate bit.
133 argument specifies which resource is affected; this can be either
140 These functions should be used in preference to manually manipulating
141 the configuration space.
144 .Fn pci_get_powerstate
145 function returns the current ACPI power state of the device
147 If the device does not support power management capabilities, then the default
149 .Dv PCI_POWERSTATE_D0
151 The following power states are defined by ACPI:
152 .Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN"
153 .It Dv PCI_POWERSTATE_D0
154 State in which device is on and running.
155 It is receiving full power from the system and delivering
156 full functionality to the user.
157 .It Dv PCI_POWERSTATE_D1
158 Class-specific low-power state in which device context may or
160 Busses in this state cannot do anything to the bus, to
161 force devices to lose context.
162 .It Dv PCI_POWERSTATE_D2
163 Class-specific low-power state in which device context may or
165 Attains greater power savings than
166 .Dv PCI_POWERSTATE_D1 .
167 Busses in this state can cause devices to lose some context.
170 be prepared for the bus to be in this state or higher.
171 .It Dv PCI_POWERSTATE_D3
172 State in which the device is off and not running.
173 Device context is lost, and power from the device can
175 .It Dv PCI_POWERSTATE_UNKNOWN
176 State of the device is unknown.
180 .Fn pci_set_powerstate
181 function is used to transition the device
183 to the ACPI power state
185 It checks to see if the device is PCI 2.2 compliant.
187 capabilities pointer to determine which power states the device supports.
188 If the device does not have power management capabilities, the default state
190 .Dv PCI_POWERSTATE_D0
195 function looks up the
197 of a PCI device, given its
204 number actually refers to the number of the device on the bus,
205 which does not necessarily indicate its geographic location
206 in terms of a physical slot.
207 Note that in case the system has multiple PCI domains,
210 function only searches the first one.
211 Actually, it is equivalent to:
212 .Bd -literal -offset indent
213 pci_find_dbsf(0, bus, slot, func);
218 function looks up the
220 of a PCI device, given its
228 number actually refers to the number of the device on the bus,
229 which does not necessarily indicate its geographic location
230 in terms of a physical slot.
234 function looks up the
236 of a PCI device, given its
241 Note that there can be multiple matches for this search; this function
242 only returns the first matching device.
246 function is used to locate the first instance of a PCI-express
247 extended capability register set for the device
249 The extended capability to locate is specified by ID via
251 Constant macros of the form
253 for standard extended capability IDs are defined in
254 .In bus/pci/pcireg.h .
255 If the extended capability is found, then
257 is set to the offset in configuration space of the extended capability
260 Return the offset in configuration space of the requested extended
261 capability entry or 0 if the specified capability was not found.
262 .Sh IMPLEMENTATION NOTES
265 type varies according to the size of the PCI bus address
266 space on the target architecture.
270 .Xr bus_alloc_resource 9 ,
272 .Xr bus_release_resource 9 ,
273 .Xr bus_setup_intr 9 ,
274 .Xr bus_teardown_intr 9 ,
280 .%B FreeBSD Developers' Handbook
282 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
287 .%B PCI System Architecture
290 .%O ISBN 0-201-30974-2
293 This manual page was written by
294 .An Bruce M Simpson Aq Mt bms@FreeBSD.org .
296 The kernel PCI code has a number of references to
298 These do not refer to the geographic location of PCI devices,
299 but to the device number assigned by the combination of the PCI IDSEL
300 mechanism and the platform firmware.
301 This should be taken note of when working with the kernel PCI code.