diff options
Diffstat (limited to 'Documentation/filesystems')
-rw-r--r-- | Documentation/filesystems/index.rst | 2 | ||||
-rw-r--r-- | Documentation/filesystems/sysfs-pci.rst | 138 | ||||
-rw-r--r-- | Documentation/filesystems/sysfs-tagging.rst | 48 |
3 files changed, 0 insertions, 188 deletions
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 4c536e66dc4c..98f59a864242 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -34,8 +34,6 @@ algorithms work. quota seq_file sharedsubtree - sysfs-pci - sysfs-tagging automount-support diff --git a/Documentation/filesystems/sysfs-pci.rst b/Documentation/filesystems/sysfs-pci.rst deleted file mode 100644 index 742fbd21dc1f..000000000000 --- a/Documentation/filesystems/sysfs-pci.rst +++ /dev/null @@ -1,138 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -============================================ -Accessing PCI device resources through sysfs -============================================ - -sysfs, usually mounted at /sys, provides access to PCI resources on platforms -that support it. For example, a given bus might look like this:: - - /sys/devices/pci0000:17 - |-- 0000:17:00.0 - | |-- class - | |-- config - | |-- device - | |-- enable - | |-- irq - | |-- local_cpus - | |-- remove - | |-- resource - | |-- resource0 - | |-- resource1 - | |-- resource2 - | |-- revision - | |-- rom - | |-- subsystem_device - | |-- subsystem_vendor - | `-- vendor - `-- ... - -The topmost element describes the PCI domain and bus number. In this case, -the domain number is 0000 and the bus number is 17 (both values are in hex). -This bus contains a single function device in slot 0. The domain and bus -numbers are reproduced for convenience. Under the device directory are several -files, each with their own function. - - =================== ===================================================== - file function - =================== ===================================================== - class PCI class (ascii, ro) - config PCI config space (binary, rw) - device PCI device (ascii, ro) - enable Whether the device is enabled (ascii, rw) - irq IRQ number (ascii, ro) - local_cpus nearby CPU mask (cpumask, ro) - remove remove device from kernel's list (ascii, wo) - resource PCI resource host addresses (ascii, ro) - resource0..N PCI resource N, if present (binary, mmap, rw\ [1]_) - resource0_wc..N_wc PCI WC map resource N, if prefetchable (binary, mmap) - revision PCI revision (ascii, ro) - rom PCI ROM resource, if present (binary, ro) - subsystem_device PCI subsystem device (ascii, ro) - subsystem_vendor PCI subsystem vendor (ascii, ro) - vendor PCI vendor (ascii, ro) - =================== ===================================================== - -:: - - ro - read only file - rw - file is readable and writable - wo - write only file - mmap - file is mmapable - ascii - file contains ascii text - binary - file contains binary data - cpumask - file contains a cpumask type - -.. [1] rw for IORESOURCE_IO (I/O port) regions only - -The read only files are informational, writes to them will be ignored, with -the exception of the 'rom' file. Writable files can be used to perform -actions on the device (e.g. changing config space, detaching a device). -mmapable files are available via an mmap of the file at offset 0 and can be -used to do actual device programming from userspace. Note that some platforms -don't support mmapping of certain resources, so be sure to check the return -value from any attempted mmap. The most notable of these are I/O port -resources, which also provide read/write access. - -The 'enable' file provides a counter that indicates how many times the device -has been enabled. If the 'enable' file currently returns '4', and a '1' is -echoed into it, it will then return '5'. Echoing a '0' into it will decrease -the count. Even when it returns to 0, though, some of the initialisation -may not be reversed. - -The 'rom' file is special in that it provides read-only access to the device's -ROM file, if available. It's disabled by default, however, so applications -should write the string "1" to the file to enable it before attempting a read -call, and disable it following the access by writing "0" to the file. Note -that the device must be enabled for a rom read to return data successfully. -In the event a driver is not bound to the device, it can be enabled using the -'enable' file, documented above. - -The 'remove' file is used to remove the PCI device, by writing a non-zero -integer to the file. This does not involve any kind of hot-plug functionality, -e.g. powering off the device. The device is removed from the kernel's list of -PCI devices, the sysfs directory for it is removed, and the device will be -removed from any drivers attached to it. Removal of PCI root buses is -disallowed. - -Accessing legacy resources through sysfs ----------------------------------------- - -Legacy I/O port and ISA memory resources are also provided in sysfs if the -underlying platform supports them. They're located in the PCI class hierarchy, -e.g.:: - - /sys/class/pci_bus/0000:17/ - |-- bridge -> ../../../devices/pci0000:17 - |-- cpuaffinity - |-- legacy_io - `-- legacy_mem - -The legacy_io file is a read/write file that can be used by applications to -do legacy port I/O. The application should open the file, seek to the desired -port (e.g. 0x3e8) and do a read or a write of 1, 2 or 4 bytes. The legacy_mem -file should be mmapped with an offset corresponding to the memory offset -desired, e.g. 0xa0000 for the VGA frame buffer. The application can then -simply dereference the returned pointer (after checking for errors of course) -to access legacy memory space. - -Supporting PCI access on new platforms --------------------------------------- - -In order to support PCI resource mapping as described above, Linux platform -code should ideally define ARCH_GENERIC_PCI_MMAP_RESOURCE and use the generic -implementation of that functionality. To support the historical interface of -mmap() through files in /proc/bus/pci, platforms may also set HAVE_PCI_MMAP. - -Alternatively, platforms which set HAVE_PCI_MMAP may provide their own -implementation of pci_mmap_page_range() instead of defining -ARCH_GENERIC_PCI_MMAP_RESOURCE. - -Platforms which support write-combining maps of PCI resources must define -arch_can_pci_mmap_wc() which shall evaluate to non-zero at runtime when -write-combining is permitted. Platforms which support maps of I/O resources -define arch_can_pci_mmap_io() similarly. - -Legacy resources are protected by the HAVE_PCI_LEGACY define. Platforms -wishing to support legacy functionality should define it and provide -pci_legacy_read, pci_legacy_write and pci_mmap_legacy_page_range functions. diff --git a/Documentation/filesystems/sysfs-tagging.rst b/Documentation/filesystems/sysfs-tagging.rst deleted file mode 100644 index 83647e10c207..000000000000 --- a/Documentation/filesystems/sysfs-tagging.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -============= -Sysfs tagging -============= - -(Taken almost verbatim from Eric Biederman's netns tagging patch -commit msg) - -The problem. Network devices show up in sysfs and with the network -namespace active multiple devices with the same name can show up in -the same directory, ouch! - -To avoid that problem and allow existing applications in network -namespaces to see the same interface that is currently presented in -sysfs, sysfs now has tagging directory support. - -By using the network namespace pointers as tags to separate out -the sysfs directory entries we ensure that we don't have conflicts -in the directories and applications only see a limited set of -the network devices. - -Each sysfs directory entry may be tagged with a namespace via the -``void *ns member`` of its ``kernfs_node``. If a directory entry is tagged, -then ``kernfs_node->flags`` will have a flag between KOBJ_NS_TYPE_NONE -and KOBJ_NS_TYPES, and ns will point to the namespace to which it -belongs. - -Each sysfs superblock's kernfs_super_info contains an array -``void *ns[KOBJ_NS_TYPES]``. When a task in a tagging namespace -kobj_nstype first mounts sysfs, a new superblock is created. It -will be differentiated from other sysfs mounts by having its -``s_fs_info->ns[kobj_nstype]`` set to the new namespace. Note that -through bind mounting and mounts propagation, a task can easily view -the contents of other namespaces' sysfs mounts. Therefore, when a -namespace exits, it will call kobj_ns_exit() to invalidate any -kernfs_node->ns pointers pointing to it. - -Users of this interface: - -- define a type in the ``kobj_ns_type`` enumeration. -- call kobj_ns_type_register() with its ``kobj_ns_type_operations`` which has - - - current_ns() which returns current's namespace - - netlink_ns() which returns a socket's namespace - - initial_ns() which returns the initial namesapce - -- call kobj_ns_exit() when an individual tag is no longer valid |