0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ============================================
0004 Accessing PCI device resources through sysfs
0005 ============================================
0006
0007 sysfs, usually mounted at /sys, provides access to PCI resources on platforms
0008 that support it. For example, a given bus might look like this::
0009
0010 /sys/devices/pci0000:17
0011 |-- 0000:17:00.0
0012 | |-- class
0013 | |-- config
0014 | |-- device
0015 | |-- enable
0016 | |-- irq
0017 | |-- local_cpus
0018 | |-- remove
0019 | |-- resource
0020 | |-- resource0
0021 | |-- resource1
0022 | |-- resource2
0023 | |-- revision
0024 | |-- rom
0025 | |-- subsystem_device
0026 | |-- subsystem_vendor
0027 | `-- vendor
0028 `-- ...
0029
0030 The topmost element describes the PCI domain and bus number. In this case,
0031 the domain number is 0000 and the bus number is 17 (both values are in hex).
0032 This bus contains a single function device in slot 0. The domain and bus
0033 numbers are reproduced for convenience. Under the device directory are several
0034 files, each with their own function.
0035
0036 =================== =====================================================
0037 file function
0038 =================== =====================================================
0039 class PCI class (ascii, ro)
0040 config PCI config space (binary, rw)
0041 device PCI device (ascii, ro)
0042 enable Whether the device is enabled (ascii, rw)
0043 irq IRQ number (ascii, ro)
0044 local_cpus nearby CPU mask (cpumask, ro)
0045 remove remove device from kernel's list (ascii, wo)
0046 resource PCI resource host addresses (ascii, ro)
0047 resource0..N PCI resource N, if present (binary, mmap, rw\ [1]_)
0048 resource0_wc..N_wc PCI WC map resource N, if prefetchable (binary, mmap)
0049 revision PCI revision (ascii, ro)
0050 rom PCI ROM resource, if present (binary, ro)
0051 subsystem_device PCI subsystem device (ascii, ro)
0052 subsystem_vendor PCI subsystem vendor (ascii, ro)
0053 vendor PCI vendor (ascii, ro)
0054 =================== =====================================================
0055
0056 ::
0057
0058 ro - read only file
0059 rw - file is readable and writable
0060 wo - write only file
0061 mmap - file is mmapable
0062 ascii - file contains ascii text
0063 binary - file contains binary data
0064 cpumask - file contains a cpumask type
0065
0066 .. [1] rw for IORESOURCE_IO (I/O port) regions only
0067
0068 The read only files are informational, writes to them will be ignored, with
0069 the exception of the 'rom' file. Writable files can be used to perform
0070 actions on the device (e.g. changing config space, detaching a device).
0071 mmapable files are available via an mmap of the file at offset 0 and can be
0072 used to do actual device programming from userspace. Note that some platforms
0073 don't support mmapping of certain resources, so be sure to check the return
0074 value from any attempted mmap. The most notable of these are I/O port
0075 resources, which also provide read/write access.
0076
0077 The 'enable' file provides a counter that indicates how many times the device
0078 has been enabled. If the 'enable' file currently returns '4', and a '1' is
0079 echoed into it, it will then return '5'. Echoing a '0' into it will decrease
0080 the count. Even when it returns to 0, though, some of the initialisation
0081 may not be reversed.
0082
0083 The 'rom' file is special in that it provides read-only access to the device's
0084 ROM file, if available. It's disabled by default, however, so applications
0085 should write the string "1" to the file to enable it before attempting a read
0086 call, and disable it following the access by writing "0" to the file. Note
0087 that the device must be enabled for a rom read to return data successfully.
0088 In the event a driver is not bound to the device, it can be enabled using the
0089 'enable' file, documented above.
0090
0091 The 'remove' file is used to remove the PCI device, by writing a non-zero
0092 integer to the file. This does not involve any kind of hot-plug functionality,
0093 e.g. powering off the device. The device is removed from the kernel's list of
0094 PCI devices, the sysfs directory for it is removed, and the device will be
0095 removed from any drivers attached to it. Removal of PCI root buses is
0096 disallowed.
0097
0098 Accessing legacy resources through sysfs
0099 ----------------------------------------
0100
0101 Legacy I/O port and ISA memory resources are also provided in sysfs if the
0102 underlying platform supports them. They're located in the PCI class hierarchy,
0103 e.g.::
0104
0105 /sys/class/pci_bus/0000:17/
0106 |-- bridge -> ../../../devices/pci0000:17
0107 |-- cpuaffinity
0108 |-- legacy_io
0109 `-- legacy_mem
0110
0111 The legacy_io file is a read/write file that can be used by applications to
0112 do legacy port I/O. The application should open the file, seek to the desired
0113 port (e.g. 0x3e8) and do a read or a write of 1, 2 or 4 bytes. The legacy_mem
0114 file should be mmapped with an offset corresponding to the memory offset
0115 desired, e.g. 0xa0000 for the VGA frame buffer. The application can then
0116 simply dereference the returned pointer (after checking for errors of course)
0117 to access legacy memory space.
0118
0119 Supporting PCI access on new platforms
0120 --------------------------------------
0121
0122 In order to support PCI resource mapping as described above, Linux platform
0123 code should ideally define ARCH_GENERIC_PCI_MMAP_RESOURCE and use the generic
0124 implementation of that functionality. To support the historical interface of
0125 mmap() through files in /proc/bus/pci, platforms may also set HAVE_PCI_MMAP.
0126
0127 Alternatively, platforms which set HAVE_PCI_MMAP may provide their own
0128 implementation of pci_mmap_resource_range() instead of defining
0129 ARCH_GENERIC_PCI_MMAP_RESOURCE.
0130
0131 Platforms which support write-combining maps of PCI resources must define
0132 arch_can_pci_mmap_wc() which shall evaluate to non-zero at runtime when
0133 write-combining is permitted. Platforms which support maps of I/O resources
0134 define arch_can_pci_mmap_io() similarly.
0135
0136 Legacy resources are protected by the HAVE_PCI_LEGACY define. Platforms
0137 wishing to support legacy functionality should define it and provide
0138 pci_legacy_read, pci_legacy_write and pci_mmap_legacy_page_range functions.
