summaryrefslogtreecommitdiff
path: root/Documentation/networking
diff options
context:
space:
mode:
authorJohn Hubbard <jhubbard@nvidia.com>2020-10-09 00:01:28 -0700
committerJonathan Corbet <corbet@lwn.net>2020-10-09 09:33:23 -0600
commit6575aeab72e04396d5a674c2b6c1df51cb8a6051 (patch)
treed787fa27e2b7043307d881e415c225489ff3fc2d /Documentation/networking
parent905705a8fd432636c22476e732cf7c7ba2d6edd7 (diff)
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 <jhubbard@nvidia.com> Link: https://lore.kernel.org/r/20201009070128.118639-1-jhubbard@nvidia.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/networking')
-rw-r--r--Documentation/networking/index.rst1
-rw-r--r--Documentation/networking/sysfs-tagging.rst48
2 files changed, 49 insertions, 0 deletions
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