[ 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

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.