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