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$ 27.\" 28.Dd September 30, 2007 29.Dt PCI 9 30.Os 31.Sh NAME 32.Nm pci , 33.Nm pci_read_config , 34.Nm pci_write_config , 35.Nm pci_enable_busmaster , 36.Nm pci_disable_busmaster , 37.Nm pci_enable_io , 38.Nm pci_disable_io , 39.Nm pci_set_powerstate , 40.Nm pci_get_powerstate , 41.Nm pci_find_bsf , 42.Nm pci_find_dbsf , 43.Nm pci_find_device 44.Nd PCI bus interface 45.Sh SYNOPSIS 46.In sys/bus.h 47.In dev/pci/pcivar.h 48.In dev/pci/pcireg.h 49.In machine/pci_cfgreg.h 50.Ft void 51.Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width" 52.Ft int 53.Fn pci_enable_busmaster "device_t dev" 54.Ft int 55.Fn pci_disable_busmaster "device_t dev" 56.Ft int 57.Fn pci_enable_io "device_t dev" "int space" 58.Ft int 59.Fn pci_disable_io "device_t dev" "int space" 60.Ft int 61.Fn pci_set_powerstate "device_t dev" "int state" 62.Ft int 63.Fn pci_get_powerstate "device_t dev" 64.Ft uint32_t 65.Fn pci_read_config "device_t dev" "int reg" "int width" 66.Ft device_t 67.Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func" 68.Ft device_t 69.Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func" 70.Ft device_t 71.Fn pci_find_device "uint16_t vendor" "uint16_t device" 72.Sh DESCRIPTION 73The 74.Nm 75set of functions are used for managing PCI devices. 76.Pp 77The 78.Fn pci_read_config 79function is used to read data from the PCI configuration 80space of the device 81.Fa dev , 82at offset 83.Fa reg , 84with 85.Fa width 86specifying the size of the access. 87.Pp 88The 89.Fn pci_write_config 90function is used to write the value 91.Fa val 92to the PCI configuration 93space of the device 94.Fa dev , 95at offset 96.Fa reg , 97with 98.Fa width 99specifying the size of the access. 100.Pp 101The 102.Fn pci_enable_busmaster 103function enables PCI bus mastering for the device 104.Fa dev , 105by setting the 106.Dv PCIM_CMD_BUSMASTEREN 107bit in the 108.Dv PCIR_COMMAND 109register. 110The 111.Fn pci_disable_busmaster 112function clears this bit. 113.Pp 114The 115.Fn pci_enable_io 116function enables memory or I/O port address decoding for the device 117.Fa dev , 118by setting the 119.Dv PCIM_CMD_MEMEN 120or 121.Dv PCIM_CMD_PORTEN 122bit in the 123.Dv PCIR_COMMAND 124register appropriately. 125The 126.Fn pci_disable_io 127function clears the appropriate bit. 128The 129.Fa space 130argument specifies which resource is affected; this can be either 131.Dv SYS_RES_MEMORY 132or 133.Dv SYS_RES_IOPORT 134as appropriate. 135.Pp 136.Em NOTE : 137These functions should be used in preference to manually manipulating 138the configuration space. 139.Pp 140The 141.Fn pci_get_powerstate 142function returns the current ACPI power state of the device 143.Fa dev . 144If the device does not support power management capabilities, then the default 145state of 146.Dv PCI_POWERSTATE_D0 147is returned. 148The following power states are defined by ACPI: 149.Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN" 150.It Dv PCI_POWERSTATE_D0 151State in which device is on and running. 152It is receiving full power from the system and delivering 153full functionality to the user. 154.It Dv PCI_POWERSTATE_D1 155Class-specific low-power state in which device context may or 156may not be lost. 157Busses in this state cannot do anything to the bus, to 158force devices to lose context. 159.It Dv PCI_POWERSTATE_D2 160Class-specific low-power state in which device context may or 161may not be lost. 162Attains greater power savings than 163.Dv PCI_POWERSTATE_D1 . 164Busses in this state can cause devices to lose some context. 165Devices 166.Em must 167be prepared for the bus to be in this state or higher. 168.It Dv PCI_POWERSTATE_D3 169State in which the device is off and not running. 170Device context is lost, and power from the device can 171be removed. 172.It Dv PCI_POWERSTATE_UNKNOWN 173State of the device is unknown. 174.El 175.Pp 176The 177.Fn pci_set_powerstate 178function is used to transition the device 179.Fa dev 180to the ACPI power state 181.Fa state . 182It checks to see if the device is PCI 2.2 compliant. 183If so, it checks the 184capabilities pointer to determine which power states the device supports. 185If the device does not have power management capabilities, the default state 186of 187.Dv PCI_POWERSTATE_D0 188is set. 189.Pp 190The 191.Fn pci_find_bsf 192function looks up the 193.Vt device_t 194of a PCI device, given its 195.Fa bus , 196.Fa slot , 197and 198.Fa func . 199The 200.Fa slot 201number actually refers to the number of the device on the bus, 202which does not necessarily indicate its geographic location 203in terms of a physical slot. 204Note that in case the system has multiple PCI domains, 205the 206.Fn pci_find_bsf 207function only searches the first one. 208Actually, it is equivalent to: 209.Bd -literal -offset indent 210pci_find_dbsf(0, bus, slot, func); 211.Ed 212.Pp 213The 214.Fn pci_find_dbsf 215function looks up the 216.Vt device_t 217of a PCI device, given its 218.Fa domain , 219.Fa bus , 220.Fa slot , 221and 222.Fa func . 223The 224.Fa slot 225number actually refers to the number of the device on the bus, 226which does not necessarily indicate its geographic location 227in terms of a physical slot. 228.Pp 229The 230.Fn pci_find_device 231function looks up the 232.Vt device_t 233of a PCI device, given its 234.Fa vendor 235and 236.Fa device 237IDs. 238Note that there can be multiple matches for this search; this function 239only returns the first matching device. 240.Sh IMPLEMENTATION NOTES 241The 242.Vt pci_addr_t 243type varies according to the size of the PCI bus address 244space on the target architecture. 245.Sh SEE ALSO 246.Xr pci 4 , 247.Xr pciconf 8 , 248.Xr bus_alloc_resource 9 , 249.Xr bus_dma 9 , 250.Xr bus_release_resource 9 , 251.Xr bus_setup_intr 9 , 252.Xr bus_teardown_intr 9 , 253.Xr devclass 9 , 254.Xr device 9 , 255.Xr driver 9 , 256.Xr rman 9 257.Rs 258.%B FreeBSD Developers' Handbook 259.%T NewBus 260.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ 261.Re 262.Rs 263.%A Shanley 264.%A Anderson 265.%B PCI System Architecture 266.%N 2nd Edition 267.%I Addison-Wesley 268.%O ISBN 0-201-30974-2 269.Re 270.Sh AUTHORS 271This manual page was written by 272.An Bruce M Simpson Aq bms@FreeBSD.org . 273.Sh BUGS 274The kernel PCI code has a number of references to 275.Dq "slot numbers" . 276These do not refer to the geographic location of PCI devices, 277but to the device number assigned by the combination of the PCI IDSEL 278mechanism and the platform firmware. 279This should be taken note of when working with the kernel PCI code. 280