1.\" 2.\" Copyright (c) 2005 Bruce M Simpson <bms@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD: src/share/man/man9/pci.9,v 1.11 2008/02/15 23:56:33 danger Exp $ 27.\" $DragonFly: src/share/man/man9/pci.9,v 1.6 2008/08/02 01:14:36 dillon Exp $ 28.\" 29.Dd July 9, 2009 30.Dt PCI 9 31.Os 32.Sh NAME 33.Nm pci , 34.Nm pci_read_config , 35.Nm pci_write_config , 36.Nm pci_enable_busmaster , 37.Nm pci_disable_busmaster , 38.Nm pci_enable_io , 39.Nm pci_disable_io , 40.Nm pci_set_powerstate , 41.Nm pci_get_powerstate , 42.Nm pci_find_bsf , 43.Nm pci_find_dbsf , 44.Nm pci_find_device 45.Nd PCI bus interface 46.Sh SYNOPSIS 47.In sys/bus.h 48.In bus/pci/pcivar.h 49.In bus/pci/pcireg.h 50.In bus/pci/pci_cfgreg.h 51.Ft void 52.Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width" 53.Ft int 54.Fn pci_enable_busmaster "device_t dev" 55.Ft int 56.Fn pci_disable_busmaster "device_t dev" 57.Ft int 58.Fn pci_enable_io "device_t dev" "int space" 59.Ft int 60.Fn pci_disable_io "device_t dev" "int space" 61.Ft int 62.Fn pci_set_powerstate "device_t dev" "int state" 63.Ft int 64.Fn pci_get_powerstate "device_t dev" 65.Ft uint32_t 66.Fn pci_read_config "device_t dev" "int reg" "int width" 67.Ft device_t 68.Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func" 69.Ft device_t 70.Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func" 71.Ft device_t 72.Fn pci_find_device "uint16_t vendor" "uint16_t device" 73.Sh DESCRIPTION 74The 75.Nm 76set of functions are used for managing PCI devices. 77.Pp 78The 79.Fn pci_read_config 80function is used to read data from the PCI configuration 81space of the device 82.Fa dev , 83at offset 84.Fa reg , 85with 86.Fa width 87specifying the size of the access. 88.Pp 89The 90.Fn pci_write_config 91function is used to write the value 92.Fa val 93to the PCI configuration 94space of the device 95.Fa dev , 96at offset 97.Fa reg , 98with 99.Fa width 100specifying the size of the access. 101.Pp 102The 103.Fn pci_enable_busmaster 104function enables PCI bus mastering for the device 105.Fa dev , 106by setting the 107.Dv PCIM_CMD_BUSMASTEREN 108bit in the 109.Dv PCIR_COMMAND 110register. 111The 112.Fn pci_disable_busmaster 113function clears this bit. 114.Pp 115The 116.Fn pci_enable_io 117function enables memory or I/O port address decoding for the device 118.Fa dev , 119by setting the 120.Dv PCIM_CMD_MEMEN 121or 122.Dv PCIM_CMD_PORTEN 123bit in the 124.Dv PCIR_COMMAND 125register appropriately. 126The 127.Fn pci_disable_io 128function clears the appropriate bit. 129The 130.Fa space 131argument specifies which resource is affected; this can be either 132.Dv SYS_RES_MEMORY 133or 134.Dv SYS_RES_IOPORT 135as appropriate. 136.Pp 137.Em NOTE : 138These functions should be used in preference to manually manipulating 139the configuration space. 140.Pp 141The 142.Fn pci_get_powerstate 143function returns the current ACPI power state of the device 144.Fa dev . 145If the device does not support power management capabilities, then the default 146state of 147.Dv PCI_POWERSTATE_D0 148is returned. 149The following power states are defined by ACPI: 150.Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN" 151.It Dv PCI_POWERSTATE_D0 152State in which device is on and running. 153It is receiving full power from the system and delivering 154full functionality to the user. 155.It Dv PCI_POWERSTATE_D1 156Class-specific low-power state in which device context may or 157may not be lost. 158Busses in this state cannot do anything to the bus, to 159force devices to lose context. 160.It Dv PCI_POWERSTATE_D2 161Class-specific low-power state in which device context may or 162may not be lost. 163Attains greater power savings than 164.Dv PCI_POWERSTATE_D1 . 165Busses in this state can cause devices to lose some context. 166Devices 167.Em must 168be prepared for the bus to be in this state or higher. 169.It Dv PCI_POWERSTATE_D3 170State in which the device is off and not running. 171Device context is lost, and power from the device can 172be removed. 173.It Dv PCI_POWERSTATE_UNKNOWN 174State of the device is unknown. 175.El 176.Pp 177The 178.Fn pci_set_powerstate 179function is used to transition the device 180.Fa dev 181to the ACPI power state 182.Fa state . 183It checks to see if the device is PCI 2.2 compliant. 184If so, it checks the 185capabilities pointer to determine which power states the device supports. 186If the device does not have power management capabilities, the default state 187of 188.Dv PCI_POWERSTATE_D0 189is set. 190.Pp 191The 192.Fn pci_find_bsf 193function looks up the 194.Vt device_t 195of a PCI device, given its 196.Fa bus , 197.Fa slot , 198and 199.Fa func . 200The 201.Fa slot 202number actually refers to the number of the device on the bus, 203which does not necessarily indicate its geographic location 204in terms of a physical slot. 205Note that in case the system has multiple PCI domains, 206the 207.Fn pci_find_bsf 208function only searches the first one. 209Actually, it is equivalent to: 210.Bd -literal -offset indent 211pci_find_dbsf(0, bus, slot, func); 212.Ed 213.Pp 214The 215.Fn pci_find_dbsf 216function looks up the 217.Vt device_t 218of a PCI device, given its 219.Fa domain , 220.Fa bus , 221.Fa slot , 222and 223.Fa func . 224The 225.Fa slot 226number actually refers to the number of the device on the bus, 227which does not necessarily indicate its geographic location 228in terms of a physical slot. 229.Pp 230The 231.Fn pci_find_device 232function looks up the 233.Vt device_t 234of a PCI device, given its 235.Fa vendor 236and 237.Fa device 238IDs. 239Note that there can be multiple matches for this search; this function 240only returns the first matching device. 241.Sh IMPLEMENTATION NOTES 242The 243.Vt pci_addr_t 244type varies according to the size of the PCI bus address 245space on the target architecture. 246.Sh SEE ALSO 247.Xr pci 4 , 248.Xr pciconf 8 , 249.Xr bus_alloc_resource 9 , 250.Xr bus_dma 9 , 251.Xr bus_release_resource 9 , 252.Xr bus_setup_intr 9 , 253.Xr bus_teardown_intr 9 , 254.Xr devclass 9 , 255.Xr device 9 , 256.Xr driver 9 , 257.Xr rman 9 258.Rs 259.%B FreeBSD Developers' Handbook 260.%T NewBus 261.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 262.Re 263.Rs 264.%A Shanley 265.%A Anderson 266.%B PCI System Architecture 267.%N 2nd Edition 268.%I Addison-Wesley 269.%O ISBN 0-201-30974-2 270.Re 271.Sh AUTHORS 272This manual page was written by 273.An Bruce M Simpson Aq bms@FreeBSD.org . 274.Sh BUGS 275The kernel PCI code has a number of references to 276.Dq "slot numbers" . 277These do not refer to the geographic location of PCI devices, 278but to the device number assigned by the combination of the PCI IDSEL 279mechanism and the platform firmware. 280This should be taken note of when working with the kernel PCI code. 281