Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | Accessing PCI device resources through sysfs |
2 | ||
3 | sysfs, usually mounted at /sys, provides access to PCI resources on platforms | |
4 | that support it. For example, a given bus might look like this: | |
5 | ||
6 | /sys/devices/pci0000:17 | |
7 | |-- 0000:17:00.0 | |
8 | | |-- class | |
9 | | |-- config | |
1da177e4 LT |
10 | | |-- device |
11 | | |-- irq | |
12 | | |-- local_cpus | |
13 | | |-- resource | |
14 | | |-- resource0 | |
15 | | |-- resource1 | |
16 | | |-- resource2 | |
17 | | |-- rom | |
18 | | |-- subsystem_device | |
19 | | |-- subsystem_vendor | |
20 | | `-- vendor | |
0b405a0f | 21 | `-- ... |
1da177e4 LT |
22 | |
23 | The topmost element describes the PCI domain and bus number. In this case, | |
24 | the domain number is 0000 and the bus number is 17 (both values are in hex). | |
25 | This bus contains a single function device in slot 0. The domain and bus | |
26 | numbers are reproduced for convenience. Under the device directory are several | |
27 | files, each with their own function. | |
28 | ||
29 | file function | |
30 | ---- -------- | |
31 | class PCI class (ascii, ro) | |
32 | config PCI config space (binary, rw) | |
1da177e4 LT |
33 | device PCI device (ascii, ro) |
34 | irq IRQ number (ascii, ro) | |
35 | local_cpus nearby CPU mask (cpumask, ro) | |
36 | resource PCI resource host addresses (ascii, ro) | |
37 | resource0..N PCI resource N, if present (binary, mmap) | |
38 | rom PCI ROM resource, if present (binary, ro) | |
39 | subsystem_device PCI subsystem device (ascii, ro) | |
40 | subsystem_vendor PCI subsystem vendor (ascii, ro) | |
41 | vendor PCI vendor (ascii, ro) | |
42 | ||
43 | ro - read only file | |
44 | rw - file is readable and writable | |
45 | mmap - file is mmapable | |
46 | ascii - file contains ascii text | |
47 | binary - file contains binary data | |
48 | cpumask - file contains a cpumask type | |
49 | ||
50 | The read only files are informational, writes to them will be ignored. | |
51 | Writable files can be used to perform actions on the device (e.g. changing | |
52 | config space, detaching a device). mmapable files are available via an | |
53 | mmap of the file at offset 0 and can be used to do actual device programming | |
54 | from userspace. Note that some platforms don't support mmapping of certain | |
55 | resources, so be sure to check the return value from any attempted mmap. | |
56 | ||
57 | Accessing legacy resources through sysfs | |
58 | ||
59 | Legacy I/O port and ISA memory resources are also provided in sysfs if the | |
60 | underlying platform supports them. They're located in the PCI class heirarchy, | |
61 | e.g. | |
62 | ||
63 | /sys/class/pci_bus/0000:17/ | |
64 | |-- bridge -> ../../../devices/pci0000:17 | |
65 | |-- cpuaffinity | |
66 | |-- legacy_io | |
67 | `-- legacy_mem | |
68 | ||
69 | The legacy_io file is a read/write file that can be used by applications to | |
70 | do legacy port I/O. The application should open the file, seek to the desired | |
71 | port (e.g. 0x3e8) and do a read or a write of 1, 2 or 4 bytes. The legacy_mem | |
72 | file should be mmapped with an offset corresponding to the memory offset | |
73 | desired, e.g. 0xa0000 for the VGA frame buffer. The application can then | |
74 | simply dereference the returned pointer (after checking for errors of course) | |
75 | to access legacy memory space. | |
76 | ||
77 | Supporting PCI access on new platforms | |
78 | ||
79 | In order to support PCI resource mapping as described above, Linux platform | |
80 | code must define HAVE_PCI_MMAP and provide a pci_mmap_page_range function. | |
81 | Platforms are free to only support subsets of the mmap functionality, but | |
82 | useful return codes should be provided. | |
83 | ||
84 | Legacy resources are protected by the HAVE_PCI_LEGACY define. Platforms | |
85 | wishing to support legacy functionality should define it and provide | |
0b405a0f | 86 | pci_legacy_read, pci_legacy_write and pci_mmap_legacy_page_range functions. |