diff options
Diffstat (limited to 'share/man/man4/pci.4')
| -rw-r--r-- | share/man/man4/pci.4 | 344 |
1 files changed, 344 insertions, 0 deletions
diff --git a/share/man/man4/pci.4 b/share/man/man4/pci.4 new file mode 100644 index 000000000000..6671f0bb7bf0 --- /dev/null +++ b/share/man/man4/pci.4 @@ -0,0 +1,344 @@ +.\" +.\" Copyright (c) 1999 Kenneth D. Merry. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 3, 2008 +.Dt PCI 4 +.Os +.Sh NAME +.Nm pci +.Nd generic PCI driver +.Sh SYNOPSIS +.Cd device pci +.Sh DESCRIPTION +The +.Nm +driver provides a way for userland programs to read and write +.Tn PCI +configuration registers. +It also provides a way for userland programs to get a list of all +.Tn PCI +devices, or all +.Tn PCI +devices that match various patterns. +.Pp +Since the +.Nm +driver provides a write interface for +.Tn PCI +configuration registers, system administrators should exercise caution when +granting access to the +.Nm +device. +If used improperly, this driver can allow userland applications to +crash a machine or cause data loss. +.Pp +The +.Nm +driver implements the +.Tn PCI +bus in the kernel. +It enumerates any devices on the +.Tn PCI +bus and gives +.Tn PCI +client drivers the chance to attach to them. +It assigns resources to children, when the BIOS does not. +It takes care of routing interrupts when necessary. +It reprobes the unattached +.Tn PCI +children when +.Tn PCI +client drivers are dynamically +loaded at runtime. +.Sh KERNEL CONFIGURATION +The +.Nm +device is included in the kernel as described in the SYNOPSIS section. +The +.Nm +driver cannot be built as a +.Xr kld 4 . +.Sh IOCTLS +The following +.Xr ioctl 2 +calls are supported by the +.Nm +driver. +They are defined in the header file +.In sys/pciio.h . +.Bl -tag -width 012345678901234 +.Pp +.It PCIOCGETCONF +This +.Xr ioctl 2 +takes a +.Va pci_conf_io +structure. +It allows the user to retrieve information on all +.Tn PCI +devices in the system, or on +.Tn PCI +devices matching patterns supplied by the user. +The call may set +.Va errno +to any value specified in either +.Xr copyin 9 +or +.Xr copyout 9 . +The +.Va pci_conf_io +structure consists of a number of fields: +.Bl -tag -width match_buf_len +.It pat_buf_len +The length, in bytes, of the buffer filled with user-supplied patterns. +.It num_patterns +The number of user-supplied patterns. +.It patterns +Pointer to a buffer filled with user-supplied patterns. +.Va patterns +is a pointer to +.Va num_patterns +.Va pci_match_conf +structures. +The +.Va pci_match_conf +structure consists of the following elements: +.Bl -tag -width pd_vendor +.It pc_sel +.Tn PCI +domain, bus, slot and function. +.It pd_name +.Tn PCI +device driver name. +.It pd_unit +.Tn PCI +device driver unit number. +.It pc_vendor +.Tn PCI +vendor ID. +.It pc_device +.Tn PCI +device ID. +.It pc_class +.Tn PCI +device class. +.It flags +The flags describe which of the fields the kernel should match against. +A device must match all specified fields in order to be returned. +The match flags are enumerated in the +.Va pci_getconf_flags +structure. +Hopefully the flag values are obvious enough that they do not need to +described in detail. +.El +.It match_buf_len +Length of the +.Va matches +buffer allocated by the user to hold the results of the +.Dv PCIOCGETCONF +query. +.It num_matches +Number of matches returned by the kernel. +.It matches +Buffer containing matching devices returned by the kernel. +The items in this buffer are of type +.Va pci_conf , +which consists of the following items: +.Bl -tag -width pc_subvendor +.It pc_sel +.Tn PCI +domain, bus, slot and function. +.It pc_hdr +.Tn PCI +header type. +.It pc_subvendor +.Tn PCI +subvendor ID. +.It pc_subdevice +.Tn PCI +subdevice ID. +.It pc_vendor +.Tn PCI +vendor ID. +.It pc_device +.Tn PCI +device ID. +.It pc_class +.Tn PCI +device class. +.It pc_subclass +.Tn PCI +device subclass. +.It pc_progif +.Tn PCI +device programming interface. +.It pc_revid +.Tn PCI +revision ID. +.It pd_name +Driver name. +.It pd_unit +Driver unit number. +.El +.It offset +The offset is passed in by the user to tell the kernel where it should +start traversing the device list. +The value passed out by the kernel +points to the record immediately after the last one returned. +The user may +pass the value returned by the kernel in subsequent calls to the +.Dv PCIOCGETCONF +ioctl. +If the user does not intend to use the offset, it must be set to zero. +.It generation +.Tn PCI +configuration generation. +This value only needs to be set if the offset is set. +The kernel will compare the current generation number of its internal +device list to the generation passed in by the user to determine whether +its device list has changed since the user last called the +.Dv PCIOCGETCONF +ioctl. +If the device list has changed, a status of +.Va PCI_GETCONF_LIST_CHANGED +will be passed back. +.It status +The status tells the user the disposition of his request for a device list. +The possible status values are: +.Bl -ohang +.It PCI_GETCONF_LAST_DEVICE +This means that there are no more devices in the PCI device list after the +ones returned in the +.Va matches +buffer. +.It PCI_GETCONF_LIST_CHANGED +This status tells the user that the +.Tn PCI +device list has changed since his last call to the +.Dv PCIOCGETCONF +ioctl and he must reset the +.Va offset +and +.Va generation +to zero to start over at the beginning of the list. +.It PCI_GETCONF_MORE_DEVS +This tells the user that his buffer was not large enough to hold all of the +remaining devices in the device list that possibly match his criteria. +It is possible for this status to be returned, even when none of the remaining +devices in the list would match the user's criteria. +.It PCI_GETCONF_ERROR +This indicates a general error while servicing the user's request. +If the +.Va pat_buf_len +is not equal to +.Va num_patterns +times +.Fn sizeof "struct pci_match_conf" , +.Va errno +will be set to +.Er EINVAL . +.El +.El +.It PCIOCREAD +This +.Xr ioctl 2 +reads the +.Tn PCI +configuration registers specified by the passed-in +.Va pci_io +structure. +The +.Va pci_io +structure consists of the following fields: +.Bl -tag -width pi_width +.It pi_sel +A +.Va pcisel +structure which specifies the domain, bus, slot and function the user would +like to query. +If the specific bus is not found, errno will be set to ENODEV and -1 returned +from the ioctl. +.It pi_reg +The +.Tn PCI +configuration register the user would like to access. +.It pi_width +The width, in bytes, of the data the user would like to read. +This value +may be either 1, 2, or 4. +3-byte reads and reads larger than 4 bytes are +not supported. +If an invalid width is passed, errno will be set to EINVAL. +.It pi_data +The data returned by the kernel. +.El +.It PCIOCWRITE +This +.Xr ioctl 2 +allows users to write to the +.Tn PCI +specified in the passed-in +.Va pci_io +structure. +The +.Va pci_io +structure is described above. +The limitations on data width described for +reading registers, above, also apply to writing +.Tn PCI +configuration registers. +.El +.Sh FILES +.Bl -tag -width /dev/pci -compact +.It Pa /dev/pci +Character device for the +.Nm +driver. +.El +.Sh SEE ALSO +.Xr pciconf 8 +.Sh HISTORY +The +.Nm +driver (not the kernel's +.Tn PCI +support code) first appeared in +.Fx 2.2 , +and was written by Stefan Esser and Garrett Wollman. +Support for device listing and matching was re-implemented by +Kenneth Merry, and first appeared in +.Fx 3.0 . +.Sh AUTHORS +.An Kenneth Merry Aq ken@FreeBSD.org +.Sh BUGS +It is not possible for users to specify an accurate offset into the device +list without calling the +.Dv PCIOCGETCONF +at least once, since they have no way of knowing the current generation +number otherwise. +This probably is not a serious problem, though, since +users can easily narrow their search by specifying a pattern or patterns +for the kernel to match against. |