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.2 2003/06/17 04:37:01 dillon Exp $
  28 .\"
  29 .Dd May 21, 2003
  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 dev/pci/pcivar.h
  48 .In dev/pci/pcireg.h
  49 .In machine/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 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 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" "u_int8_t" "u_int8_t"
  69 .Ft device_t
  70 .Fn pci_find_device "u_int16_t" "u_int16_t"
  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. The
 124 .Fn pci_disable_io
 125 function clears the appropriate bit.
 126 The
 127 .Fa state
 128 argument specifies which resource is affected; this can be either
 129 .Dv SYS_RES_MEMORY
 130 or
 131 .Dv SYS_RES_IOPORT
 132 as appropriate.
 133 .Pp
 134 .Em NOTE :
 135 These functions should be used in preference to manually manipulating
 136 the configuration space.
 137 .Pp
 138 The
 139 .Fn pci_get_powerstate
 140 function returns the current ACPI power state of the device
 141 .Fa dev .
 142 If the device does not support power management capabilities, then the default
 143 state of
 144 .Dv PCI_POWERSTATE_D0
 145 is returned.
 146 The following power states are defined by ACPI:
 147 .Bl -hang -width PCI_POWERSTATE_UNKNOWN
 148 .It Dv PCI_POWERSTATE_D0
 149 State in which device is on and running.
 150 It is receiving full power from the system and delivering
 151 full functionality to the user.
 152 .It Dv PCI_POWERSTATE_D1
 153 Class-specific low-power state in which device context may or
 154 may not be lot.
 155 Buses in this state cannot do anything to the bus, to
 156 force devices to loose context.
 157 .It Dv PCI_POWERSTATE_D2
 158 Class-specific low-power state in which device context may or
 159 may not be lost.
 160 Attains greater power savings than
 161 .Dv PCI_POWERSTATE_D1 .
 162 Buses in this state can cause devices to loose some context.
 163 Devices
 164 .Em must
 165 be prepared for the bus to be in this state or higher.
 166 .It Dv PCI_POWERSTATE_D3
 167 State in which the device is off and not running.
 168 Device context is lost, and power from the device can
 169 be removed.
 170 .It Dv PCI_POWERSTATE_UNKNOWN
 171 State of the device is unknown.
 172 .El
 173 .Pp
 174 The
 175 .Fn pci_set_powerstate
 176 function is used to transition the device
 177 .Fa dev
 178 to the ACPI power state
 179 .Fa state .
 180 It checks to see if the device is PCI 2.2 compliant.
 181 If so, it checks the
 182 capabilities pointer to determine which power states the device supports.
 183 If the device does not have power management capabilities, the default state
 184 of
 185 .Dv PCI_POWERSTATE_D0
 186 is set.
 187 .Pp
 188 The
 189 .Fn pci_find_bsf
 190 function looks up the
 191 .Vt device_t
 192 of a PCI device, given its
 193 .Fa bus ,
 194 .Fa slot ,
 195 and
 196 .Fa function .
 197 .Pp
 198 The
 199 .Fn pci_find_device
 200 function looks up the
 201 .Vt device_t
 202 of a PCI device, given its
 203 .Fa vendor
 204 and
 205 .Fa device
 206 IDs. Note that there can be multiple matches for this search; this function
 207 only returns the first matching device.
 208 .Sh IMPLEMENTATION NOTES
 209 The
 210 .Vt pci_addr_t
 211 type is varies according to the size of the PCI bus address
 212 space on the target architecture.
 213 .Sh SEE ALSO
 214 .Xr pci 4 ,
 215 .Xr pciconf 8 ,
 216 .Xr bus_alloc_resource 9 ,
 217 .Xr bus_dma 9 ,
 218 .Xr bus_release_resource 9 ,
 219 .Xr bus_setup_intr 9 ,
 220 .Xr bus_teardown_intr 9 ,
 221 .Xr devclass 9 ,
 222 .Xr device 9 ,
 223 .Xr driver 9 ,
 224 .Xr rman 9
 225 .Rs
 226 .%B FreeBSD Developers' Handbook
 227 .%T NewBus
 228 .%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
 229 .Re
 230 .Rs
 231 .%A Shanley
 232 .%A Anderson
 233 .%B PCI System Architecture
 234 .%N 2nd Edition
 235 .%I Addison-Wesley
 236 .%O ISBN 0-201-30974-2
 237 .Re
 238 .Sh AUTHORS
 239 This man page was written by
 240 .An Bruce M Simpson Aq bms@spc.org .
 241 .Sh BUGS
 242 This manual page does not yet document PAE and how it affects memory-space
 243 mapping of PCI devices.