| pci.4 (c0c7deaa94312540254b0231608a89cff45f9c2f) | pci.4 (64ae346b521983a6fc2f72b795b5c8ae101ddac1) |
|---|---|
| 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 --- 8 unchanged lines hidden (view full) --- 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.\" | 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 --- 8 unchanged lines hidden (view full) --- 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$ | 25.\" $FreeBSD$ |
| 26.\" | 26.\" |
| 27.Dd January 3, 2008 | 27.Dd October 24, 1999 |
| 28.Dt PCI 4 | 28.Dt PCI 4 |
| 29.Os | 29.Os FreeBSD 4.0 |
| 30.Sh NAME 31.Nm pci | 30.Sh NAME 31.Nm pci |
| 32.Nd generic PCI driver 33.Sh SYNOPSIS 34.Cd device pci | 32.Nd Generic PCI driver 33.Sh SYNOPSYIS 34.Cd controller pci0 |
| 35.Sh DESCRIPTION 36The | 35.Sh DESCRIPTION 36The |
| 37.Nm | 37.Nm pci |
| 38driver provides a way for userland programs to read and write 39.Tn PCI | 38driver provides a way for userland programs to read and write 39.Tn PCI |
| 40configuration registers. 41It also provides a way for userland programs to get a list of all | 40configuration registers. It also provides a way for userland programs to 41get a list of all |
| 42.Tn PCI 43devices, or all 44.Tn PCI 45devices that match various patterns. 46.Pp 47Since the | 42.Tn PCI 43devices, or all 44.Tn PCI 45devices that match various patterns. 46.Pp 47Since the |
| 48.Nm | 48.Nm pci |
| 49driver provides a write interface for 50.Tn PCI 51configuration registers, system administrators should exercise caution when 52granting access to the | 49driver provides a write interface for 50.Tn PCI 51configuration registers, system administrators should exercise caution when 52granting access to the |
| 53.Nm 54device. 55If used improperly, this driver can allow userland applications to | 53.Nm pci 54device. If used improperly, this driver can allow userland applications to |
| 56crash a machine or cause data loss. | 55crash a machine or cause data loss. |
| 57.Pp 58The 59.Nm 60driver implements the 61.Tn PCI 62bus in the kernel. 63It enumerates any devices on the 64.Tn PCI 65bus and gives 66.Tn PCI 67client drivers the chance to attach to them. 68It assigns resources to children, when the BIOS does not. 69It takes care of routing interrupts when necessary. 70It reprobes the unattached 71.Tn PCI 72children when 73.Tn PCI 74client drivers are dynamically 75loaded at runtime. | |
| 76.Sh KERNEL CONFIGURATION | 56.Sh KERNEL CONFIGURATION |
| 77The 78.Nm 79device is included in the kernel as described in the SYNOPSIS section. 80The 81.Nm 82driver cannot be built as a 83.Xr kld 4 . | 57It is only necessary to specify one 58.Nm pci 59controller in the kernel. Additional 60.Tn PCI 61busses are handled automatically as they are encountered. |
| 84.Sh IOCTLS 85The following 86.Xr ioctl 2 87calls are supported by the | 62.Sh IOCTLS 63The following 64.Xr ioctl 2 65calls are supported by the |
| 88.Nm 89driver. 90They are defined in the header file 91.In sys/pciio.h . | 66.Nm pci 67driver. They are defined in the header file 68.Aq Pa sys/pciio.h . |
| 92.Bl -tag -width 012345678901234 93.Pp 94.It PCIOCGETCONF 95This 96.Xr ioctl 2 97takes a 98.Va pci_conf_io | 69.Bl -tag -width 012345678901234 70.Pp 71.It PCIOCGETCONF 72This 73.Xr ioctl 2 74takes a 75.Va pci_conf_io |
| 99structure. 100It allows the user to retrieve information on all | 76structure. It allows the user to retrieve information on all |
| 101.Tn PCI 102devices in the system, or on 103.Tn PCI 104devices matching patterns supplied by the user. | 77.Tn PCI 78devices in the system, or on 79.Tn PCI 80devices matching patterns supplied by the user. |
| 105The call may set 106.Va errno 107to any value specified in either 108.Xr copyin 9 109or 110.Xr copyout 9 . | |
| 111The 112.Va pci_conf_io 113structure consists of a number of fields: 114.Bl -tag -width match_buf_len 115.It pat_buf_len 116The length, in bytes, of the buffer filled with user-supplied patterns. 117.It num_patterns 118The number of user-supplied patterns. 119.It patterns 120Pointer to a buffer filled with user-supplied patterns. 121.Va patterns 122is a pointer to 123.Va num_patterns 124.Va pci_match_conf | 81The 82.Va pci_conf_io 83structure consists of a number of fields: 84.Bl -tag -width match_buf_len 85.It pat_buf_len 86The length, in bytes, of the buffer filled with user-supplied patterns. 87.It num_patterns 88The number of user-supplied patterns. 89.It patterns 90Pointer to a buffer filled with user-supplied patterns. 91.Va patterns 92is a pointer to 93.Va num_patterns 94.Va pci_match_conf |
| 125structures. 126The | 95structures. The |
| 127.Va pci_match_conf 128structure consists of the following elements: 129.Bl -tag -width pd_vendor 130.It pc_sel 131.Tn PCI | 96.Va pci_match_conf 97structure consists of the following elements: 98.Bl -tag -width pd_vendor 99.It pc_sel 100.Tn PCI |
| 132domain, bus, slot and function. | 101bus, slot and function. |
| 133.It pd_name 134.Tn PCI 135device driver name. 136.It pd_unit 137.Tn PCI 138device driver unit number. 139.It pc_vendor 140.Tn PCI 141vendor ID. 142.It pc_device 143.Tn PCI 144device ID. 145.It pc_class 146.Tn PCI 147device class. 148.It flags 149The flags describe which of the fields the kernel should match against. | 102.It pd_name 103.Tn PCI 104device driver name. 105.It pd_unit 106.Tn PCI 107device driver unit number. 108.It pc_vendor 109.Tn PCI 110vendor ID. 111.It pc_device 112.Tn PCI 113device ID. 114.It pc_class 115.Tn PCI 116device class. 117.It flags 118The flags describe which of the fields the kernel should match against. |
| 150A device must match all specified fields in order to be returned. 151The match flags are enumerated in the 152.Va pci_getconf_flags | 119A device must match all specified fields in order to be returned. The 120match flags are enumerated in the 121.Va pci_getconf_flags |
| 153structure. | 122structure. |
| 154Hopefully the flag values are obvious enough that they do not need to | 123Hopefully the flag values are obvious enough that they don't need to |
| 155described in detail. 156.El 157.It match_buf_len 158Length of the 159.Va matches 160buffer allocated by the user to hold the results of the 161.Dv PCIOCGETCONF 162query. 163.It num_matches 164Number of matches returned by the kernel. 165.It matches | 124described in detail. 125.El 126.It match_buf_len 127Length of the 128.Va matches 129buffer allocated by the user to hold the results of the 130.Dv PCIOCGETCONF 131query. 132.It num_matches 133Number of matches returned by the kernel. 134.It matches |
| 166Buffer containing matching devices returned by the kernel. 167The items in this buffer are of type 168.Va pci_conf , | 135Buffer containing matching devices returned by the kernel. The items in 136this buffer are of type 137.Va pci_conf , |
| 169which consists of the following items: 170.Bl -tag -width pc_subvendor 171.It pc_sel 172.Tn PCI | 138which consists of the following items: 139.Bl -tag -width pc_subvendor 140.It pc_sel 141.Tn PCI |
| 173domain, bus, slot and function. | 142bus, slot and function. |
| 174.It pc_hdr 175.Tn PCI 176header type. 177.It pc_subvendor 178.Tn PCI 179subvendor ID. 180.It pc_subdevice 181.Tn PCI --- 18 unchanged lines hidden (view full) --- 200revision ID. 201.It pd_name 202Driver name. 203.It pd_unit 204Driver unit number. 205.El 206.It offset 207The offset is passed in by the user to tell the kernel where it should | 143.It pc_hdr 144.Tn PCI 145header type. 146.It pc_subvendor 147.Tn PCI 148subvendor ID. 149.It pc_subdevice 150.Tn PCI --- 18 unchanged lines hidden (view full) --- 169revision ID. 170.It pd_name 171Driver name. 172.It pd_unit 173Driver unit number. 174.El 175.It offset 176The offset is passed in by the user to tell the kernel where it should |
| 208start traversing the device list. 209The value passed out by the kernel 210points to the record immediately after the last one returned. 211The user may | 177start traversing the device list. The value passed out by the kernel 178points to the record immediately after the last one returned. The user may |
| 212pass the value returned by the kernel in subsequent calls to the 213.Dv PCIOCGETCONF | 179pass the value returned by the kernel in subsequent calls to the 180.Dv PCIOCGETCONF |
| 214ioctl. 215If the user does not intend to use the offset, it must be set to zero. | 181ioctl. If the user does not intend to use the offset, it must be set to 182zero. |
| 216.It generation 217.Tn PCI | 183.It generation 184.Tn PCI |
| 218configuration generation. 219This value only needs to be set if the offset is set. 220The kernel will compare the current generation number of its internal | 185configuration generation. This value only needs to be set if the offset is 186set. The kernel will compare the current generation number of its internal |
| 221device list to the generation passed in by the user to determine whether 222its device list has changed since the user last called the 223.Dv PCIOCGETCONF | 187device list to the generation passed in by the user to determine whether 188its device list has changed since the user last called the 189.Dv PCIOCGETCONF |
| 224ioctl. 225If the device list has changed, a status of | 190ioctl. If the device list has changed, a status of |
| 226.Va PCI_GETCONF_LIST_CHANGED 227will be passed back. 228.It status 229The status tells the user the disposition of his request for a device list. 230The possible status values are: 231.Bl -ohang 232.It PCI_GETCONF_LAST_DEVICE 233This means that there are no more devices in the PCI device list after the 234ones returned in the 235.Va matches 236buffer. 237.It PCI_GETCONF_LIST_CHANGED 238This status tells the user that the 239.Tn PCI | 191.Va PCI_GETCONF_LIST_CHANGED 192will be passed back. 193.It status 194The status tells the user the disposition of his request for a device list. 195The possible status values are: 196.Bl -ohang 197.It PCI_GETCONF_LAST_DEVICE 198This means that there are no more devices in the PCI device list after the 199ones returned in the 200.Va matches 201buffer. 202.It PCI_GETCONF_LIST_CHANGED 203This status tells the user that the 204.Tn PCI |
| 240device list has changed since his last call to the | 205device list has changed since his last call to the |
| 241.Dv PCIOCGETCONF 242ioctl and he must reset the 243.Va offset 244and 245.Va generation 246to zero to start over at the beginning of the list. 247.It PCI_GETCONF_MORE_DEVS 248This tells the user that his buffer was not large enough to hold all of the | 206.Dv PCIOCGETCONF 207ioctl and he must reset the 208.Va offset 209and 210.Va generation 211to zero to start over at the beginning of the list. 212.It PCI_GETCONF_MORE_DEVS 213This tells the user that his buffer was not large enough to hold all of the |
| 249remaining devices in the device list that possibly match his criteria. 250It is possible for this status to be returned, even when none of the remaining | 214remaining devices in the device list that possibly match his criteria. It 215is possible for this status to be returned, even when none of the remaining |
| 251devices in the list would match the user's criteria. 252.It PCI_GETCONF_ERROR | 216devices in the list would match the user's criteria. 217.It PCI_GETCONF_ERROR |
| 253This indicates a general error while servicing the user's request. 254If the 255.Va pat_buf_len 256is not equal to 257.Va num_patterns 258times 259.Fn sizeof "struct pci_match_conf" , 260.Va errno 261will be set to 262.Er EINVAL . | 218This indicates a general error while servicing the user's request. A more 219specific indication of the problem may or may not be printed in the kernel 220message buffer (and by implication, the system console). |
| 263.El 264.El 265.It PCIOCREAD 266This 267.Xr ioctl 2 268reads the 269.Tn PCI 270configuration registers specified by the passed-in 271.Va pci_io | 221.El 222.El 223.It PCIOCREAD 224This 225.Xr ioctl 2 226reads the 227.Tn PCI 228configuration registers specified by the passed-in 229.Va pci_io |
| 272structure. 273The | 230structure. The |
| 274.Va pci_io 275structure consists of the following fields: 276.Bl -tag -width pi_width 277.It pi_sel 278A 279.Va pcisel | 231.Va pci_io 232structure consists of the following fields: 233.Bl -tag -width pi_width 234.It pi_sel 235A 236.Va pcisel |
| 280structure which specifies the domain, bus, slot and function the user would 281like to query. 282If the specific bus is not found, errno will be set to ENODEV and -1 returned 283from the ioctl. | 237structure which specifies the bus, slot and function the user would like to 238query. |
| 284.It pi_reg 285The 286.Tn PCI 287configuration register the user would like to access. 288.It pi_width | 239.It pi_reg 240The 241.Tn PCI 242configuration register the user would like to access. 243.It pi_width |
| 289The width, in bytes, of the data the user would like to read. 290This value 291may be either 1, 2, or 4. 2923-byte reads and reads larger than 4 bytes are | 244The width, in bytes, of the data the user would like to read. This value 245may be either 1, 2, or 4. 3-byte reads and reads larger than 4 bytes are |
| 293not supported. | 246not supported. |
| 294If an invalid width is passed, errno will be set to EINVAL. | |
| 295.It pi_data 296The data returned by the kernel. 297.El 298.It PCIOCWRITE 299This 300.Xr ioctl 2 301allows users to write to the 302.Tn PCI 303specified in the passed-in 304.Va pci_io | 247.It pi_data 248The data returned by the kernel. 249.El 250.It PCIOCWRITE 251This 252.Xr ioctl 2 253allows users to write to the 254.Tn PCI 255specified in the passed-in 256.Va pci_io |
| 305structure. 306The | 257structure. The |
| 307.Va pci_io | 258.Va pci_io |
| 308structure is described above. 309The limitations on data width described for | 259structure is described above. The limitations on data width described for |
| 310reading registers, above, also apply to writing 311.Tn PCI 312configuration registers. 313.El 314.Sh FILES | 260reading registers, above, also apply to writing 261.Tn PCI 262configuration registers. 263.El 264.Sh FILES |
| 315.Bl -tag -width /dev/pci -compact | 265.Bl -tag -width 01234567890 -compact |
| 316.It Pa /dev/pci 317Character device for the | 266.It Pa /dev/pci 267Character device for the |
| 318.Nm | 268.Nm pci |
| 319driver. 320.El | 269driver. 270.El |
| 271.Sh DIAGNOSTICS 272None. |
|
| 321.Sh SEE ALSO 322.Xr pciconf 8 323.Sh HISTORY 324The | 273.Sh SEE ALSO 274.Xr pciconf 8 275.Sh HISTORY 276The |
| 325.Nm | 277.Nm pci |
| 326driver (not the kernel's 327.Tn PCI 328support code) first appeared in 329.Fx 2.2 , 330and was written by Stefan Esser and Garrett Wollman. 331Support for device listing and matching was re-implemented by 332Kenneth Merry, and first appeared in 333.Fx 3.0 . 334.Sh AUTHORS | 278driver (not the kernel's 279.Tn PCI 280support code) first appeared in 281.Fx 2.2 , 282and was written by Stefan Esser and Garrett Wollman. 283Support for device listing and matching was re-implemented by 284Kenneth Merry, and first appeared in 285.Fx 3.0 . 286.Sh AUTHORS |
| 335.An Kenneth Merry Aq ken@FreeBSD.org | 287.An Kenneth Merry Aq ken@FreeBSD.ORG |
| 336.Sh BUGS | 288.Sh BUGS |
| 337It is not possible for users to specify an accurate offset into the device | 289It isn't possible for users to specify an accurate offset into the device |
| 338list without calling the 339.Dv PCIOCGETCONF 340at least once, since they have no way of knowing the current generation | 290list without calling the 291.Dv PCIOCGETCONF 292at least once, since they have no way of knowing the current generation |
| 341number otherwise. 342This probably is not a serious problem, though, since | 293number otherwise. This probably isn't a serious problem, though, since |
| 343users can easily narrow their search by specifying a pattern or patterns 344for the kernel to match against. | 294users can easily narrow their search by specifying a pattern or patterns 295for the kernel to match against. |