pci.4: Sync with FreeBSD RELENG_7_2.
[dragonfly.git] / share / man / man4 / pci.4
CommitLineData
984263bc
MD
1.\"
2.\" Copyright (c) 1999 Kenneth D. Merry.
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. The name of the author may not be used to endorse or promote products
11.\" derived from this software without specific prior written permission.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: src/share/man/man4/pci.4,v 1.3.2.5 2001/08/17 13:08:39 ru Exp $
db5c5815 26.\" $DragonFly: src/share/man/man4/pci.4,v 1.5 2008/11/13 21:46:03 swildner Exp $
984263bc 27.\"
10c1c28a 28.Dd July 5, 2009
984263bc
MD
29.Dt PCI 4
30.Os
31.Sh NAME
32.Nm pci
33.Nd generic PCI driver
34.Sh SYNOPSIS
35.Cd device pci
36.Sh DESCRIPTION
37The
38.Nm
39driver provides a way for userland programs to read and write
40.Tn PCI
db5c5815
SW
41configuration registers.
42It also provides a way for userland programs to get a list of all
984263bc
MD
43.Tn PCI
44devices, or all
45.Tn PCI
46devices that match various patterns.
47.Pp
48Since the
49.Nm
50driver provides a write interface for
51.Tn PCI
52configuration registers, system administrators should exercise caution when
53granting access to the
54.Nm
db5c5815
SW
55device.
56If used improperly, this driver can allow userland applications to
984263bc
MD
57crash a machine or cause data loss.
58.Sh KERNEL CONFIGURATION
59It is only necessary to specify one
60.Nm
db5c5815
SW
61controller in the kernel.
62Additional
984263bc
MD
63.Tn PCI
64busses are handled automatically as they are encountered.
65.Sh IOCTLS
66The following
67.Xr ioctl 2
68calls are supported by the
69.Nm
db5c5815
SW
70driver.
71They are defined in the header file
44cb301e 72.In sys/pciio.h .
db5c5815
SW
73.Bl -tag -width ".It Dv PCIOCGETCONF"
74.It Dv PCIOCGETCONF
984263bc
MD
75This
76.Xr ioctl 2
77takes a
78.Va pci_conf_io
db5c5815
SW
79structure.
80It allows the user to retrieve information on all
984263bc
MD
81.Tn PCI
82devices in the system, or on
83.Tn PCI
84devices matching patterns supplied by the user.
10c1c28a
SW
85The call may set
86.Va errno
87to any value specified in either
88.Xr copyin 9
89or
90.Xr copyout 9 .
984263bc
MD
91The
92.Va pci_conf_io
93structure consists of a number of fields:
db5c5815
SW
94.Bl -tag -width ".Fa match_buf_len"
95.It Fa pat_buf_len
984263bc 96The length, in bytes, of the buffer filled with user-supplied patterns.
db5c5815 97.It Fa num_patterns
984263bc 98The number of user-supplied patterns.
db5c5815 99.It Fa patterns
984263bc 100Pointer to a buffer filled with user-supplied patterns.
db5c5815 101.Fa patterns
984263bc 102is a pointer to
10c1c28a 103.Fa num_patterns
db5c5815
SW
104.Vt pci_match_conf
105structures.
106The
107.Vt pci_match_conf
984263bc 108structure consists of the following elements:
db5c5815
SW
109.Bl -tag -width ".Fa pd_vendor"
110.It Fa pc_sel
984263bc 111.Tn PCI
10c1c28a 112domain, bus, slot and function.
db5c5815 113.It Fa pd_name
984263bc
MD
114.Tn PCI
115device driver name.
db5c5815 116.It Fa pd_unit
984263bc
MD
117.Tn PCI
118device driver unit number.
db5c5815 119.It Fa pc_vendor
984263bc
MD
120.Tn PCI
121vendor ID.
db5c5815 122.It Fa pc_device
984263bc
MD
123.Tn PCI
124device ID.
db5c5815 125.It Fa pc_class
984263bc
MD
126.Tn PCI
127device class.
db5c5815 128.It Fa flags
984263bc 129The flags describe which of the fields the kernel should match against.
db5c5815
SW
130A device must match all specified fields in order to be returned.
131The match flags are enumerated in the
132.Vt pci_getconf_flags
984263bc 133structure.
10c1c28a 134Hopefully the flag values are obvious enough that they do not need to
984263bc
MD
135described in detail.
136.El
db5c5815 137.It Fa match_buf_len
984263bc 138Length of the
db5c5815 139.Fa matches
984263bc
MD
140buffer allocated by the user to hold the results of the
141.Dv PCIOCGETCONF
142query.
db5c5815 143.It Fa num_matches
984263bc 144Number of matches returned by the kernel.
db5c5815
SW
145.It Fa matches
146Buffer containing matching devices returned by the kernel.
147The items in this buffer are of type
148.Vt pci_conf ,
984263bc 149which consists of the following items:
db5c5815
SW
150.Bl -tag -width ".Fa pc_subvendor"
151.It Fa pc_sel
984263bc 152.Tn PCI
10c1c28a 153domain, bus, slot and function.
db5c5815 154.It Fa pc_hdr
984263bc
MD
155.Tn PCI
156header type.
db5c5815 157.It Fa pc_subvendor
984263bc
MD
158.Tn PCI
159subvendor ID.
db5c5815 160.It Fa pc_subdevice
984263bc
MD
161.Tn PCI
162subdevice ID.
db5c5815 163.It Fa pc_vendor
984263bc
MD
164.Tn PCI
165vendor ID.
db5c5815 166.It Fa pc_device
984263bc
MD
167.Tn PCI
168device ID.
db5c5815 169.It Fa pc_class
984263bc
MD
170.Tn PCI
171device class.
db5c5815 172.It Fa pc_subclass
984263bc
MD
173.Tn PCI
174device subclass.
db5c5815 175.It Fa pc_progif
984263bc
MD
176.Tn PCI
177device programming interface.
db5c5815 178.It Fa pc_revid
984263bc
MD
179.Tn PCI
180revision ID.
db5c5815 181.It Fa pd_name
984263bc 182Driver name.
db5c5815 183.It Fa pd_unit
984263bc
MD
184Driver unit number.
185.El
db5c5815 186.It Fa offset
984263bc 187The offset is passed in by the user to tell the kernel where it should
db5c5815
SW
188start traversing the device list.
189The value passed out by the kernel
190points to the record immediately after the last one returned.
191The user may
984263bc
MD
192pass the value returned by the kernel in subsequent calls to the
193.Dv PCIOCGETCONF
db5c5815
SW
194ioctl.
195If the user does not intend to use the offset, it must be set to zero.
196.It Fa generation
984263bc 197.Tn PCI
db5c5815
SW
198configuration generation.
199This value only needs to be set if the offset is set.
200The kernel will compare the current generation number of its internal
984263bc
MD
201device list to the generation passed in by the user to determine whether
202its device list has changed since the user last called the
203.Dv PCIOCGETCONF
db5c5815
SW
204ioctl.
205If the device list has changed, a status of
206.Dv PCI_GETCONF_LIST_CHANGED
984263bc 207will be passed back.
db5c5815 208.It Fa status
984263bc
MD
209The status tells the user the disposition of his request for a device list.
210The possible status values are:
211.Bl -ohang
db5c5815 212.It Dv PCI_GETCONF_LAST_DEVICE
984263bc
MD
213This means that there are no more devices in the PCI device list after the
214ones returned in the
db5c5815 215.Fa matches
984263bc 216buffer.
db5c5815 217.It Dv PCI_GETCONF_LIST_CHANGED
984263bc
MD
218This status tells the user that the
219.Tn PCI
220device list has changed since his last call to the
221.Dv PCIOCGETCONF
222ioctl and he must reset the
db5c5815 223.Fa offset
984263bc 224and
db5c5815 225.Fa generation
984263bc 226to zero to start over at the beginning of the list.
db5c5815 227.It Dv PCI_GETCONF_MORE_DEVS
984263bc 228This tells the user that his buffer was not large enough to hold all of the
db5c5815
SW
229remaining devices in the device list that possibly match his criteria.
230It is possible for this status to be returned, even when none of the remaining
984263bc 231devices in the list would match the user's criteria.
db5c5815
SW
232.It Dv PCI_GETCONF_ERROR
233This indicates a general error while servicing the user's request.
10c1c28a
SW
234If the
235.Fa pat_buf_len
236is not equal to
237.Fa num_patterns
238times
239.Fn sizeof "struct pci_match_conf" ,
240.Va errno
241will be set to
242.Er EINVAL .
984263bc
MD
243.El
244.El
db5c5815 245.It Dv PCIOCREAD
984263bc
MD
246This
247.Xr ioctl 2
248reads the
249.Tn PCI
250configuration registers specified by the passed-in
db5c5815
SW
251.Vt pci_io
252structure.
253The
254.Vt pci_io
984263bc 255structure consists of the following fields:
db5c5815
SW
256.Bl -tag -width ".Fa pi_width"
257.It Fa pi_sel
984263bc 258A
db5c5815 259.Vt pcisel
10c1c28a
SW
260structure which specifies the domain, bus, slot and function the user would
261like to query.
262If the specific bus is not found,
263.Va errno
264will be set to
265.Er ENODEV
266and -1 returned from the ioctl.
db5c5815 267.It Fa pi_reg
984263bc
MD
268The
269.Tn PCI
270configuration register the user would like to access.
db5c5815
SW
271.It Fa pi_width
272The width, in bytes, of the data the user would like to read.
273This value may be either 1, 2, or 4.
2743-byte reads and reads larger than 4 bytes are not supported.
10c1c28a
SW
275If an invalid width is passed,
276.Va errno
277will be set to
278.Er EINVAL .
db5c5815 279.It Fa pi_data
984263bc
MD
280The data returned by the kernel.
281.El
db5c5815 282.It Dv PCIOCWRITE
984263bc
MD
283This
284.Xr ioctl 2
285allows users to write to the
286.Tn PCI
287specified in the passed-in
db5c5815
SW
288.Vt pci_io
289structure.
290The
291.Vt pci_io
292structure is described above.
293The limitations on data width described for
984263bc
MD
294reading registers, above, also apply to writing
295.Tn PCI
296configuration registers.
297.El
298.Sh FILES
299.Bl -tag -width /dev/pci -compact
300.It Pa /dev/pci
301Character device for the
302.Nm
303driver.
304.El
984263bc
MD
305.Sh SEE ALSO
306.Xr pciconf 8
307.Sh HISTORY
308The
309.Nm
310driver (not the kernel's
311.Tn PCI
312support code) first appeared in
313.Fx 2.2 ,
314and was written by Stefan Esser and Garrett Wollman.
315Support for device listing and matching was re-implemented by
316Kenneth Merry, and first appeared in
317.Fx 3.0 .
318.Sh AUTHORS
319.An Kenneth Merry Aq ken@FreeBSD.org
320.Sh BUGS
10c1c28a 321It is not possible for users to specify an accurate offset into the device
984263bc
MD
322list without calling the
323.Dv PCIOCGETCONF
324at least once, since they have no way of knowing the current generation
db5c5815 325number otherwise.
10c1c28a 326This probably is not a serious problem, though, since
984263bc
MD
327users can easily narrow their search by specifying a pattern or patterns
328for the kernel to match against.