345 lines
8.4 KiB
Groff
345 lines
8.4 KiB
Groff
.\"
|
|
.\" 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.
|