tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1Accessing PCI device resources through sysfs
2
3sysfs, usually mounted at /sys, provides access to PCI resources on platforms
4that 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
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
21 `-- ...
22
23The topmost element describes the PCI domain and bus number. In this case,
24the domain number is 0000 and the bus number is 17 (both values are in hex).
25This bus contains a single function device in slot 0. The domain and bus
26numbers are reproduced for convenience. Under the device directory are several
27files, each with their own function.
28
29 file function
30 ---- --------
31 class PCI class (ascii, ro)
32 config PCI config space (binary, rw)
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
50The read only files are informational, writes to them will be ignored.
51Writable files can be used to perform actions on the device (e.g. changing
52config space, detaching a device). mmapable files are available via an
53mmap of the file at offset 0 and can be used to do actual device programming
54from userspace. Note that some platforms don't support mmapping of certain
55resources, so be sure to check the return value from any attempted mmap.
56
57Accessing legacy resources through sysfs
58
59Legacy I/O port and ISA memory resources are also provided in sysfs if the
60underlying platform supports them. They're located in the PCI class heirarchy,
61e.g.
62
63 /sys/class/pci_bus/0000:17/
64 |-- bridge -> ../../../devices/pci0000:17
65 |-- cpuaffinity
66 |-- legacy_io
67 `-- legacy_mem
68
69The legacy_io file is a read/write file that can be used by applications to
70do legacy port I/O. The application should open the file, seek to the desired
71port (e.g. 0x3e8) and do a read or a write of 1, 2 or 4 bytes. The legacy_mem
72file should be mmapped with an offset corresponding to the memory offset
73desired, e.g. 0xa0000 for the VGA frame buffer. The application can then
74simply dereference the returned pointer (after checking for errors of course)
75to access legacy memory space.
76
77Supporting PCI access on new platforms
78
79In order to support PCI resource mapping as described above, Linux platform
80code must define HAVE_PCI_MMAP and provide a pci_mmap_page_range function.
81Platforms are free to only support subsets of the mmap functionality, but
82useful return codes should be provided.
83
84Legacy resources are protected by the HAVE_PCI_LEGACY define. Platforms
85wishing to support legacy functionality should define it and provide
86pci_legacy_read, pci_legacy_write and pci_mmap_legacy_page_range functions.