Root/
1 | Accessing PCI device resources through sysfs |
2 | -------------------------------------------- |
3 | |
4 | sysfs, usually mounted at /sys, provides access to PCI resources on platforms |
5 | that support it. For example, a given bus might look like this: |
6 | |
7 | /sys/devices/pci0000:17 |
8 | |-- 0000:17:00.0 |
9 | | |-- class |
10 | | |-- config |
11 | | |-- device |
12 | | |-- enable |
13 | | |-- irq |
14 | | |-- local_cpus |
15 | | |-- remove |
16 | | |-- resource |
17 | | |-- resource0 |
18 | | |-- resource1 |
19 | | |-- resource2 |
20 | | |-- rom |
21 | | |-- subsystem_device |
22 | | |-- subsystem_vendor |
23 | | `-- vendor |
24 | `-- ... |
25 | |
26 | The topmost element describes the PCI domain and bus number. In this case, |
27 | the domain number is 0000 and the bus number is 17 (both values are in hex). |
28 | This bus contains a single function device in slot 0. The domain and bus |
29 | numbers are reproduced for convenience. Under the device directory are several |
30 | files, each with their own function. |
31 | |
32 | file function |
33 | ---- -------- |
34 | class PCI class (ascii, ro) |
35 | config PCI config space (binary, rw) |
36 | device PCI device (ascii, ro) |
37 | enable Whether the device is enabled (ascii, rw) |
38 | irq IRQ number (ascii, ro) |
39 | local_cpus nearby CPU mask (cpumask, ro) |
40 | remove remove device from kernel's list (ascii, wo) |
41 | resource PCI resource host addresses (ascii, ro) |
42 | resource0..N PCI resource N, if present (binary, mmap, rw[1]) |
43 | resource0_wc..N_wc PCI WC map resource N, if prefetchable (binary, mmap) |
44 | rom PCI ROM resource, if present (binary, ro) |
45 | subsystem_device PCI subsystem device (ascii, ro) |
46 | subsystem_vendor PCI subsystem vendor (ascii, ro) |
47 | vendor PCI vendor (ascii, ro) |
48 | |
49 | ro - read only file |
50 | rw - file is readable and writable |
51 | wo - write only file |
52 | mmap - file is mmapable |
53 | ascii - file contains ascii text |
54 | binary - file contains binary data |
55 | cpumask - file contains a cpumask type |
56 | |
57 | [1] rw for RESOURCE_IO (I/O port) regions only |
58 | |
59 | The read only files are informational, writes to them will be ignored, with |
60 | the exception of the 'rom' file. Writable files can be used to perform |
61 | actions on the device (e.g. changing config space, detaching a device). |
62 | mmapable files are available via an mmap of the file at offset 0 and can be |
63 | used to do actual device programming from userspace. Note that some platforms |
64 | don't support mmapping of certain resources, so be sure to check the return |
65 | value from any attempted mmap. The most notable of these are I/O port |
66 | resources, which also provide read/write access. |
67 | |
68 | The 'enable' file provides a counter that indicates how many times the device |
69 | has been enabled. If the 'enable' file currently returns '4', and a '1' is |
70 | echoed into it, it will then return '5'. Echoing a '0' into it will decrease |
71 | the count. Even when it returns to 0, though, some of the initialisation |
72 | may not be reversed. |
73 | |
74 | The 'rom' file is special in that it provides read-only access to the device's |
75 | ROM file, if available. It's disabled by default, however, so applications |
76 | should write the string "1" to the file to enable it before attempting a read |
77 | call, and disable it following the access by writing "0" to the file. Note |
78 | that the device must be enabled for a rom read to return data successfully. |
79 | In the event a driver is not bound to the device, it can be enabled using the |
80 | 'enable' file, documented above. |
81 | |
82 | The 'remove' file is used to remove the PCI device, by writing a non-zero |
83 | integer to the file. This does not involve any kind of hot-plug functionality, |
84 | e.g. powering off the device. The device is removed from the kernel's list of |
85 | PCI devices, the sysfs directory for it is removed, and the device will be |
86 | removed from any drivers attached to it. Removal of PCI root buses is |
87 | disallowed. |
88 | |
89 | Accessing legacy resources through sysfs |
90 | ---------------------------------------- |
91 | |
92 | Legacy I/O port and ISA memory resources are also provided in sysfs if the |
93 | underlying platform supports them. They're located in the PCI class hierarchy, |
94 | e.g. |
95 | |
96 | /sys/class/pci_bus/0000:17/ |
97 | |-- bridge -> ../../../devices/pci0000:17 |
98 | |-- cpuaffinity |
99 | |-- legacy_io |
100 | `-- legacy_mem |
101 | |
102 | The legacy_io file is a read/write file that can be used by applications to |
103 | do legacy port I/O. The application should open the file, seek to the desired |
104 | port (e.g. 0x3e8) and do a read or a write of 1, 2 or 4 bytes. The legacy_mem |
105 | file should be mmapped with an offset corresponding to the memory offset |
106 | desired, e.g. 0xa0000 for the VGA frame buffer. The application can then |
107 | simply dereference the returned pointer (after checking for errors of course) |
108 | to access legacy memory space. |
109 | |
110 | Supporting PCI access on new platforms |
111 | -------------------------------------- |
112 | |
113 | In order to support PCI resource mapping as described above, Linux platform |
114 | code must define HAVE_PCI_MMAP and provide a pci_mmap_page_range function. |
115 | Platforms are free to only support subsets of the mmap functionality, but |
116 | useful return codes should be provided. |
117 | |
118 | Legacy resources are protected by the HAVE_PCI_LEGACY define. Platforms |
119 | wishing to support legacy functionality should define it and provide |
120 | pci_legacy_read, pci_legacy_write and pci_mmap_legacy_page_range functions. |
121 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9