pci(4)

NAME

pci - generic PCI driver

SYNOPSIS

device pci

DESCRIPTION

The pci driver provides a way for userland programs to read

and write PCI
configuration registers. It also provides a way for user

land programs to
get a list of all PCI devices, or all PCI devices that match

various patterns.

Since the pci driver provides a write interface for PCI con

figuration
registers, system administrators should exercise caution

when granting
access to the pci device. If used improperly, this driver

can allow
userland applications to crash a machine or cause data loss.

KERNEL CONFIGURATION

It is only necessary to specify one pci controller in the

kernel. Additional PCI busses are handled automatically as they are en

countered.

IOCTLS

The following ioctl(2) calls are supported by the pci driv

er. They are
defined in the header file

PCIOCGETCONF This ioctl(2) takes a pci_conf_io struc

ture. It allows

the user to retrieve information on all PCI

devices in
the system, or on PCI devices matching pat

terns supplied
by the user. The call may set errno to any

value specified in either copyin(9) or copyout(9).

The pci_conf_io
structure consists of a number of fields:

pat_buf_len The length, in bytes, of the

buffer

filled with user-supplied

patterns.

num_patterns The number of user-supplied

patterns.

patterns Pointer to a buffer filled

with user-sup

plied patterns. patterns is

a pointer to
num_patterns pci_match_conf

structures.
The pci_match_conf structure

consists of
the following elements:

pc_sel PCI bus, slot and

function.

pd_name PCI device driver

name.

pd_unit PCI device driver

unit number.

pc_vendor PCI vendor ID.

pc_device PCI device ID.

pc_class PCI device class.

flags The flags de

scribe which of

the fields the

kernel should
match against. A

device must
match all speci

fied fields in
order to be re

turned. The
match flags are

enumerated in
the

pci_getconf_flags structure. Hopefully

the flag values are obvious

enough that
they do not need

to described
in detail.

match_buf_len Length of the matches buffer

allocated by

the user to hold the results

of the
PCIOCGETCONF query.

num_matches Number of matches returned

by the kernel.

matches Buffer containing matching

devices

returned by the kernel. The

items in
this buffer are of type

pci_conf, which
consists of the following

items:

pc_sel PCI bus, slot

and function.

pc_hdr PCI header

type.

pc_subvendor PCI subvendor

ID.

pc_subdevice PCI subdevice

ID.

pc_vendor PCI vendor ID.

pc_device PCI device ID.

pc_class PCI device

class.

pc_subclass PCI device

subclass.

pc_progif PCI device

programming

interface.

pc_revid PCI revision

ID.

pd_name Driver name.

pd_unit Driver unit

number.

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 PCIOCGETCONF

ioctl. If the
user does not intend to use

the offset,
it must be set to zero.

generation PCI configuration genera

tion. This value

only needs to be set if the

offset is
set. The kernel will com

pare the current
generation number of its in

ternal device
list to the generation

passed in by the
user to determine whether

its device list
has changed since the user

last called
the PCIOCGETCONF ioctl. If

the device
list has changed, a status

of
PCI_GETCONF_LIST_CHANGED

will be passed
back.

status The status tells the user

the disposition

of his request for a device

list. The
possible status values are:

PCI_GETCONF_LAST_DEVICE
This means that there are no

more devices
in the PCI device list after

the ones
returned in the matches

buffer.

PCI_GETCONF_LIST_CHANGED
This status tells the user

that the PCI
device list has changed

since his last
call to the PCIOCGETCONF

ioctl and he
must reset the offset and

generation to
zero to start over at the

beginning of
the list.

PCI_GETCONF_MORE_DEVS
This tells the user that his

buffer was
not large enough to hold all

of the
remaining devices in the de

vice list that
possibly match his criteria.

It is possible for this status to be

returned,
even when none of the re

maining devices
in the list would match the

user's criteria.

PCI_GETCONF_ERROR
This indicates a general er

ror while servicing the user's request.

If the
pat_buf_len is not equal to

num_patterns
times sizeof(struct

pci_match_conf),
errno will be set to EINVAL.

PCIOCREAD This ioctl(2) reads the PCI configuration

registers

specified by the passed-in pci_io struc

ture. The pci_io
structure consists of the following fields:

pi_sel A pcisel structure which speci

fies the 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.

pi_reg The PCI configuration register

the user would

like to access.

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.

pi_data The data returned by the kernel.

PCIOCWRITE This ioctl(2) allows users to write to the

PCI specified

in the passed-in pci_io structure. The

pci_io structure
is described above. The limitations on da

ta width
described for reading registers, above, al

so apply to
writing PCI configuration registers.

FILES

/dev/pci Character device for the pci driver.

DIAGNOSTICS

None.

SEE ALSO

pciconf(8)

HISTORY

The pci driver (not the kernel's PCI support code) first ap

peared in
FreeBSD 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 FreeBSD 3.0.

AUTHORS

Kenneth Merry <ken@FreeBSD.org>

BUGS

It is not possible for users to specify an accurate offset

into the
device list without calling the PCIOCGETCONF at least once,

since they
have no way of knowing the current generation number other

wise. 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.

BSD October 24, 1999

BSD