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