479 lines
15 KiB
Groff
479 lines
15 KiB
Groff
.\" $NetBSD: pci.9,v 1.6 2002/02/13 08:18:47 ross Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Gregory McGarry.
|
|
.\"
|
|
.\" 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. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
|
|
.\"
|
|
.Dd June 19, 2001
|
|
.Dt PCI 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm PCI ,
|
|
.Nm pci_conf_read ,
|
|
.Nm pci_conf_write ,
|
|
.Nm pci_conf_print ,
|
|
.Nm pci_find_device ,
|
|
.Nm pci_get_capability ,
|
|
.Nm pci_mapreg_type ,
|
|
.Nm pci_mapreg_map ,
|
|
.Nm pci_mapreg_info ,
|
|
.Nm pci_intr_map ,
|
|
.Nm pci_intr_string ,
|
|
.Nm pci_intr_evcnt ,
|
|
.Nm pci_intr_establish ,
|
|
.Nm pci_intr_disestablish ,
|
|
.Nm pci_make_tag ,
|
|
.Nm pci_decompose_tag ,
|
|
.Nm pci_findvendor ,
|
|
.Nm pci_devinfo ,
|
|
.Nm PCI_VENDOR ,
|
|
.Nm PCI_PRODUCT ,
|
|
.Nm PCI_REVISION
|
|
.Nd Peripheral Component Interconnect
|
|
.Sh SYNOPSIS
|
|
.Fd #include \*[Lt]machine/bus.h\*[Gt]
|
|
.Fd #include \*[Lt]dev/pci/pcivar.h\*[Gt]
|
|
.Fd #include \*[Lt]dev/pci/pcireg.h\*[Gt]
|
|
.Fd #include \*[Lt]dev/pci/pcidevs.h\*[Gt]
|
|
.Ft pcireg_t
|
|
.Fn pci_conf_read "pci_chipset_tag_t pc" "pcitag_t tag" "int reg"
|
|
.Ft void
|
|
.Fn pci_conf_write "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \
|
|
"pcireg_t val"
|
|
.Ft void
|
|
.Fn pci_conf_print "pci_chipset_tag_t pc" "pcitag_t tag" \
|
|
"void (*func)(pci_chipset_tag_t, pcitag_t, const pcireg_t *)"
|
|
.Ft int
|
|
.Fn pci_find_device "struct pci_attach_args *pa" \
|
|
"int (*func)(struct pci_attach_args *)"
|
|
.Ft int
|
|
.Fn pci_get_capability "pci_chipset_tag_t pc" "pcitag_t tag" \
|
|
"int capid" "int *offsetp" "pcireg_t *valuep"
|
|
.Ft pcireg_t
|
|
.Fn pci_mapreg_type "pci_chipset_tag_t pc" "pcitag_t tag" "int reg"
|
|
.Ft int
|
|
.Fn pci_mapreg_map "struct pci_attach_args *pa" "int reg" \
|
|
"pcireg_t type" "int busflags" "bus_space_tag_t *tagp" \
|
|
"bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep"
|
|
.Ft int
|
|
.Fn pci_mapreg_info "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \
|
|
"pcireg_t type" "bus_addr_t *basep" "bus_size_t *sizep" "int *flagsp"
|
|
.Ft int
|
|
.Fn pci_intr_map "struct pci_attach_args *pa" "pci_intr_handle_t *ih"
|
|
.Ft const char *
|
|
.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih"
|
|
.Ft const struct evcnt *
|
|
.Fn pci_intr_evcnt "pci_chipset_tag_t pc" "pci_intr_handle_t ih"
|
|
.Ft void *
|
|
.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \
|
|
"int level" "int (*handler)(void *)" "void *arg"
|
|
.Ft void
|
|
.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *ih"
|
|
.Ft pcitag_t
|
|
.Fn pci_make_tag "pci_chipset_tag_t pc" "int bus" "int device" \
|
|
"int function"
|
|
.Ft void
|
|
.Fn pci_decompose_tag "pci_chipset_tag_t pc" "pcitag_t tag" \
|
|
"int *busp" "int *devicep" "int *functionp"
|
|
.Ft char *
|
|
.Fn pci_findvendor "pcireg_t id"
|
|
.Ft void
|
|
.Fn pci_devinfo "pcireg_t id" "pcireg_t class" "int show" "char *cp"
|
|
.Ft int
|
|
.Fn PCI_VENDOR "pcireg_t id"
|
|
.Ft int
|
|
.Fn PCI_PRODUCT "pcireg_t id"
|
|
.Ft int
|
|
.Fn PCI_REVISION "pcireg_t id"
|
|
.Sh DESCRIPTION
|
|
The machine-independent
|
|
.Nm
|
|
subsystem provides support for PCI devices.
|
|
.Pp
|
|
The PCI bus was initially developed by Intel in the early 1990's to
|
|
replace the ISA bus for interfacing with their Pentium processor. The
|
|
PCI specification is widely regarded as well designed, and the PCI bus
|
|
has found widespread acceptance in machines ranging from Apple's
|
|
PowerPC-based systems to Sun's UltraSPARC-based machines.
|
|
.Pp
|
|
The PCI bus is a multiplexed bus, allowing addresses and data on the same
|
|
pins for a reduced number of pins. Data transfers can be 8-bit,
|
|
16-bit or 32-bit. A 64-bit extended PCI bus is also defined.
|
|
Multi-byte transfers are little-endian. The PCI bus operates up to
|
|
33MHz and any device on the bus can be the bus master.
|
|
.Pp
|
|
AGP is a version of PCI optimised for high-throughput data rates,
|
|
particularly for accelerated frame buffers.
|
|
.Pp
|
|
The PCI bus is a "plug and play" bus, in the sense that devices can be
|
|
configured dynamically by software. The PCI interface chip on a PCI
|
|
device bus presents a small window of registers into the PCI
|
|
configuration space. These registers contain information about the
|
|
device such as the vendor and a product ID. The configuration
|
|
registers can also be written to by software to alter how the device
|
|
interfaces to the PCI bus. An important register in the configuration
|
|
space is the Base Address Register (BAR). The BAR is written to by
|
|
software to map the device registers into a window of processor
|
|
address space. Once this mapping is done, the device registers can be
|
|
accessed relative to the base address.
|
|
.Sh DATA TYPES
|
|
Drivers for devices attached to the
|
|
.Nm
|
|
will make use of the following data types:
|
|
.Bl -tag -width compact
|
|
.It Fa pcireg_t
|
|
Configuration space register.
|
|
.It Fa pci_chipset_tag_t
|
|
Chipset tag for the PCI bus.
|
|
.It Fa pcitag_t
|
|
Configuration tag describing the location and function of the PCI
|
|
device. It contains the tuple
|
|
.Ao
|
|
bus, device, function
|
|
.Ac .
|
|
.It Fa pci_intr_handle_t
|
|
The opaque handle describing an established interrupt handler.
|
|
.It Fa struct pci_attach_args
|
|
Devices have their identity recorded in this structure. It contains
|
|
the following members:
|
|
.Bd -literal
|
|
bus_space_tag_t pa_iot; /* pci i/o space tag */
|
|
bus_space_tag_t pa_memt; /* pci mem space tag */
|
|
bus_dma_tag_t pa_dmat; /* DMA tag */
|
|
pci_chipset_tag_t pa_pc;
|
|
int pa_flags; /* flags */
|
|
pcitag_t pa_tag;
|
|
pcireg_t pa_id;
|
|
pcireg_t pa_class;
|
|
.Ed
|
|
.El
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width compact
|
|
.It Fn pci_conf_read "pc" "tag" "reg"
|
|
Read from register
|
|
.Fa reg
|
|
in PCI configuration space. The argument
|
|
.Fa tag
|
|
is the PCI tag for the current device attached to PCI chipset
|
|
.Fa pc .
|
|
.It Fn pci_conf_write "pc" "tag" "reg" "val"
|
|
Write to register
|
|
.Fa reg
|
|
in PCI configuration space. The argument
|
|
.Fa tag
|
|
is the PCI tag for the current device attached to PCI chipset
|
|
.Fa pc .
|
|
.It Fn pci_conf_print "pc" "tag" "func"
|
|
Print out most of the registers in the PCI configuration for the
|
|
device. The argument
|
|
.Fa tag
|
|
is the PCI tag for the current device attached to PCI chipset
|
|
.Fa pc .
|
|
The argument
|
|
.Fa func
|
|
is a function called by
|
|
.Fn pci_conf_print
|
|
to print the device-dependent registers. This function is only useful
|
|
for driver development and is usually wrapped in pre-processor
|
|
declarations.
|
|
.It Fn pci_find_device "pa" "func"
|
|
Find a device using a match function on all probed busses. The
|
|
argument
|
|
.Fa func
|
|
is called by
|
|
.Fn pci_find_device
|
|
to match a device. The argument
|
|
.Fa pa
|
|
is filled in if the device is matched.
|
|
.Fn pci_find_device
|
|
returns 1 if the device is matched, and zero otherwise. This function
|
|
is specifically for use by LKMs (see
|
|
.Xr lkm 4 )
|
|
and its use otherwise is strongly discouraged.
|
|
.It Fn pci_get_capability "pc" "tag" "capid" "offsetp" "valuep"
|
|
Parse the device capability list in configuration space looking for
|
|
capability
|
|
.Fa capid .
|
|
If
|
|
.Fa offsetp
|
|
is not NULL, the register offset in configuration space is returned in
|
|
.Fa offsetp .
|
|
If
|
|
.Fa valuep
|
|
is not NULL, the value of the capability is returned in
|
|
.Fa valuep .
|
|
The argument
|
|
.Fa tag
|
|
is the PCI tag for the current device attached to PCI chipset
|
|
.Fa pc .
|
|
This function returns 1 if the capability was found. If the
|
|
capability was not found, it returns zero, and
|
|
.Fa offsetp
|
|
and
|
|
.Fa valuep
|
|
remain unchanged.
|
|
.It Fn pci_mapreg_type "pc" "tag" "reg"
|
|
Interrogates the Base Address Register (BAR) in configuration space
|
|
specified by
|
|
.Fa reg
|
|
and returns the default (or current) mapping type. Valid returns
|
|
values are:
|
|
.Bl -tag -width compact
|
|
.It PCI_MAPREG_TYPE_IO
|
|
The mapping is to I/O address space.
|
|
.It PCI_MAPREG_TYPE_MEM
|
|
The mapping is to memory address space.
|
|
.It PCI_MAPREG_TYPE_MEM | PCI_MAPREG_MEM_TYPE_64BIT
|
|
The mapping is to 64-bit memory address space.
|
|
.It PCI_MAPREG_TYPE_ROM
|
|
The mapping is to ROM.
|
|
.El
|
|
.sp
|
|
The argument
|
|
.Fa tag
|
|
is the PCI tag for the current device attached to PCI chipset
|
|
.Fa pc .
|
|
.It Fo pci_mapreg_map
|
|
.Fa "pa" "reg" "type" "busflags" "tagp" "handlep"
|
|
.Fa "basep" "sizep"
|
|
.Fc
|
|
Maps the register windows for the device into kernel virtual address
|
|
space. This function is generally only called during the driver
|
|
attach step and takes a pointer to the
|
|
.Em struct pci_attach_args
|
|
in
|
|
.Fa pa .
|
|
The physical address of the mapping is in the Base Address Register
|
|
(BAR) in configuration space specified by
|
|
.Fa reg .
|
|
Valid values for the type of mapping
|
|
.Fa type
|
|
are:
|
|
.Bl -tag -width compact
|
|
.It PCI_MAPREG_TYPE_IO
|
|
The mapping should be to I/O address space.
|
|
.It PCI_MAPREG_TYPE_MEM
|
|
The mapping should be to memory address space.
|
|
.It PCI_MAPREG_TYPE_ROM
|
|
The mapping is to access ROM.
|
|
.El
|
|
.sp
|
|
The argument
|
|
.Fa busflags
|
|
are bus-space flags passed to
|
|
.Fn bus_space_map
|
|
to perform the mapping (see
|
|
.Xr bus_space 9 ) .
|
|
The bus-space tag and handle for the mapped register window are
|
|
returned in
|
|
.Fa tagp
|
|
and
|
|
.Fa handlep
|
|
respectively. The bus-address and size of the mapping are returned in
|
|
.Fa basep
|
|
and
|
|
.Fa sizep
|
|
respectively. If any of
|
|
.Fa tagp ,
|
|
.Fa handlep ,
|
|
.Fa basep ,
|
|
or
|
|
.Fa sizep
|
|
are NULL then
|
|
.Fn pci_mapreg_map
|
|
does not define their return value. This function returns zero on
|
|
success and non-zero on error.
|
|
.It Fn pci_mapreg_info "pc" "tag" "reg" "type" "basep" "sizep" "flagsp"
|
|
Performs the same operations as
|
|
.Fn pci_mapreg_map
|
|
but doesn't actually map the register window into kernel virtual
|
|
address space. Returns the bus-address, size and bus flags in
|
|
.Fa basep ,
|
|
.Fa sizep
|
|
and
|
|
.Fa flagsp
|
|
respectively. These return values can be used by
|
|
.Fn bus_space_map
|
|
to actually map the register window into kernel virtual address space.
|
|
This function is useful for setting up the registers in configuration
|
|
space and deferring the mapping to a later time, such as in a
|
|
bus-independent attachment routine.
|
|
.Fa pci_mapreg_info
|
|
returns zero on success and non-zero on failure.
|
|
.It Fn pci_intr_map "pa" "ih"
|
|
See
|
|
.Xr pci_intr 9 .
|
|
.It Fn pci_intr_string "pc" "ih"
|
|
See
|
|
.Xr pci_intr 9 .
|
|
.It Fn pci_intr_evcnt "pc" "ih"
|
|
See
|
|
.Xr pci_intr 9 .
|
|
.It Fn pci_intr_establish "pc" "ih" "level" "handler" "arg"
|
|
See
|
|
.Xr pci_intr 9 .
|
|
.It Fn pci_intr_disestablish "pc" "ih"
|
|
See
|
|
.Xr pci_intr 9 .
|
|
.It Fn pci_make_tag "pc" "bus" "device" "function"
|
|
Create a new PCI tag for the PCI device specified by the tuple
|
|
.Ao
|
|
bus, device, function
|
|
.Ac .
|
|
This function is not useful to the usual PCI device driver. It is
|
|
generally used by drivers of multi-function devices when attaching
|
|
other PCI device drivers to each function.
|
|
.It Fn pci_decompose_tag "pc" "tag" "busp" "devicep" "fnp"
|
|
Decompose the PCI tag
|
|
.Fa tag
|
|
generated by
|
|
.Fn pci_make_tag
|
|
into its
|
|
.Ao
|
|
bus, device, function
|
|
.Ac
|
|
tuple.
|
|
.It Fn pci_findvendor "id"
|
|
Return the string of the vendor name for the device specified by
|
|
.Fa id .
|
|
.It Fn pci_devinfo "id" "class" "show" "cp"
|
|
Returns the description string from the in-kernel PCI database for the
|
|
device described by
|
|
.Fa id
|
|
and
|
|
.Fa class .
|
|
The description string is returned in
|
|
.Fa cp .
|
|
The argument
|
|
.Fa show
|
|
specifies whether the PCI subsystem should report the string to the
|
|
console.
|
|
.It Fn PCI_VENDOR "id"
|
|
Return the PCI vendor id for device
|
|
.Fa id .
|
|
.It Fn PCI_PRODUCT "id"
|
|
Return the PCI product id for device
|
|
.Fa id .
|
|
.It Fn PCI_REVISION "id"
|
|
Return the PCI product revision for device
|
|
.Fa id .
|
|
.El
|
|
.Sh AUTOCONFIGURATION
|
|
During autoconfiguration, a
|
|
.Nm
|
|
driver will receive a pointer to
|
|
.Fa struct pci_attach_args
|
|
describing the device attaches to the PCI bus. Drivers match the
|
|
device using the
|
|
.Fa pa_id
|
|
member using
|
|
.Fn PCI_VENDOR .
|
|
.Fn PCI_PRODUCT
|
|
and
|
|
.Fn PCI_REVISION .
|
|
.Pp
|
|
During the driver attach step, drivers can read the device
|
|
configuration space using
|
|
.Fn pci_conf_read .
|
|
The meaning attached to registers in the PCI configuration space are
|
|
device-dependent, but will usually contain physical addresses of the
|
|
device register windows. Device options can also be stored into the
|
|
PCI configuration space using
|
|
.Fn pci_conf_write .
|
|
For example, the driver can request support for bus-mastering DMA by
|
|
writing the option to the PCI configuration space.
|
|
.Pp
|
|
Device capabilities can be queried using
|
|
.Fn pci_get_capability ,
|
|
and returns device-specific information which can be found in the PCI
|
|
configuration space to alter device operation.
|
|
.Pp
|
|
After reading the physical addresses of the device register windows
|
|
from configuration space, these windows must be mapped into kernel
|
|
virtual address space using
|
|
.Fn pci_mapreg_map .
|
|
Device registers can now be accessed using the standard bus-space API
|
|
(see
|
|
.Xr bus_space 9 ) .
|
|
.Pp
|
|
Details of using PCI interrupts is described in
|
|
.Xr pci_intr 9 .
|
|
.Sh DMA SUPPORT
|
|
The PCI bus supports bus-mastering operations from any device on the
|
|
bus. The DMA facilities are accessed through the standard
|
|
.Xr bus_dma 9
|
|
interface. To support DMA transfers from the device to the host, it
|
|
is necessary to enable bus-mastering in the PCI configuration space
|
|
for the device.
|
|
.Pp
|
|
During system shutdown, it is necessary to abort any DMA transfers in
|
|
progress by registering a shutdown hook (see
|
|
.Xr shutdownhook_establish 9 ) .
|
|
.Sh CODE REFERENCES
|
|
This section describes places within the
|
|
.Nx
|
|
source tree where actual code implementing or utilising the
|
|
machine-independent PCI subsystem can be found. All pathnames are
|
|
relative to
|
|
.Pa /usr/src .
|
|
.Pp
|
|
The PCI subsystem itself is implemented within the files
|
|
.Pa sys/dev/pci/pci.c ,
|
|
.Pa sys/dev/pci/pci_subr.c ,
|
|
.Pa sys/dev/pci/pci_map.c ,
|
|
.Pa sys/dev/pci/pci_quirks.c ,
|
|
and
|
|
.Pa sys/dev/pci/pciconf.c .
|
|
Machine-dependent portions are implemented within the file
|
|
.Pa sys/arch/\*[Lt]arch\*[Gt]/pci/pci_machdep.c .
|
|
.Pp
|
|
The database of known devices exists within the file
|
|
.Pa sys/dev/pci/pcidevs_data.h
|
|
and is generated automatically from the file
|
|
.Pa sys/dev/pci/pcidevs .
|
|
New vendor and product identifiers should be added to this
|
|
file. The database can be regenerated using the Makefile
|
|
.Pa sys/dev/pci/Makefile.pcidevs .
|
|
.Sh SEE ALSO
|
|
.Xr pci 4 ,
|
|
.Xr autoconf 9 ,
|
|
.Xr bus_dma 9 ,
|
|
.Xr bus_space 9 ,
|
|
.Xr driver 9 ,
|
|
.Xr pci_configure_bus 9 ,
|
|
.Xr pci_intr 9 ,
|
|
.Xr shutdownhook_establish 9
|
|
.Sh HISTORY
|
|
The machine-independent PCI subsystem appeared in
|
|
.Nx 1.2 .
|