.\" .\" 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: src/share/man/man9/pci.9,v 1.2.2.1 2003/06/13 01:04:17 hmp Exp $ .\" $DragonFly: src/share/man/man9/pci.9,v 1.3 2005/12/20 13:05:15 swildner Exp $ .\" .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 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 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.