share/man/man9/pci.9

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