55aaf894e8
support machines having multiple independently numbered PCI domains and don't support reenumeration without ambiguity amongst the devices as seen by the OS and represented by PCI location strings. This includes introducing a function pci_find_dbsf(9) which works like pci_find_bsf(9) but additionally takes a domain number argument and limiting pci_find_bsf(9) to only search devices in domain 0 (the only domain in single-domain systems). Bge(4) and ofw_pcibus(4) are changed to use pci_find_dbsf(9) instead of pci_find_bsf(9) in order to no longer report false positives when searching for siblings and dupe devices in the same domain respectively. Along with this change the sole host-PCI bridge driver converted to actually make use of PCI domain support is uninorth(4), the others continue to use domain 0 only for now and need to be converted as appropriate later on. Note that this means that the format of the location strings as used by pciconf(8) has been changed and that consumers of <sys/pciio.h> potentially need to be recompiled. Suggested by: jhb Reviewed by: grehan, jhb, marcel Approved by: re (kensmith), jhb (PCI maintainer hat)
280 lines
7.1 KiB
Groff
280 lines
7.1 KiB
Groff
.\"
|
|
.\" Copyright (c) 2005 Bruce M Simpson <bms@FreeBSD.org>
|
|
.\" 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. 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.
|
|
.\"
|
|
.\" 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 September 30, 2007
|
|
.Dt PCI 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pci ,
|
|
.Nm pci_read_config ,
|
|
.Nm pci_write_config ,
|
|
.Nm pci_enable_busmaster ,
|
|
.Nm pci_disable_busmaster ,
|
|
.Nm pci_enable_io ,
|
|
.Nm pci_disable_io ,
|
|
.Nm pci_set_powerstate ,
|
|
.Nm pci_get_powerstate ,
|
|
.Nm pci_find_bsf ,
|
|
.Nm pci_find_dbsf ,
|
|
.Nm pci_find_device
|
|
.Nd PCI bus interface
|
|
.Sh SYNOPSIS
|
|
.In sys/bus.h
|
|
.In dev/pci/pcivar.h
|
|
.In dev/pci/pcireg.h
|
|
.In machine/pci_cfgreg.h
|
|
.Ft void
|
|
.Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width"
|
|
.Ft int
|
|
.Fn pci_enable_busmaster "device_t dev"
|
|
.Ft int
|
|
.Fn pci_disable_busmaster "device_t dev"
|
|
.Ft int
|
|
.Fn pci_enable_io "device_t dev" "int space"
|
|
.Ft int
|
|
.Fn pci_disable_io "device_t dev" "int space"
|
|
.Ft int
|
|
.Fn pci_set_powerstate "device_t dev" "int state"
|
|
.Ft int
|
|
.Fn pci_get_powerstate "device_t dev"
|
|
.Ft uint32_t
|
|
.Fn pci_read_config "device_t dev" "int reg" "int width"
|
|
.Ft device_t
|
|
.Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
|
|
.Ft device_t
|
|
.Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func"
|
|
.Ft device_t
|
|
.Fn pci_find_device "uint16_t vendor" "uint16_t device"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
set of functions are used for managing PCI devices.
|
|
.Pp
|
|
The
|
|
.Fn pci_read_config
|
|
function is used to read data from the PCI configuration
|
|
space of the device
|
|
.Fa dev ,
|
|
at offset
|
|
.Fa reg ,
|
|
with
|
|
.Fa width
|
|
specifying the size of the access.
|
|
.Pp
|
|
The
|
|
.Fn pci_write_config
|
|
function is used to write the value
|
|
.Fa val
|
|
to the PCI configuration
|
|
space of the device
|
|
.Fa dev ,
|
|
at offset
|
|
.Fa reg ,
|
|
with
|
|
.Fa width
|
|
specifying the size of the access.
|
|
.Pp
|
|
The
|
|
.Fn pci_enable_busmaster
|
|
function enables PCI bus mastering for the device
|
|
.Fa dev ,
|
|
by setting the
|
|
.Dv PCIM_CMD_BUSMASTEREN
|
|
bit in the
|
|
.Dv PCIR_COMMAND
|
|
register.
|
|
The
|
|
.Fn pci_disable_busmaster
|
|
function clears this bit.
|
|
.Pp
|
|
The
|
|
.Fn pci_enable_io
|
|
function enables memory or I/O port address decoding for the device
|
|
.Fa dev ,
|
|
by setting the
|
|
.Dv PCIM_CMD_MEMEN
|
|
or
|
|
.Dv PCIM_CMD_PORTEN
|
|
bit in the
|
|
.Dv PCIR_COMMAND
|
|
register appropriately.
|
|
The
|
|
.Fn pci_disable_io
|
|
function clears the appropriate bit.
|
|
The
|
|
.Fa space
|
|
argument specifies which resource is affected; this can be either
|
|
.Dv SYS_RES_MEMORY
|
|
or
|
|
.Dv SYS_RES_IOPORT
|
|
as appropriate.
|
|
.Pp
|
|
.Em NOTE :
|
|
These functions should be used in preference to manually manipulating
|
|
the configuration space.
|
|
.Pp
|
|
The
|
|
.Fn pci_get_powerstate
|
|
function returns the current ACPI power state of the device
|
|
.Fa dev .
|
|
If the device does not support power management capabilities, then the default
|
|
state of
|
|
.Dv PCI_POWERSTATE_D0
|
|
is returned.
|
|
The following power states are defined by ACPI:
|
|
.Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN"
|
|
.It Dv PCI_POWERSTATE_D0
|
|
State in which device is on and running.
|
|
It is receiving full power from the system and delivering
|
|
full functionality to the user.
|
|
.It Dv PCI_POWERSTATE_D1
|
|
Class-specific low-power state in which device context may or
|
|
may not be lot.
|
|
Busses in this state cannot do anything to the bus, to
|
|
force devices to lose context.
|
|
.It Dv PCI_POWERSTATE_D2
|
|
Class-specific low-power state in which device context may or
|
|
may not be lost.
|
|
Attains greater power savings than
|
|
.Dv PCI_POWERSTATE_D1 .
|
|
Busses in this state can cause devices to lose some context.
|
|
Devices
|
|
.Em must
|
|
be prepared for the bus to be in this state or higher.
|
|
.It Dv PCI_POWERSTATE_D3
|
|
State in which the device is off and not running.
|
|
Device context is lost, and power from the device can
|
|
be removed.
|
|
.It Dv PCI_POWERSTATE_UNKNOWN
|
|
State of the device is unknown.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn pci_set_powerstate
|
|
function is used to transition the device
|
|
.Fa dev
|
|
to the ACPI power state
|
|
.Fa state .
|
|
It checks to see if the device is PCI 2.2 compliant.
|
|
If so, it checks the
|
|
capabilities pointer to determine which power states the device supports.
|
|
If the device does not have power management capabilities, the default state
|
|
of
|
|
.Dv PCI_POWERSTATE_D0
|
|
is set.
|
|
.Pp
|
|
The
|
|
.Fn pci_find_bsf
|
|
function looks up the
|
|
.Vt device_t
|
|
of a PCI device, given its
|
|
.Fa bus ,
|
|
.Fa slot ,
|
|
and
|
|
.Fa func .
|
|
The
|
|
.Fa slot
|
|
number actually refers to the number of the device on the bus,
|
|
which does not necessarily indicate its geographic location
|
|
in terms of a physical slot.
|
|
Note that in case the system has multiple PCI domains,
|
|
the
|
|
.Fn pci_find_bsf
|
|
function only searches the first one.
|
|
Actually, it is equivalent to:
|
|
.Bd -literal -offset indent
|
|
pci_find_dbsf(0, bus, slot, func);
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fn pci_find_dbsf
|
|
function looks up the
|
|
.Vt device_t
|
|
of a PCI device, given its
|
|
.Fa domain ,
|
|
.Fa bus ,
|
|
.Fa slot ,
|
|
and
|
|
.Fa func .
|
|
The
|
|
.Fa slot
|
|
number actually refers to the number of the device on the bus,
|
|
which does not necessarily indicate its geographic location
|
|
in terms of a physical slot.
|
|
.Pp
|
|
The
|
|
.Fn pci_find_device
|
|
function looks up the
|
|
.Vt device_t
|
|
of a PCI device, given its
|
|
.Fa vendor
|
|
and
|
|
.Fa device
|
|
IDs.
|
|
Note that there can be multiple matches for this search; this function
|
|
only returns the first matching device.
|
|
.Sh IMPLEMENTATION NOTES
|
|
The
|
|
.Vt pci_addr_t
|
|
type varies according to the size of the PCI bus address
|
|
space on the target architecture.
|
|
.Sh SEE ALSO
|
|
.Xr pci 4 ,
|
|
.Xr pciconf 8 ,
|
|
.Xr bus_alloc_resource 9 ,
|
|
.Xr bus_dma 9 ,
|
|
.Xr bus_release_resource 9 ,
|
|
.Xr bus_setup_intr 9 ,
|
|
.Xr bus_teardown_intr 9 ,
|
|
.Xr devclass 9 ,
|
|
.Xr device 9 ,
|
|
.Xr driver 9 ,
|
|
.Xr rman 9
|
|
.Rs
|
|
.%B FreeBSD Developers' Handbook
|
|
.%T NewBus
|
|
.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
|
|
.Re
|
|
.Rs
|
|
.%A Shanley
|
|
.%A Anderson
|
|
.%B PCI System Architecture
|
|
.%N 2nd Edition
|
|
.%I Addison-Wesley
|
|
.%O ISBN 0-201-30974-2
|
|
.Re
|
|
.Sh AUTHORS
|
|
This manual page was written by
|
|
.An Bruce M Simpson Aq bms@FreeBSD.org .
|
|
.Sh BUGS
|
|
The kernel PCI code has a number of references to
|
|
.Dq "slot numbers" .
|
|
These do not refer to the geographic location of PCI devices,
|
|
but to the device number assigned by the combination of the PCI IDSEL
|
|
mechanism and the platform firmware.
|
|
This should be taken note of when working with the kernel PCI code.
|