| 1 | .\" |
| 2 | .\" Copyright (c) 1999 Kenneth D. Merry. |
| 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. The name of the author may not be used to endorse or promote products |
| 11 | .\" derived from this software without specific prior written permission. |
| 12 | .\" |
| 13 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
| 14 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 15 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 16 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
| 17 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 18 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 19 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 20 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 21 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 22 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 23 | .\" SUCH DAMAGE. |
| 24 | .\" |
| 25 | .\" $FreeBSD: src/share/man/man4/pci.4,v 1.3.2.5 2001/08/17 13:08:39 ru Exp $ |
| 26 | .\" $DragonFly: src/share/man/man4/pci.4,v 1.5 2008/11/13 21:46:03 swildner Exp $ |
| 27 | .\" |
| 28 | .Dd July 5, 2009 |
| 29 | .Dt PCI 4 |
| 30 | .Os |
| 31 | .Sh NAME |
| 32 | .Nm pci |
| 33 | .Nd generic PCI driver |
| 34 | .Sh SYNOPSIS |
| 35 | .Cd device pci |
| 36 | .Sh DESCRIPTION |
| 37 | The |
| 38 | .Nm |
| 39 | driver provides a way for userland programs to read and write |
| 40 | .Tn PCI |
| 41 | configuration registers. |
| 42 | It also provides a way for userland programs to get a list of all |
| 43 | .Tn PCI |
| 44 | devices, or all |
| 45 | .Tn PCI |
| 46 | devices that match various patterns. |
| 47 | .Pp |
| 48 | Since the |
| 49 | .Nm |
| 50 | driver provides a write interface for |
| 51 | .Tn PCI |
| 52 | configuration registers, system administrators should exercise caution when |
| 53 | granting access to the |
| 54 | .Nm |
| 55 | device. |
| 56 | If used improperly, this driver can allow userland applications to |
| 57 | crash a machine or cause data loss. |
| 58 | .Sh KERNEL CONFIGURATION |
| 59 | It is only necessary to specify one |
| 60 | .Nm |
| 61 | controller in the kernel. |
| 62 | Additional |
| 63 | .Tn PCI |
| 64 | busses are handled automatically as they are encountered. |
| 65 | .Sh IOCTLS |
| 66 | The following |
| 67 | .Xr ioctl 2 |
| 68 | calls are supported by the |
| 69 | .Nm |
| 70 | driver. |
| 71 | They are defined in the header file |
| 72 | .In sys/pciio.h . |
| 73 | .Bl -tag -width ".It Dv PCIOCGETCONF" |
| 74 | .It Dv PCIOCGETCONF |
| 75 | This |
| 76 | .Xr ioctl 2 |
| 77 | takes a |
| 78 | .Va pci_conf_io |
| 79 | structure. |
| 80 | It allows the user to retrieve information on all |
| 81 | .Tn PCI |
| 82 | devices in the system, or on |
| 83 | .Tn PCI |
| 84 | devices matching patterns supplied by the user. |
| 85 | The call may set |
| 86 | .Va errno |
| 87 | to any value specified in either |
| 88 | .Xr copyin 9 |
| 89 | or |
| 90 | .Xr copyout 9 . |
| 91 | The |
| 92 | .Va pci_conf_io |
| 93 | structure consists of a number of fields: |
| 94 | .Bl -tag -width ".Fa match_buf_len" |
| 95 | .It Fa pat_buf_len |
| 96 | The length, in bytes, of the buffer filled with user-supplied patterns. |
| 97 | .It Fa num_patterns |
| 98 | The number of user-supplied patterns. |
| 99 | .It Fa patterns |
| 100 | Pointer to a buffer filled with user-supplied patterns. |
| 101 | .Fa patterns |
| 102 | is a pointer to |
| 103 | .Fa num_patterns |
| 104 | .Vt pci_match_conf |
| 105 | structures. |
| 106 | The |
| 107 | .Vt pci_match_conf |
| 108 | structure consists of the following elements: |
| 109 | .Bl -tag -width ".Fa pd_vendor" |
| 110 | .It Fa pc_sel |
| 111 | .Tn PCI |
| 112 | domain, bus, slot and function. |
| 113 | .It Fa pd_name |
| 114 | .Tn PCI |
| 115 | device driver name. |
| 116 | .It Fa pd_unit |
| 117 | .Tn PCI |
| 118 | device driver unit number. |
| 119 | .It Fa pc_vendor |
| 120 | .Tn PCI |
| 121 | vendor ID. |
| 122 | .It Fa pc_device |
| 123 | .Tn PCI |
| 124 | device ID. |
| 125 | .It Fa pc_class |
| 126 | .Tn PCI |
| 127 | device class. |
| 128 | .It Fa flags |
| 129 | The flags describe which of the fields the kernel should match against. |
| 130 | A device must match all specified fields in order to be returned. |
| 131 | The match flags are enumerated in the |
| 132 | .Vt pci_getconf_flags |
| 133 | structure. |
| 134 | Hopefully the flag values are obvious enough that they do not need to |
| 135 | described in detail. |
| 136 | .El |
| 137 | .It Fa match_buf_len |
| 138 | Length of the |
| 139 | .Fa matches |
| 140 | buffer allocated by the user to hold the results of the |
| 141 | .Dv PCIOCGETCONF |
| 142 | query. |
| 143 | .It Fa num_matches |
| 144 | Number of matches returned by the kernel. |
| 145 | .It Fa matches |
| 146 | Buffer containing matching devices returned by the kernel. |
| 147 | The items in this buffer are of type |
| 148 | .Vt pci_conf , |
| 149 | which consists of the following items: |
| 150 | .Bl -tag -width ".Fa pc_subvendor" |
| 151 | .It Fa pc_sel |
| 152 | .Tn PCI |
| 153 | domain, bus, slot and function. |
| 154 | .It Fa pc_hdr |
| 155 | .Tn PCI |
| 156 | header type. |
| 157 | .It Fa pc_subvendor |
| 158 | .Tn PCI |
| 159 | subvendor ID. |
| 160 | .It Fa pc_subdevice |
| 161 | .Tn PCI |
| 162 | subdevice ID. |
| 163 | .It Fa pc_vendor |
| 164 | .Tn PCI |
| 165 | vendor ID. |
| 166 | .It Fa pc_device |
| 167 | .Tn PCI |
| 168 | device ID. |
| 169 | .It Fa pc_class |
| 170 | .Tn PCI |
| 171 | device class. |
| 172 | .It Fa pc_subclass |
| 173 | .Tn PCI |
| 174 | device subclass. |
| 175 | .It Fa pc_progif |
| 176 | .Tn PCI |
| 177 | device programming interface. |
| 178 | .It Fa pc_revid |
| 179 | .Tn PCI |
| 180 | revision ID. |
| 181 | .It Fa pd_name |
| 182 | Driver name. |
| 183 | .It Fa pd_unit |
| 184 | Driver unit number. |
| 185 | .El |
| 186 | .It Fa offset |
| 187 | The offset is passed in by the user to tell the kernel where it should |
| 188 | start traversing the device list. |
| 189 | The value passed out by the kernel |
| 190 | points to the record immediately after the last one returned. |
| 191 | The user may |
| 192 | pass the value returned by the kernel in subsequent calls to the |
| 193 | .Dv PCIOCGETCONF |
| 194 | ioctl. |
| 195 | If the user does not intend to use the offset, it must be set to zero. |
| 196 | .It Fa generation |
| 197 | .Tn PCI |
| 198 | configuration generation. |
| 199 | This value only needs to be set if the offset is set. |
| 200 | The kernel will compare the current generation number of its internal |
| 201 | device list to the generation passed in by the user to determine whether |
| 202 | its device list has changed since the user last called the |
| 203 | .Dv PCIOCGETCONF |
| 204 | ioctl. |
| 205 | If the device list has changed, a status of |
| 206 | .Dv PCI_GETCONF_LIST_CHANGED |
| 207 | will be passed back. |
| 208 | .It Fa status |
| 209 | The status tells the user the disposition of his request for a device list. |
| 210 | The possible status values are: |
| 211 | .Bl -ohang |
| 212 | .It Dv PCI_GETCONF_LAST_DEVICE |
| 213 | This means that there are no more devices in the PCI device list after the |
| 214 | ones returned in the |
| 215 | .Fa matches |
| 216 | buffer. |
| 217 | .It Dv PCI_GETCONF_LIST_CHANGED |
| 218 | This status tells the user that the |
| 219 | .Tn PCI |
| 220 | device list has changed since his last call to the |
| 221 | .Dv PCIOCGETCONF |
| 222 | ioctl and he must reset the |
| 223 | .Fa offset |
| 224 | and |
| 225 | .Fa generation |
| 226 | to zero to start over at the beginning of the list. |
| 227 | .It Dv PCI_GETCONF_MORE_DEVS |
| 228 | This tells the user that his buffer was not large enough to hold all of the |
| 229 | remaining devices in the device list that possibly match his criteria. |
| 230 | It is possible for this status to be returned, even when none of the remaining |
| 231 | devices in the list would match the user's criteria. |
| 232 | .It Dv PCI_GETCONF_ERROR |
| 233 | This indicates a general error while servicing the user's request. |
| 234 | If the |
| 235 | .Fa pat_buf_len |
| 236 | is not equal to |
| 237 | .Fa num_patterns |
| 238 | times |
| 239 | .Fn sizeof "struct pci_match_conf" , |
| 240 | .Va errno |
| 241 | will be set to |
| 242 | .Er EINVAL . |
| 243 | .El |
| 244 | .El |
| 245 | .It Dv PCIOCREAD |
| 246 | This |
| 247 | .Xr ioctl 2 |
| 248 | reads the |
| 249 | .Tn PCI |
| 250 | configuration registers specified by the passed-in |
| 251 | .Vt pci_io |
| 252 | structure. |
| 253 | The |
| 254 | .Vt pci_io |
| 255 | structure consists of the following fields: |
| 256 | .Bl -tag -width ".Fa pi_width" |
| 257 | .It Fa pi_sel |
| 258 | A |
| 259 | .Vt pcisel |
| 260 | structure which specifies the domain, bus, slot and function the user would |
| 261 | like to query. |
| 262 | If the specific bus is not found, |
| 263 | .Va errno |
| 264 | will be set to |
| 265 | .Er ENODEV |
| 266 | and -1 returned from the ioctl. |
| 267 | .It Fa pi_reg |
| 268 | The |
| 269 | .Tn PCI |
| 270 | configuration register the user would like to access. |
| 271 | .It Fa pi_width |
| 272 | The width, in bytes, of the data the user would like to read. |
| 273 | This value may be either 1, 2, or 4. |
| 274 | 3-byte reads and reads larger than 4 bytes are not supported. |
| 275 | If an invalid width is passed, |
| 276 | .Va errno |
| 277 | will be set to |
| 278 | .Er EINVAL . |
| 279 | .It Fa pi_data |
| 280 | The data returned by the kernel. |
| 281 | .El |
| 282 | .It Dv PCIOCWRITE |
| 283 | This |
| 284 | .Xr ioctl 2 |
| 285 | allows users to write to the |
| 286 | .Tn PCI |
| 287 | specified in the passed-in |
| 288 | .Vt pci_io |
| 289 | structure. |
| 290 | The |
| 291 | .Vt pci_io |
| 292 | structure is described above. |
| 293 | The limitations on data width described for |
| 294 | reading registers, above, also apply to writing |
| 295 | .Tn PCI |
| 296 | configuration registers. |
| 297 | .El |
| 298 | .Sh FILES |
| 299 | .Bl -tag -width /dev/pci -compact |
| 300 | .It Pa /dev/pci |
| 301 | Character device for the |
| 302 | .Nm |
| 303 | driver. |
| 304 | .El |
| 305 | .Sh SEE ALSO |
| 306 | .Xr pciconf 8 |
| 307 | .Sh HISTORY |
| 308 | The |
| 309 | .Nm |
| 310 | driver (not the kernel's |
| 311 | .Tn PCI |
| 312 | support code) first appeared in |
| 313 | .Fx 2.2 , |
| 314 | and was written by Stefan Esser and Garrett Wollman. |
| 315 | Support for device listing and matching was re-implemented by |
| 316 | Kenneth Merry, and first appeared in |
| 317 | .Fx 3.0 . |
| 318 | .Sh AUTHORS |
| 319 | .An Kenneth Merry Aq ken@FreeBSD.org |
| 320 | .Sh BUGS |
| 321 | It is not possible for users to specify an accurate offset into the device |
| 322 | list without calling the |
| 323 | .Dv PCIOCGETCONF |
| 324 | at least once, since they have no way of knowing the current generation |
| 325 | number otherwise. |
| 326 | This probably is not a serious problem, though, since |
| 327 | users can easily narrow their search by specifying a pattern or patterns |
| 328 | for the kernel to match against. |