Commit | Line | Data |
---|---|---|
28bcadf0 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ============================================ | |
1da177e4 | 4 | Accessing PCI device resources through sysfs |
28bcadf0 | 5 | ============================================ |
1da177e4 LT |
6 | |
7 | sysfs, usually mounted at /sys, provides access to PCI resources on platforms | |
28bcadf0 | 8 | that support it. For example, a given bus might look like this:: |
1da177e4 LT |
9 | |
10 | /sys/devices/pci0000:17 | |
11 | |-- 0000:17:00.0 | |
12 | | |-- class | |
13 | | |-- config | |
1da177e4 | 14 | | |-- device |
97c44836 | 15 | | |-- enable |
1da177e4 LT |
16 | | |-- irq |
17 | | |-- local_cpus | |
77c27c7b | 18 | | |-- remove |
1da177e4 LT |
19 | | |-- resource |
20 | | |-- resource0 | |
21 | | |-- resource1 | |
22 | | |-- resource2 | |
702ed3be | 23 | | |-- revision |
1da177e4 LT |
24 | | |-- rom |
25 | | |-- subsystem_device | |
26 | | |-- subsystem_vendor | |
27 | | `-- vendor | |
0b405a0f | 28 | `-- ... |
1da177e4 LT |
29 | |
30 | The topmost element describes the PCI domain and bus number. In this case, | |
31 | the domain number is 0000 and the bus number is 17 (both values are in hex). | |
32 | This bus contains a single function device in slot 0. The domain and bus | |
33 | numbers are reproduced for convenience. Under the device directory are several | |
34 | files, each with their own function. | |
35 | ||
28bcadf0 | 36 | =================== ===================================================== |
1da177e4 | 37 | file function |
28bcadf0 | 38 | =================== ===================================================== |
1da177e4 LT |
39 | class PCI class (ascii, ro) |
40 | config PCI config space (binary, rw) | |
1da177e4 | 41 | device PCI device (ascii, ro) |
97c44836 | 42 | enable Whether the device is enabled (ascii, rw) |
1da177e4 LT |
43 | irq IRQ number (ascii, ro) |
44 | local_cpus nearby CPU mask (cpumask, ro) | |
77c27c7b | 45 | remove remove device from kernel's list (ascii, wo) |
1da177e4 | 46 | resource PCI resource host addresses (ascii, ro) |
28bcadf0 | 47 | resource0..N PCI resource N, if present (binary, mmap, rw\ [1]_) |
45aec1ae | 48 | resource0_wc..N_wc PCI WC map resource N, if prefetchable (binary, mmap) |
702ed3be | 49 | revision PCI revision (ascii, ro) |
1da177e4 LT |
50 | rom PCI ROM resource, if present (binary, ro) |
51 | subsystem_device PCI subsystem device (ascii, ro) | |
52 | subsystem_vendor PCI subsystem vendor (ascii, ro) | |
53 | vendor PCI vendor (ascii, ro) | |
28bcadf0 MCC |
54 | =================== ===================================================== |
55 | ||
56 | :: | |
1da177e4 LT |
57 | |
58 | ro - read only file | |
59 | rw - file is readable and writable | |
77c27c7b | 60 | wo - write only file |
1da177e4 LT |
61 | mmap - file is mmapable |
62 | ascii - file contains ascii text | |
63 | binary - file contains binary data | |
64 | cpumask - file contains a cpumask type | |
65 | ||
e3363a0d | 66 | .. [1] rw for IORESOURCE_IO (I/O port) regions only |
8633328b | 67 | |
5d135dff JB |
68 | The read only files are informational, writes to them will be ignored, with |
69 | the exception of the 'rom' file. Writable files can be used to perform | |
70 | actions on the device (e.g. changing config space, detaching a device). | |
71 | mmapable files are available via an mmap of the file at offset 0 and can be | |
72 | used to do actual device programming from userspace. Note that some platforms | |
73 | don't support mmapping of certain resources, so be sure to check the return | |
8633328b AW |
74 | value from any attempted mmap. The most notable of these are I/O port |
75 | resources, which also provide read/write access. | |
5d135dff | 76 | |
28bcadf0 | 77 | The 'enable' file provides a counter that indicates how many times the device |
97c44836 TN |
78 | has been enabled. If the 'enable' file currently returns '4', and a '1' is |
79 | echoed into it, it will then return '5'. Echoing a '0' into it will decrease | |
80 | the count. Even when it returns to 0, though, some of the initialisation | |
28bcadf0 | 81 | may not be reversed. |
97c44836 | 82 | |
5d135dff JB |
83 | The 'rom' file is special in that it provides read-only access to the device's |
84 | ROM file, if available. It's disabled by default, however, so applications | |
85 | should write the string "1" to the file to enable it before attempting a read | |
97c44836 | 86 | call, and disable it following the access by writing "0" to the file. Note |
19f59460 | 87 | that the device must be enabled for a rom read to return data successfully. |
97c44836 TN |
88 | In the event a driver is not bound to the device, it can be enabled using the |
89 | 'enable' file, documented above. | |
1da177e4 | 90 | |
77c27c7b AC |
91 | The 'remove' file is used to remove the PCI device, by writing a non-zero |
92 | integer to the file. This does not involve any kind of hot-plug functionality, | |
93 | e.g. powering off the device. The device is removed from the kernel's list of | |
94 | PCI devices, the sysfs directory for it is removed, and the device will be | |
95 | removed from any drivers attached to it. Removal of PCI root buses is | |
96 | disallowed. | |
97 | ||
1da177e4 | 98 | Accessing legacy resources through sysfs |
5d135dff | 99 | ---------------------------------------- |
1da177e4 LT |
100 | |
101 | Legacy I/O port and ISA memory resources are also provided in sysfs if the | |
1b3c3714 | 102 | underlying platform supports them. They're located in the PCI class hierarchy, |
28bcadf0 | 103 | e.g.:: |
1da177e4 LT |
104 | |
105 | /sys/class/pci_bus/0000:17/ | |
106 | |-- bridge -> ../../../devices/pci0000:17 | |
107 | |-- cpuaffinity | |
108 | |-- legacy_io | |
109 | `-- legacy_mem | |
110 | ||
111 | The legacy_io file is a read/write file that can be used by applications to | |
112 | do legacy port I/O. The application should open the file, seek to the desired | |
113 | port (e.g. 0x3e8) and do a read or a write of 1, 2 or 4 bytes. The legacy_mem | |
114 | file should be mmapped with an offset corresponding to the memory offset | |
115 | desired, e.g. 0xa0000 for the VGA frame buffer. The application can then | |
116 | simply dereference the returned pointer (after checking for errors of course) | |
117 | to access legacy memory space. | |
118 | ||
119 | Supporting PCI access on new platforms | |
5d135dff | 120 | -------------------------------------- |
1da177e4 LT |
121 | |
122 | In order to support PCI resource mapping as described above, Linux platform | |
f7195824 DW |
123 | code should ideally define ARCH_GENERIC_PCI_MMAP_RESOURCE and use the generic |
124 | implementation of that functionality. To support the historical interface of | |
125 | mmap() through files in /proc/bus/pci, platforms may also set HAVE_PCI_MMAP. | |
126 | ||
127 | Alternatively, platforms which set HAVE_PCI_MMAP may provide their own | |
128 | implementation of pci_mmap_page_range() instead of defining | |
129 | ARCH_GENERIC_PCI_MMAP_RESOURCE. | |
1da177e4 | 130 | |
ae749c7a DW |
131 | Platforms which support write-combining maps of PCI resources must define |
132 | arch_can_pci_mmap_wc() which shall evaluate to non-zero at runtime when | |
e854d8b2 DW |
133 | write-combining is permitted. Platforms which support maps of I/O resources |
134 | define arch_can_pci_mmap_io() similarly. | |
ae749c7a | 135 | |
1da177e4 LT |
136 | Legacy resources are protected by the HAVE_PCI_LEGACY define. Platforms |
137 | wishing to support legacy functionality should define it and provide | |
0b405a0f | 138 | pci_legacy_read, pci_legacy_write and pci_mmap_legacy_page_range functions. |