xref: /freebsd/share/man/man4/pci.4 (revision 0ade47aed66312df82c49f1dfa325a67a7dcbbe6)
164ae346bSKenneth D. Merry.\"
264ae346bSKenneth D. Merry.\" Copyright (c) 1999 Kenneth D. Merry.
364ae346bSKenneth D. Merry.\" All rights reserved.
464ae346bSKenneth D. Merry.\"
564ae346bSKenneth D. Merry.\" Redistribution and use in source and binary forms, with or without
664ae346bSKenneth D. Merry.\" modification, are permitted provided that the following conditions
764ae346bSKenneth D. Merry.\" are met:
864ae346bSKenneth D. Merry.\" 1. Redistributions of source code must retain the above copyright
964ae346bSKenneth D. Merry.\"    notice, this list of conditions and the following disclaimer.
1064ae346bSKenneth D. Merry.\" 2. The name of the author may not be used to endorse or promote products
1164ae346bSKenneth D. Merry.\"    derived from this software without specific prior written permission.
1264ae346bSKenneth D. Merry.\"
1364ae346bSKenneth D. Merry.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
1464ae346bSKenneth D. Merry.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1564ae346bSKenneth D. Merry.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1664ae346bSKenneth D. Merry.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
1764ae346bSKenneth D. Merry.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
1864ae346bSKenneth D. Merry.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
1964ae346bSKenneth D. Merry.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
2064ae346bSKenneth D. Merry.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
2164ae346bSKenneth D. Merry.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
2264ae346bSKenneth D. Merry.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
2364ae346bSKenneth D. Merry.\" SUCH DAMAGE.
2464ae346bSKenneth D. Merry.\"
2564ae346bSKenneth D. Merry.\" $FreeBSD$
2664ae346bSKenneth D. Merry.\"
270ade47aeSWarner Losh.Dd January 3, 2008
2864ae346bSKenneth D. Merry.Dt PCI 4
293d45e180SRuslan Ermilov.Os
3064ae346bSKenneth D. Merry.Sh NAME
3164ae346bSKenneth D. Merry.Nm pci
32eb083802SRuslan Ermilov.Nd generic PCI driver
33251c176fSRuslan Ermilov.Sh SYNOPSIS
346b713d58SJeroen Ruigrok van der Werven.Cd device pci
3564ae346bSKenneth D. Merry.Sh DESCRIPTION
3664ae346bSKenneth D. MerryThe
374b66483fSRuslan Ermilov.Nm
3864ae346bSKenneth D. Merrydriver provides a way for userland programs to read and write
3964ae346bSKenneth D. Merry.Tn PCI
40b5e7e999SRuslan Ermilovconfiguration registers.
41b5e7e999SRuslan ErmilovIt also provides a way for userland programs to get a list of all
4264ae346bSKenneth D. Merry.Tn PCI
4364ae346bSKenneth D. Merrydevices, or all
4464ae346bSKenneth D. Merry.Tn PCI
4564ae346bSKenneth D. Merrydevices that match various patterns.
4664ae346bSKenneth D. Merry.Pp
4764ae346bSKenneth D. MerrySince the
484b66483fSRuslan Ermilov.Nm
4964ae346bSKenneth D. Merrydriver provides a write interface for
5064ae346bSKenneth D. Merry.Tn PCI
5164ae346bSKenneth D. Merryconfiguration registers, system administrators should exercise caution when
5264ae346bSKenneth D. Merrygranting access to the
534b66483fSRuslan Ermilov.Nm
54b5e7e999SRuslan Ermilovdevice.
55b5e7e999SRuslan ErmilovIf used improperly, this driver can allow userland applications to
5664ae346bSKenneth D. Merrycrash a machine or cause data loss.
570ade47aeSWarner Losh.Pp
580ade47aeSWarner LoshThe
594b66483fSRuslan Ermilov.Nm
600ade47aeSWarner Loshdriver implements the pci bus in the kernel.
610ade47aeSWarner LoshIt enumerates and devices on the pci bus and gives pci client drivers the
620ade47aeSWarner Loshchance to attach to them.
630ade47aeSWarner LoshIt assigns resources to children, when the BIOS doesn't.
640ade47aeSWarner LoshIt takes care of routing interrupts when necessary.
650ade47aeSWarner LoshIt reprobes the unattached pci children when pci client drivers are dynamically
660ade47aeSWarner Loshloaded at runtime.
670ade47aeSWarner Losh.Sh KERNEL CONFIGURATION
680ade47aeSWarner LoshThe
690ade47aeSWarner Losh.Nm
700ade47aeSWarner Loshdevice is included in the kernel as described in the SYNOPSIS section.
710ade47aeSWarner LoshThe pci driver cannot be built as a kld.
7264ae346bSKenneth D. Merry.Sh IOCTLS
7364ae346bSKenneth D. MerryThe following
7464ae346bSKenneth D. Merry.Xr ioctl 2
7564ae346bSKenneth D. Merrycalls are supported by the
764b66483fSRuslan Ermilov.Nm
77b5e7e999SRuslan Ermilovdriver.
78b5e7e999SRuslan ErmilovThey are defined in the header file
79fe08efe6SRuslan Ermilov.In sys/pciio.h .
8064ae346bSKenneth D. Merry.Bl -tag -width 012345678901234
8164ae346bSKenneth D. Merry.Pp
8264ae346bSKenneth D. Merry.It PCIOCGETCONF
8364ae346bSKenneth D. MerryThis
8464ae346bSKenneth D. Merry.Xr ioctl 2
8564ae346bSKenneth D. Merrytakes a
8664ae346bSKenneth D. Merry.Va pci_conf_io
87b5e7e999SRuslan Ermilovstructure.
88b5e7e999SRuslan ErmilovIt allows the user to retrieve information on all
8964ae346bSKenneth D. Merry.Tn PCI
9064ae346bSKenneth D. Merrydevices in the system, or on
9164ae346bSKenneth D. Merry.Tn PCI
925203edcdSRuslan Ermilovdevices matching patterns supplied by the user.
935203edcdSRuslan ErmilovThe call may set
9407e3ed79SJohn-Mark Gurney.Va errno
9507e3ed79SJohn-Mark Gurneyto any value specified in either
9607e3ed79SJohn-Mark Gurney.Xr copyin 9
9707e3ed79SJohn-Mark Gurneyor
9807e3ed79SJohn-Mark Gurney.Xr copyout 9 .
9964ae346bSKenneth D. MerryThe
10064ae346bSKenneth D. Merry.Va pci_conf_io
10164ae346bSKenneth D. Merrystructure consists of a number of fields:
10264ae346bSKenneth D. Merry.Bl -tag -width match_buf_len
10364ae346bSKenneth D. Merry.It pat_buf_len
10464ae346bSKenneth D. MerryThe length, in bytes, of the buffer filled with user-supplied patterns.
10564ae346bSKenneth D. Merry.It num_patterns
10664ae346bSKenneth D. MerryThe number of user-supplied patterns.
10764ae346bSKenneth D. Merry.It patterns
10864ae346bSKenneth D. MerryPointer to a buffer filled with user-supplied patterns.
10964ae346bSKenneth D. Merry.Va patterns
11064ae346bSKenneth D. Merryis a pointer to
11164ae346bSKenneth D. Merry.Va num_patterns
11264ae346bSKenneth D. Merry.Va pci_match_conf
1135203edcdSRuslan Ermilovstructures.
1145203edcdSRuslan ErmilovThe
11564ae346bSKenneth D. Merry.Va pci_match_conf
11664ae346bSKenneth D. Merrystructure consists of the following elements:
11764ae346bSKenneth D. Merry.Bl -tag -width pd_vendor
11864ae346bSKenneth D. Merry.It pc_sel
11964ae346bSKenneth D. Merry.Tn PCI
12055aaf894SMarius Strobldomain, bus, slot and function.
12164ae346bSKenneth D. Merry.It pd_name
12264ae346bSKenneth D. Merry.Tn PCI
12364ae346bSKenneth D. Merrydevice driver name.
12464ae346bSKenneth D. Merry.It pd_unit
12564ae346bSKenneth D. Merry.Tn PCI
12664ae346bSKenneth D. Merrydevice driver unit number.
12764ae346bSKenneth D. Merry.It pc_vendor
12864ae346bSKenneth D. Merry.Tn PCI
12964ae346bSKenneth D. Merryvendor ID.
13064ae346bSKenneth D. Merry.It pc_device
13164ae346bSKenneth D. Merry.Tn PCI
13264ae346bSKenneth D. Merrydevice ID.
13364ae346bSKenneth D. Merry.It pc_class
13464ae346bSKenneth D. Merry.Tn PCI
13564ae346bSKenneth D. Merrydevice class.
13664ae346bSKenneth D. Merry.It flags
13764ae346bSKenneth D. MerryThe flags describe which of the fields the kernel should match against.
138b5e7e999SRuslan ErmilovA device must match all specified fields in order to be returned.
139b5e7e999SRuslan ErmilovThe match flags are enumerated in the
14064ae346bSKenneth D. Merry.Va pci_getconf_flags
14164ae346bSKenneth D. Merrystructure.
1420227791bSRuslan ErmilovHopefully the flag values are obvious enough that they do not need to
14364ae346bSKenneth D. Merrydescribed in detail.
14464ae346bSKenneth D. Merry.El
14564ae346bSKenneth D. Merry.It match_buf_len
14664ae346bSKenneth D. MerryLength of the
14764ae346bSKenneth D. Merry.Va matches
14864ae346bSKenneth D. Merrybuffer allocated by the user to hold the results of the
14964ae346bSKenneth D. Merry.Dv PCIOCGETCONF
15064ae346bSKenneth D. Merryquery.
15164ae346bSKenneth D. Merry.It num_matches
15264ae346bSKenneth D. MerryNumber of matches returned by the kernel.
15364ae346bSKenneth D. Merry.It matches
154b5e7e999SRuslan ErmilovBuffer containing matching devices returned by the kernel.
155b5e7e999SRuslan ErmilovThe items in this buffer are of type
15664ae346bSKenneth D. Merry.Va pci_conf ,
15764ae346bSKenneth D. Merrywhich consists of the following items:
15864ae346bSKenneth D. Merry.Bl -tag -width pc_subvendor
15964ae346bSKenneth D. Merry.It pc_sel
16064ae346bSKenneth D. Merry.Tn PCI
16155aaf894SMarius Strobldomain, bus, slot and function.
16264ae346bSKenneth D. Merry.It pc_hdr
16364ae346bSKenneth D. Merry.Tn PCI
16464ae346bSKenneth D. Merryheader type.
16564ae346bSKenneth D. Merry.It pc_subvendor
16664ae346bSKenneth D. Merry.Tn PCI
16764ae346bSKenneth D. Merrysubvendor ID.
16864ae346bSKenneth D. Merry.It pc_subdevice
16964ae346bSKenneth D. Merry.Tn PCI
17064ae346bSKenneth D. Merrysubdevice ID.
17164ae346bSKenneth D. Merry.It pc_vendor
17264ae346bSKenneth D. Merry.Tn PCI
17364ae346bSKenneth D. Merryvendor ID.
17464ae346bSKenneth D. Merry.It pc_device
17564ae346bSKenneth D. Merry.Tn PCI
17664ae346bSKenneth D. Merrydevice ID.
17764ae346bSKenneth D. Merry.It pc_class
17864ae346bSKenneth D. Merry.Tn PCI
17964ae346bSKenneth D. Merrydevice class.
18064ae346bSKenneth D. Merry.It pc_subclass
18164ae346bSKenneth D. Merry.Tn PCI
18264ae346bSKenneth D. Merrydevice subclass.
18364ae346bSKenneth D. Merry.It pc_progif
18464ae346bSKenneth D. Merry.Tn PCI
18564ae346bSKenneth D. Merrydevice programming interface.
18664ae346bSKenneth D. Merry.It pc_revid
18764ae346bSKenneth D. Merry.Tn PCI
18864ae346bSKenneth D. Merryrevision ID.
18964ae346bSKenneth D. Merry.It pd_name
19064ae346bSKenneth D. MerryDriver name.
19164ae346bSKenneth D. Merry.It pd_unit
19264ae346bSKenneth D. MerryDriver unit number.
19364ae346bSKenneth D. Merry.El
19464ae346bSKenneth D. Merry.It offset
19564ae346bSKenneth D. MerryThe offset is passed in by the user to tell the kernel where it should
196b5e7e999SRuslan Ermilovstart traversing the device list.
197b5e7e999SRuslan ErmilovThe value passed out by the kernel
198b5e7e999SRuslan Ermilovpoints to the record immediately after the last one returned.
199b5e7e999SRuslan ErmilovThe user may
20064ae346bSKenneth D. Merrypass the value returned by the kernel in subsequent calls to the
20164ae346bSKenneth D. Merry.Dv PCIOCGETCONF
202b5e7e999SRuslan Ermilovioctl.
203b5e7e999SRuslan ErmilovIf the user does not intend to use the offset, it must be set to zero.
20464ae346bSKenneth D. Merry.It generation
20564ae346bSKenneth D. Merry.Tn PCI
206b5e7e999SRuslan Ermilovconfiguration generation.
207b5e7e999SRuslan ErmilovThis value only needs to be set if the offset is set.
208b5e7e999SRuslan ErmilovThe kernel will compare the current generation number of its internal
20964ae346bSKenneth D. Merrydevice list to the generation passed in by the user to determine whether
21064ae346bSKenneth D. Merryits device list has changed since the user last called the
21164ae346bSKenneth D. Merry.Dv PCIOCGETCONF
212b5e7e999SRuslan Ermilovioctl.
213b5e7e999SRuslan ErmilovIf the device list has changed, a status of
21464ae346bSKenneth D. Merry.Va PCI_GETCONF_LIST_CHANGED
21564ae346bSKenneth D. Merrywill be passed back.
21664ae346bSKenneth D. Merry.It status
21764ae346bSKenneth D. MerryThe status tells the user the disposition of his request for a device list.
21864ae346bSKenneth D. MerryThe possible status values are:
21964ae346bSKenneth D. Merry.Bl -ohang
22064ae346bSKenneth D. Merry.It PCI_GETCONF_LAST_DEVICE
22164ae346bSKenneth D. MerryThis means that there are no more devices in the PCI device list after the
22264ae346bSKenneth D. Merryones returned in the
22364ae346bSKenneth D. Merry.Va matches
22464ae346bSKenneth D. Merrybuffer.
22564ae346bSKenneth D. Merry.It PCI_GETCONF_LIST_CHANGED
22664ae346bSKenneth D. MerryThis status tells the user that the
22764ae346bSKenneth D. Merry.Tn PCI
22864ae346bSKenneth D. Merrydevice list has changed since his last call to the
22964ae346bSKenneth D. Merry.Dv PCIOCGETCONF
23064ae346bSKenneth D. Merryioctl and he must reset the
23164ae346bSKenneth D. Merry.Va offset
23264ae346bSKenneth D. Merryand
23364ae346bSKenneth D. Merry.Va generation
23464ae346bSKenneth D. Merryto zero to start over at the beginning of the list.
23564ae346bSKenneth D. Merry.It PCI_GETCONF_MORE_DEVS
23664ae346bSKenneth D. MerryThis tells the user that his buffer was not large enough to hold all of the
237b5e7e999SRuslan Ermilovremaining devices in the device list that possibly match his criteria.
238b5e7e999SRuslan ErmilovIt is possible for this status to be returned, even when none of the remaining
23964ae346bSKenneth D. Merrydevices in the list would match the user's criteria.
24064ae346bSKenneth D. Merry.It PCI_GETCONF_ERROR
241b5e7e999SRuslan ErmilovThis indicates a general error while servicing the user's request.
242b5e7e999SRuslan ErmilovIf the
24307e3ed79SJohn-Mark Gurney.Va pat_buf_len
24407e3ed79SJohn-Mark Gurneyis not equal to
24507e3ed79SJohn-Mark Gurney.Va num_patterns
24607e3ed79SJohn-Mark Gurneytimes
247b5e7e999SRuslan Ermilov.Fn sizeof "struct pci_match_conf" ,
248b5e7e999SRuslan Ermilov.Va errno
249b5e7e999SRuslan Ermilovwill be set to
250b5e7e999SRuslan Ermilov.Er EINVAL .
25164ae346bSKenneth D. Merry.El
25264ae346bSKenneth D. Merry.El
25364ae346bSKenneth D. Merry.It PCIOCREAD
25464ae346bSKenneth D. MerryThis
25564ae346bSKenneth D. Merry.Xr ioctl 2
25664ae346bSKenneth D. Merryreads the
25764ae346bSKenneth D. Merry.Tn PCI
25864ae346bSKenneth D. Merryconfiguration registers specified by the passed-in
25964ae346bSKenneth D. Merry.Va pci_io
2605203edcdSRuslan Ermilovstructure.
2615203edcdSRuslan ErmilovThe
26264ae346bSKenneth D. Merry.Va pci_io
26364ae346bSKenneth D. Merrystructure consists of the following fields:
26464ae346bSKenneth D. Merry.Bl -tag -width pi_width
26564ae346bSKenneth D. Merry.It pi_sel
26664ae346bSKenneth D. MerryA
26764ae346bSKenneth D. Merry.Va pcisel
26855aaf894SMarius Stroblstructure which specifies the domain, bus, slot and function the user would
26955aaf894SMarius Strobllike to query.
27055aaf894SMarius StroblIf the specific bus is not found, errno will be set to ENODEV and -1 returned
27155aaf894SMarius Stroblfrom the ioctl.
27264ae346bSKenneth D. Merry.It pi_reg
27364ae346bSKenneth D. MerryThe
27464ae346bSKenneth D. Merry.Tn PCI
27564ae346bSKenneth D. Merryconfiguration register the user would like to access.
27664ae346bSKenneth D. Merry.It pi_width
277b5e7e999SRuslan ErmilovThe width, in bytes, of the data the user would like to read.
278b5e7e999SRuslan ErmilovThis value
2795203edcdSRuslan Ermilovmay be either 1, 2, or 4.
2805203edcdSRuslan Ermilov3-byte reads and reads larger than 4 bytes are
2815203edcdSRuslan Ermilovnot supported.
2825203edcdSRuslan ErmilovIf an invalid width is passed, errno will be set to EINVAL.
28364ae346bSKenneth D. Merry.It pi_data
28464ae346bSKenneth D. MerryThe data returned by the kernel.
28564ae346bSKenneth D. Merry.El
28664ae346bSKenneth D. Merry.It PCIOCWRITE
28764ae346bSKenneth D. MerryThis
28864ae346bSKenneth D. Merry.Xr ioctl 2
28964ae346bSKenneth D. Merryallows users to write to the
29064ae346bSKenneth D. Merry.Tn PCI
29164ae346bSKenneth D. Merryspecified in the passed-in
29264ae346bSKenneth D. Merry.Va pci_io
2935203edcdSRuslan Ermilovstructure.
2945203edcdSRuslan ErmilovThe
29564ae346bSKenneth D. Merry.Va pci_io
296b5e7e999SRuslan Ermilovstructure is described above.
297b5e7e999SRuslan ErmilovThe limitations on data width described for
29864ae346bSKenneth D. Merryreading registers, above, also apply to writing
29964ae346bSKenneth D. Merry.Tn PCI
30064ae346bSKenneth D. Merryconfiguration registers.
30164ae346bSKenneth D. Merry.El
30264ae346bSKenneth D. Merry.Sh FILES
3033136363fSRuslan Ermilov.Bl -tag -width /dev/pci -compact
30464ae346bSKenneth D. Merry.It Pa /dev/pci
30564ae346bSKenneth D. MerryCharacter device for the
3064b66483fSRuslan Ermilov.Nm
30764ae346bSKenneth D. Merrydriver.
30864ae346bSKenneth D. Merry.El
30964ae346bSKenneth D. Merry.Sh SEE ALSO
31064ae346bSKenneth D. Merry.Xr pciconf 8
31164ae346bSKenneth D. Merry.Sh HISTORY
31264ae346bSKenneth D. MerryThe
3134b66483fSRuslan Ermilov.Nm
31464ae346bSKenneth D. Merrydriver (not the kernel's
31564ae346bSKenneth D. Merry.Tn PCI
31664ae346bSKenneth D. Merrysupport code) first appeared in
31764ae346bSKenneth D. Merry.Fx 2.2 ,
31864ae346bSKenneth D. Merryand was written by Stefan Esser and Garrett Wollman.
31964ae346bSKenneth D. MerrySupport for device listing and matching was re-implemented by
32064ae346bSKenneth D. MerryKenneth Merry, and first appeared in
32164ae346bSKenneth D. Merry.Fx 3.0 .
32264ae346bSKenneth D. Merry.Sh AUTHORS
323c5e7e03aSRuslan Ermilov.An Kenneth Merry Aq ken@FreeBSD.org
32464ae346bSKenneth D. Merry.Sh BUGS
3250227791bSRuslan ErmilovIt is not possible for users to specify an accurate offset into the device
32664ae346bSKenneth D. Merrylist without calling the
32764ae346bSKenneth D. Merry.Dv PCIOCGETCONF
32864ae346bSKenneth D. Merryat least once, since they have no way of knowing the current generation
329b5e7e999SRuslan Ermilovnumber otherwise.
3300227791bSRuslan ErmilovThis probably is not a serious problem, though, since
33164ae346bSKenneth D. Merryusers can easily narrow their search by specifying a pattern or patterns
33264ae346bSKenneth D. Merryfor the kernel to match against.
333