Bring in a manual page documenting some important functions of the

PCI bus interface.  I have made some modifications to this manual
page, so it looks a bit different from the original version that
was posted to me.

Submitted by:		Bruce M. Simpson <bms@spc.org>
Reviewed by:		imp, mdodd (early copy)
Approved by:		des (mentor)

MFC after:		3 days

1 files changed, 240 insertions, 0 deletions

diff --git a/share/man/man9/pci.9 b/share/man/man9/pci.9
new file mode 100644
index 0000000..09ec5ce
--- /dev/null
+++ b/share/man/man9/pci.9
@@ -0,0 +1,240 @@
+.\"
+.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.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 May 21, 2003
+.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_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
+.Pp
+.Ft void
+.Fn pci_write_config "device_t dev" "int reg" "u_int32_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 u_int32_t
+.Fn pci_read_config "device_t dev" "int reg" "int width"
+.Ft device_t
+.Fn pci_find_bsf "u_int8_t" "u_int8_t" "u_int8_t"
+.Ft device_t
+.Fn pci_find_device "u_int16_t" "u_int16_t"
+.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 state
+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 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.
+Buses in this state cannot do anything to the bus, to
+force devices to loose 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 .
+Buses in this state can cause devices to loose 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 function .
+.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 is varies according to the size of the PCI bus address
+space on the target architecture.
+.Sh SEE ALSO
+.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 man page was written by
+.An Bruce M Simpson Aq bms@spc.org .
+.Sh BUGS
+This manual page does not yet document PAE and how it affects memory-space
+mapping of PCI devices.