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