From 6575aeab72e04396d5a674c2b6c1df51cb8a6051 Mon Sep 17 00:00:00 2001 From: John Hubbard Date: Fri, 9 Oct 2020 00:01:28 -0700 Subject: Documentation: better locations for sysfs-pci, sysfs-tagging sysfs-pci and sysfs-tagging were mis-filed: their locations within Documentation/ implied that they were related to file systems. Actually, each topic is about a very specific *use* of sysfs, and sysfs *happens* to be a (virtual) filesystem, so this is not really the right place. It's jarring to be reading about filesystems in general and then come across these specific details about PCI, and tagging...and then back to general filesystems again. Move sysfs-pci to PCI, and move sysfs-tagging to networking. (Thanks to Jonathan Corbet for coming up with the final locations.) Signed-off-by: John Hubbard Link: https://lore.kernel.org/r/20201009070128.118639-1-jhubbard@nvidia.com Signed-off-by: Jonathan Corbet --- Documentation/networking/index.rst | 1 + Documentation/networking/sysfs-tagging.rst | 48 ++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 Documentation/networking/sysfs-tagging.rst (limited to 'Documentation/networking') diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index c29496fff81c..611e4b130c1e 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -95,6 +95,7 @@ Contents: seg6-sysctl strparser switchdev + sysfs-tagging tc-actions-env-rules tcp-thin team diff --git a/Documentation/networking/sysfs-tagging.rst b/Documentation/networking/sysfs-tagging.rst new file mode 100644 index 000000000000..83647e10c207 --- /dev/null +++ b/Documentation/networking/sysfs-tagging.rst @@ -0,0 +1,48 @@ +.. 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 -- cgit v1.2.3