From a2233471565b09968e95c9728de99650b35f9a56 Mon Sep 17 00:00:00 2001 From: hmp Date: Mon, 9 Jun 2003 17:32:41 +0000 Subject: 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 Reviewed by: imp, mdodd (early copy) Approved by: des (mentor) MFC after: 3 days --- share/man/man9/pci.9 | 240 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 share/man/man9/pci.9 (limited to 'share/man') 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 +.\" 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. -- cgit v1.1