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.\"
| 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: head/share/man/man4/pci.4 70015 2000-12-14 11:52:05Z ru $
| 25.\" $FreeBSD: head/share/man/man4/pci.4 70466 2000-12-29 09:18:45Z ru $
|
26.\"
27.Dd October 24, 1999
28.Dt PCI 4
29.Os FreeBSD
30.Sh NAME
31.Nm pci
32.Nd Generic PCI driver
33.Sh SYNOPSIS
34.Cd device pci
35.Sh DESCRIPTION
36The
37.Nm
38driver provides a way for userland programs to read and write
39.Tn PCI
40configuration registers. It also provides a way for userland programs to
41get a list of all
42.Tn PCI
43devices, or all
44.Tn PCI
45devices that match various patterns.
46.Pp
47Since the
48.Nm
49driver provides a write interface for
50.Tn PCI
51configuration registers, system administrators should exercise caution when
52granting access to the
53.Nm
54device. If used improperly, this driver can allow userland applications to
55crash a machine or cause data loss.
56.Sh KERNEL CONFIGURATION
57It is only necessary to specify one
58.Nm
59controller in the kernel. Additional
60.Tn PCI
61busses are handled automatically as they are encountered.
62.Sh IOCTLS
63The following
64.Xr ioctl 2
65calls are supported by the
66.Nm
67driver. They are defined in the header file
68.Aq Pa sys/pciio.h .
69.Bl -tag -width 012345678901234
70.Pp
71.It PCIOCGETCONF
72This
73.Xr ioctl 2
74takes a
75.Va pci_conf_io
76structure. It allows the user to retrieve information on all
77.Tn PCI
78devices in the system, or on
79.Tn PCI
80devices matching patterns supplied by the user.
81The
82.Va pci_conf_io
83structure consists of a number of fields:
84.Bl -tag -width match_buf_len
85.It pat_buf_len
86The length, in bytes, of the buffer filled with user-supplied patterns.
87.It num_patterns
88The number of user-supplied patterns.
89.It patterns
90Pointer to a buffer filled with user-supplied patterns.
91.Va patterns
92is a pointer to
93.Va num_patterns
94.Va pci_match_conf
95structures. The
96.Va pci_match_conf
97structure consists of the following elements:
98.Bl -tag -width pd_vendor
99.It pc_sel
100.Tn PCI
101bus, slot and function.
102.It pd_name
103.Tn PCI
104device driver name.
105.It pd_unit
106.Tn PCI
107device driver unit number.
108.It pc_vendor
109.Tn PCI
110vendor ID.
111.It pc_device
112.Tn PCI
113device ID.
114.It pc_class
115.Tn PCI
116device class.
117.It flags
118The flags describe which of the fields the kernel should match against.
119A device must match all specified fields in order to be returned. The
120match flags are enumerated in the
121.Va pci_getconf_flags
122structure.
123Hopefully the flag values are obvious enough that they don't need to
124described in detail.
125.El
126.It match_buf_len
127Length of the
128.Va matches
129buffer allocated by the user to hold the results of the
130.Dv PCIOCGETCONF
131query.
132.It num_matches
133Number of matches returned by the kernel.
134.It matches
135Buffer containing matching devices returned by the kernel. The items in
136this buffer are of type
137.Va pci_conf ,
138which consists of the following items:
139.Bl -tag -width pc_subvendor
140.It pc_sel
141.Tn PCI
142bus, slot and function.
143.It pc_hdr
144.Tn PCI
145header type.
146.It pc_subvendor
147.Tn PCI
148subvendor ID.
149.It pc_subdevice
150.Tn PCI
151subdevice ID.
152.It pc_vendor
153.Tn PCI
154vendor ID.
155.It pc_device
156.Tn PCI
157device ID.
158.It pc_class
159.Tn PCI
160device class.
161.It pc_subclass
162.Tn PCI
163device subclass.
164.It pc_progif
165.Tn PCI
166device programming interface.
167.It pc_revid
168.Tn PCI
169revision ID.
170.It pd_name
171Driver name.
172.It pd_unit
173Driver unit number.
174.El
175.It offset
176The offset is passed in by the user to tell the kernel where it should
177start traversing the device list. The value passed out by the kernel
178points to the record immediately after the last one returned. The user may
179pass the value returned by the kernel in subsequent calls to the
180.Dv PCIOCGETCONF
181ioctl. If the user does not intend to use the offset, it must be set to
182zero.
183.It generation
184.Tn PCI
185configuration generation. This value only needs to be set if the offset is
186set. The kernel will compare the current generation number of its internal
187device list to the generation passed in by the user to determine whether
188its device list has changed since the user last called the
189.Dv PCIOCGETCONF
190ioctl. If the device list has changed, a status of
191.Va PCI_GETCONF_LIST_CHANGED
192will be passed back.
193.It status
194The status tells the user the disposition of his request for a device list.
195The possible status values are:
196.Bl -ohang
197.It PCI_GETCONF_LAST_DEVICE
198This means that there are no more devices in the PCI device list after the
199ones returned in the
200.Va matches
201buffer.
202.It PCI_GETCONF_LIST_CHANGED
203This status tells the user that the
204.Tn PCI
205device list has changed since his last call to the
206.Dv PCIOCGETCONF
207ioctl and he must reset the
208.Va offset
209and
210.Va generation
211to zero to start over at the beginning of the list.
212.It PCI_GETCONF_MORE_DEVS
213This tells the user that his buffer was not large enough to hold all of the
214remaining devices in the device list that possibly match his criteria. It
215is possible for this status to be returned, even when none of the remaining
216devices in the list would match the user's criteria.
217.It PCI_GETCONF_ERROR
218This indicates a general error while servicing the user's request. A more
219specific indication of the problem may or may not be printed in the kernel
220message buffer (and by implication, the system console).
221.El
222.El
223.It PCIOCREAD
224This
225.Xr ioctl 2
226reads the
227.Tn PCI
228configuration registers specified by the passed-in
229.Va pci_io
230structure. The
231.Va pci_io
232structure consists of the following fields:
233.Bl -tag -width pi_width
234.It pi_sel
235A
236.Va pcisel
237structure which specifies the bus, slot and function the user would like to
238query.
239.It pi_reg
240The
241.Tn PCI
242configuration register the user would like to access.
243.It pi_width
244The width, in bytes, of the data the user would like to read. This value
245may be either 1, 2, or 4. 3-byte reads and reads larger than 4 bytes are
246not supported.
247.It pi_data
248The data returned by the kernel.
249.El
250.It PCIOCWRITE
251This
252.Xr ioctl 2
253allows users to write to the
254.Tn PCI
255specified in the passed-in
256.Va pci_io
257structure. The
258.Va pci_io
259structure is described above. The limitations on data width described for
260reading registers, above, also apply to writing
261.Tn PCI
262configuration registers.
263.El
264.Sh FILES
| 26.\"
27.Dd October 24, 1999
28.Dt PCI 4
29.Os FreeBSD
30.Sh NAME
31.Nm pci
32.Nd Generic PCI driver
33.Sh SYNOPSIS
34.Cd device pci
35.Sh DESCRIPTION
36The
37.Nm
38driver provides a way for userland programs to read and write
39.Tn PCI
40configuration registers. It also provides a way for userland programs to
41get a list of all
42.Tn PCI
43devices, or all
44.Tn PCI
45devices that match various patterns.
46.Pp
47Since the
48.Nm
49driver provides a write interface for
50.Tn PCI
51configuration registers, system administrators should exercise caution when
52granting access to the
53.Nm
54device. If used improperly, this driver can allow userland applications to
55crash a machine or cause data loss.
56.Sh KERNEL CONFIGURATION
57It is only necessary to specify one
58.Nm
59controller in the kernel. Additional
60.Tn PCI
61busses are handled automatically as they are encountered.
62.Sh IOCTLS
63The following
64.Xr ioctl 2
65calls are supported by the
66.Nm
67driver. They are defined in the header file
68.Aq Pa sys/pciio.h .
69.Bl -tag -width 012345678901234
70.Pp
71.It PCIOCGETCONF
72This
73.Xr ioctl 2
74takes a
75.Va pci_conf_io
76structure. It allows the user to retrieve information on all
77.Tn PCI
78devices in the system, or on
79.Tn PCI
80devices matching patterns supplied by the user.
81The
82.Va pci_conf_io
83structure consists of a number of fields:
84.Bl -tag -width match_buf_len
85.It pat_buf_len
86The length, in bytes, of the buffer filled with user-supplied patterns.
87.It num_patterns
88The number of user-supplied patterns.
89.It patterns
90Pointer to a buffer filled with user-supplied patterns.
91.Va patterns
92is a pointer to
93.Va num_patterns
94.Va pci_match_conf
95structures. The
96.Va pci_match_conf
97structure consists of the following elements:
98.Bl -tag -width pd_vendor
99.It pc_sel
100.Tn PCI
101bus, slot and function.
102.It pd_name
103.Tn PCI
104device driver name.
105.It pd_unit
106.Tn PCI
107device driver unit number.
108.It pc_vendor
109.Tn PCI
110vendor ID.
111.It pc_device
112.Tn PCI
113device ID.
114.It pc_class
115.Tn PCI
116device class.
117.It flags
118The flags describe which of the fields the kernel should match against.
119A device must match all specified fields in order to be returned. The
120match flags are enumerated in the
121.Va pci_getconf_flags
122structure.
123Hopefully the flag values are obvious enough that they don't need to
124described in detail.
125.El
126.It match_buf_len
127Length of the
128.Va matches
129buffer allocated by the user to hold the results of the
130.Dv PCIOCGETCONF
131query.
132.It num_matches
133Number of matches returned by the kernel.
134.It matches
135Buffer containing matching devices returned by the kernel. The items in
136this buffer are of type
137.Va pci_conf ,
138which consists of the following items:
139.Bl -tag -width pc_subvendor
140.It pc_sel
141.Tn PCI
142bus, slot and function.
143.It pc_hdr
144.Tn PCI
145header type.
146.It pc_subvendor
147.Tn PCI
148subvendor ID.
149.It pc_subdevice
150.Tn PCI
151subdevice ID.
152.It pc_vendor
153.Tn PCI
154vendor ID.
155.It pc_device
156.Tn PCI
157device ID.
158.It pc_class
159.Tn PCI
160device class.
161.It pc_subclass
162.Tn PCI
163device subclass.
164.It pc_progif
165.Tn PCI
166device programming interface.
167.It pc_revid
168.Tn PCI
169revision ID.
170.It pd_name
171Driver name.
172.It pd_unit
173Driver unit number.
174.El
175.It offset
176The offset is passed in by the user to tell the kernel where it should
177start traversing the device list. The value passed out by the kernel
178points to the record immediately after the last one returned. The user may
179pass the value returned by the kernel in subsequent calls to the
180.Dv PCIOCGETCONF
181ioctl. If the user does not intend to use the offset, it must be set to
182zero.
183.It generation
184.Tn PCI
185configuration generation. This value only needs to be set if the offset is
186set. The kernel will compare the current generation number of its internal
187device list to the generation passed in by the user to determine whether
188its device list has changed since the user last called the
189.Dv PCIOCGETCONF
190ioctl. If the device list has changed, a status of
191.Va PCI_GETCONF_LIST_CHANGED
192will be passed back.
193.It status
194The status tells the user the disposition of his request for a device list.
195The possible status values are:
196.Bl -ohang
197.It PCI_GETCONF_LAST_DEVICE
198This means that there are no more devices in the PCI device list after the
199ones returned in the
200.Va matches
201buffer.
202.It PCI_GETCONF_LIST_CHANGED
203This status tells the user that the
204.Tn PCI
205device list has changed since his last call to the
206.Dv PCIOCGETCONF
207ioctl and he must reset the
208.Va offset
209and
210.Va generation
211to zero to start over at the beginning of the list.
212.It PCI_GETCONF_MORE_DEVS
213This tells the user that his buffer was not large enough to hold all of the
214remaining devices in the device list that possibly match his criteria. It
215is possible for this status to be returned, even when none of the remaining
216devices in the list would match the user's criteria.
217.It PCI_GETCONF_ERROR
218This indicates a general error while servicing the user's request. A more
219specific indication of the problem may or may not be printed in the kernel
220message buffer (and by implication, the system console).
221.El
222.El
223.It PCIOCREAD
224This
225.Xr ioctl 2
226reads the
227.Tn PCI
228configuration registers specified by the passed-in
229.Va pci_io
230structure. The
231.Va pci_io
232structure consists of the following fields:
233.Bl -tag -width pi_width
234.It pi_sel
235A
236.Va pcisel
237structure which specifies the bus, slot and function the user would like to
238query.
239.It pi_reg
240The
241.Tn PCI
242configuration register the user would like to access.
243.It pi_width
244The width, in bytes, of the data the user would like to read. This value
245may be either 1, 2, or 4. 3-byte reads and reads larger than 4 bytes are
246not supported.
247.It pi_data
248The data returned by the kernel.
249.El
250.It PCIOCWRITE
251This
252.Xr ioctl 2
253allows users to write to the
254.Tn PCI
255specified in the passed-in
256.Va pci_io
257structure. The
258.Va pci_io
259structure is described above. The limitations on data width described for
260reading registers, above, also apply to writing
261.Tn PCI
262configuration registers.
263.El
264.Sh FILES
|
265.Bl -tag -width 01234567890 -compact
| 265.Bl -tag -width /dev/pci -compact
|
266.It Pa /dev/pci
267Character device for the
268.Nm
269driver.
270.El
271.Sh DIAGNOSTICS
272None.
273.Sh SEE ALSO
274.Xr pciconf 8
275.Sh HISTORY
276The
277.Nm
278driver (not the kernel's
279.Tn PCI
280support code) first appeared in
281.Fx 2.2 ,
282and was written by Stefan Esser and Garrett Wollman.
283Support for device listing and matching was re-implemented by
284Kenneth Merry, and first appeared in
285.Fx 3.0 .
286.Sh AUTHORS
287.An Kenneth Merry Aq ken@FreeBSD.ORG
288.Sh BUGS
289It isn't possible for users to specify an accurate offset into the device
290list without calling the
291.Dv PCIOCGETCONF
292at least once, since they have no way of knowing the current generation
293number otherwise. This probably isn't a serious problem, though, since
294users can easily narrow their search by specifying a pattern or patterns
295for the kernel to match against.
| 266.It Pa /dev/pci
267Character device for the
268.Nm
269driver.
270.El
271.Sh DIAGNOSTICS
272None.
273.Sh SEE ALSO
274.Xr pciconf 8
275.Sh HISTORY
276The
277.Nm
278driver (not the kernel's
279.Tn PCI
280support code) first appeared in
281.Fx 2.2 ,
282and was written by Stefan Esser and Garrett Wollman.
283Support for device listing and matching was re-implemented by
284Kenneth Merry, and first appeared in
285.Fx 3.0 .
286.Sh AUTHORS
287.An Kenneth Merry Aq ken@FreeBSD.ORG
288.Sh BUGS
289It isn't possible for users to specify an accurate offset into the device
290list without calling the
291.Dv PCIOCGETCONF
292at least once, since they have no way of knowing the current generation
293number otherwise. This probably isn't a serious problem, though, since
294users can easily narrow their search by specifying a pattern or patterns
295for the kernel to match against.
|