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