diff options
author | ken <ken@FreeBSD.org> | 1999-12-08 17:44:04 +0000 |
---|---|---|
committer | ken <ken@FreeBSD.org> | 1999-12-08 17:44:04 +0000 |
commit | cdf669dd0c4c5349e23a6a7b332274e7ce22ed95 (patch) | |
tree | 6f72060e6e960edfc33f6b93c4adb3a488dd32bf /share/man/man4/pci.4 | |
parent | 9c42a64866402347e4236cd8093f94f654bae318 (diff) | |
download | FreeBSD-src-cdf669dd0c4c5349e23a6a7b332274e7ce22ed95.zip FreeBSD-src-cdf669dd0c4c5349e23a6a7b332274e7ce22ed95.tar.gz |
[ repository copy of sys/pci/pci_ioctl.h to sys/sys/pciio.h happened in the
background ]
Rename sys/pci/pci_ioctl.h to sys/sys/pciio.h to make it easier for
userland programs to use this interface. Reformat the file, and add a
BSD-style copyright to it.
Add a new man page for pci(4). The PCIOCGETCONF, PCIOCREAD, and PCIOCWRITE
ioctls are documented, but the PCIOCATTACHED ioctl is not documented
because it is not implemented.
Change includes of <pci/pci_ioctl.h> to <sys/pciio.h> or remove them
altogether. In many cases, pci_ioctl.h was unused.
Reviewed by: steve
Diffstat (limited to 'share/man/man4/pci.4')
-rw-r--r-- | share/man/man4/pci.4 | 295 |
1 files changed, 295 insertions, 0 deletions
diff --git a/share/man/man4/pci.4 b/share/man/man4/pci.4 new file mode 100644 index 0000000..8f5ceed --- /dev/null +++ b/share/man/man4/pci.4 @@ -0,0 +1,295 @@ +.\" +.\" 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 October 24, 1999 +.Dt PCI 4 +.Os FreeBSD 4.0 +.Sh NAME +.Nm pci +.Nd Generic PCI driver +.Sh SYNOPSYIS +.Cd controller pci0 +.Sh DESCRIPTION +The +.Nm pci +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 pci +driver provides a write interface for +.Tn PCI +configuration registers, system administrators should exercise caution when +granting access to the +.Nm pci +device. If used improperly, this driver can allow userland applications to +crash a machine or cause data loss. +.Sh KERNEL CONFIGURATION +It is only necessary to specify one +.Nm pci +controller in the kernel. Additional +.Tn PCI +busses are handled automatically as they are encountered. +.Sh IOCTLS +The following +.Xr ioctl 2 +calls are supported by the +.Nm pci +driver. They are defined in the header file +.Aq Pa 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 +.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 +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 don't 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 +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. A more +specific indication of the problem may or may not be printed in the kernel +message buffer (and by implication, the system console). +.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 bus, slot and function the user would like to +query. +.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. +.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 01234567890 -compact +.It Pa /dev/pci +Character device for the +.Nm pci +driver. +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr pciconf 8 +.Sh HISTORY +The +.Nm pci +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 isn't 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 isn't a serious problem, though, since +users can easily narrow their search by specifying a pattern or patterns +for the kernel to match against. |