share/man/man9/pci.9

   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
  74 The
  75 .Nm
  76 set of functions are used for managing PCI devices.
  77 .Pp
  78 The
  79 .Fn pci_read_config
  80 function is used to read data from the PCI configuration
  81 space of the device
  82 .Fa dev ,
  83 at offset
  84 .Fa reg ,
  85 with
  86 .Fa width
  87 specifying the size of the access.
  88 .Pp
  89 The
  90 .Fn pci_write_config
  91 function is used to write the value
  92 .Fa val
  93 to the PCI configuration
  94 space of the device
  95 .Fa dev ,
  96 at offset
  97 .Fa reg ,
  98 with
  99 .Fa width
 100 specifying the size of the access.
 101 .Pp
 102 The
 103 .Fn pci_enable_busmaster
 104 function enables PCI bus mastering for the device
 105 .Fa dev ,
 106 by setting the
 107 .Dv PCIM_CMD_BUSMASTEREN
 108 bit in the
 109 .Dv PCIR_COMMAND
 110 register.
 111 The
 112 .Fn pci_disable_busmaster
 113 function clears this bit.
 114 .Pp
 115 The
 116 .Fn pci_enable_io
 117 function enables memory or I/O port address decoding for the device
 118 .Fa dev ,
 119 by setting the
 120 .Dv PCIM_CMD_MEMEN
 121 or
 122 .Dv PCIM_CMD_PORTEN
 123 bit in the
 124 .Dv PCIR_COMMAND
 125 register appropriately.
 126 The
 127 .Fn pci_disable_io
 128 function clears the appropriate bit.
 129 The
 130 .Fa space
 131 argument specifies which resource is affected; this can be either
 132 .Dv SYS_RES_MEMORY
 133 or
 134 .Dv SYS_RES_IOPORT
 135 as appropriate.
 136 .Pp
 137 .Em NOTE :
 138 These functions should be used in preference to manually manipulating
 139 the configuration space.
 140 .Pp
 141 The
 142 .Fn pci_get_powerstate
 143 function returns the current ACPI power state of the device
 144 .Fa dev .
 145 If the device does not support power management capabilities, then the default
 146 state of
 147 .Dv PCI_POWERSTATE_D0
 148 is returned.
 149 The following power states are defined by ACPI:
 150 .Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN"
 151 .It Dv PCI_POWERSTATE_D0
 152 State in which device is on and running.
 153 It is receiving full power from the system and delivering
 154 full functionality to the user.
 155 .It Dv PCI_POWERSTATE_D1
 156 Class-specific low-power state in which device context may or
 157 may not be lost.
 158 Busses in this state cannot do anything to the bus, to
 159 force devices to lose context.
 160 .It Dv PCI_POWERSTATE_D2
 161 Class-specific low-power state in which device context may or
 162 may not be lost.
 163 Attains greater power savings than
 164 .Dv PCI_POWERSTATE_D1 .
 165 Busses in this state can cause devices to lose some context.
 166 Devices
 167 .Em must
 168 be prepared for the bus to be in this state or higher.
 169 .It Dv PCI_POWERSTATE_D3
 170 State in which the device is off and not running.
 171 Device context is lost, and power from the device can
 172 be removed.
 173 .It Dv PCI_POWERSTATE_UNKNOWN
 174 State of the device is unknown.
 175 .El
 176 .Pp
 177 The
 178 .Fn pci_set_powerstate
 179 function is used to transition the device
 180 .Fa dev
 181 to the ACPI power state
 182 .Fa state .
 183 It checks to see if the device is PCI 2.2 compliant.
 184 If so, it checks the
 185 capabilities pointer to determine which power states the device supports.
 186 If the device does not have power management capabilities, the default state
 187 of
 188 .Dv PCI_POWERSTATE_D0
 189 is set.
 190 .Pp
 191 The
 192 .Fn pci_find_bsf
 193 function looks up the
 194 .Vt device_t
 195 of a PCI device, given its
 196 .Fa bus ,
 197 .Fa slot ,
 198 and
 199 .Fa func .
 200 The
 201 .Fa slot
 202 number actually refers to the number of the device on the bus,
 203 which does not necessarily indicate its geographic location
 204 in terms of a physical slot.
 205 Note that in case the system has multiple PCI domains,
 206 the
 207 .Fn pci_find_bsf
 208 function only searches the first one.
 209 Actually, it is equivalent to:
 210 .Bd -literal -offset indent
 211 pci_find_dbsf(0, bus, slot, func);
 212 .Ed
 213 .Pp
 214 The
 215 .Fn pci_find_dbsf
 216 function looks up the
 217 .Vt device_t
 218 of a PCI device, given its
 219 .Fa domain ,
 220 .Fa bus ,
 221 .Fa slot ,
 222 and
 223 .Fa func .
 224 The
 225 .Fa slot
 226 number actually refers to the number of the device on the bus,
 227 which does not necessarily indicate its geographic location
 228 in terms of a physical slot.
 229 .Pp
 230 The
 231 .Fn pci_find_device
 232 function looks up the
 233 .Vt device_t
 234 of a PCI device, given its
 235 .Fa vendor
 236 and
 237 .Fa device
 238 IDs.
 239 Note that there can be multiple matches for this search; this function
 240 only returns the first matching device.
 241 .Sh IMPLEMENTATION NOTES
 242 The
 243 .Vt pci_addr_t
 244 type varies according to the size of the PCI bus address
 245 space 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
 272 This manual page was written by
 273 .An Bruce M Simpson Aq bms@FreeBSD.org .
 274 .Sh BUGS
 275 The kernel PCI code has a number of references to
 276 .Dq "slot numbers" .
 277 These do not refer to the geographic location of PCI devices,
 278 but to the device number assigned by the combination of the PCI IDSEL
 279 mechanism and the platform firmware.
 280 This should be taken note of when working with the kernel PCI code.