man/man9/pci.9

.\"
.\" 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: src/share/man/man9/pci.9,v 1.11 2008/02/15 23:56:33 danger Exp $
.\"
.Dd November 9, 2014
.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 ,
.Nm pci_find_extcap
.Nd PCI bus interface
.Sh SYNOPSIS
.In sys/bus.h
.In bus/pci/pcivar.h
.In bus/pci/pcireg.h
.In bus/pci/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"
.Ft int
.Fn pci_find_extcap "device_t dev" "int capability" "int *capreg"
.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 lost.
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.
.Pp
The
.Fn pci_find_extcap
function is used to locate the first instance of a PCI-express
extended capability register set for the device
.Fa dev .
The extended capability to locate is specified by ID via
.Fa capability .
Constant macros of the form
.Dv PCIZ_xxx
for standard extended capability IDs are defined in
.In bus/pci/pcireg.h .
If the extended capability is found, then
.Fa *capreg
is set to the offset in configuration space of the extended capability
register set, and
.Fn pci_find_extcap
Return the offset in configuration space of the requested extended
capability entry or 0 if the specified capability was not found.
.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 Mt 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.