Merge tag 'docs-6.18' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "It has been a relatively busy cycle in docsland, with changes all
  over:

   - Bring the kernel memory-model docs into the Sphinx build in the
     "literal include" mode.

   - Lots of build-infrastructure work, further cleaning up long-term
     kernel-doc technical debt. The sphinx-pre-install tool has been
     converted to Python and updated for current systems.

   - A new tool to detect when documents have been moved and generate
     HTML redirects; this can be used on kernel.org (or any other site
     hosting the rendered docs) to avoid breaking links.

   - Automated processing of the YAML files describing the netlink
     protocol.

   - A significant update of the maintainer's PGP guide.

  ... and a seemingly endless series of typo fixes, build-problem fixes,
  etc"

* tag 'docs-6.18' of git://git.lwn.net/linux: (193 commits)
  Documentation/features: Update feature lists for 6.17-rc7
  docs: remove cdomain.py
  Documentation/process: submitting-patches: fix typo in "were do"
  docs: dev-tools/lkmm: Fix typo of missing file extension
  Documentation: trace: histogram: Convert ftrace docs cross-reference
  Documentation: trace: histogram-design: Wrap introductory note in note:: directive
  Documentation: trace: historgram-design: Separate sched_waking histogram section heading and the following diagram
  Documentation: trace: histogram-design: Trim trailing vertices in diagram explanation text
  Documentation: trace: histogram: Fix histogram trigger subsection number order
  docs: driver-api: fix spelling of "buses".
  Documentation: fbcon: Use admonition directives
  Documentation: fbcon: Reindent 8th step of attach/detach/unload
  Documentation: fbcon: Add boot options and attach/detach/unload section headings
  docs: filesystems: sysfs: add remaining top level sysfs directory descriptions
  docs: filesystems: sysfs: clarify symlink destinations in dev and bus/devices descriptions
  docs: filesystems: sysfs: remove top level sysfs net directory
  docs: maintainer: Fix ambiguous subheading formatting
  docs: kdoc: a few more dump_typedef() tweaks
  docs: kdoc: remove redundant comment stripping in dump_typedef()
  docs: kdoc: remove some dead code in dump_typedef()
  ...

1 files changed, 19 insertions, 6 deletions

diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst
index be966f27f284..2703c04af7d0 100644
--- a/Documentation/filesystems/sysfs.rst
+++ b/Documentation/filesystems/sysfs.rst
@@ -243,8 +243,8 @@ Other notes:
 - show() methods should return the number of bytes printed into the
   buffer.
 
-- show() should only use sysfs_emit() or sysfs_emit_at() when formatting
-  the value to be returned to user space.
+- New implementations of show() methods should only use sysfs_emit() or
+  sysfs_emit_at() when formatting the value to be returned to user space.
 
 - store() should return the number of bytes used from the buffer. If the
   entire buffer has been used, just return the count argument.
@@ -299,7 +299,6 @@ The top level sysfs directory looks like::
     hypervisor/
     kernel/
     module/
-    net/
     power/
 
 devices/ contains a filesystem representation of the device tree. It maps
@@ -313,7 +312,7 @@ kernel. Each bus's directory contains two subdirectories::
 	drivers/
 
 devices/ contains symlinks for each device discovered in the system
-that point to the device's directory under root/.
+that point to the device's directory under /sys/devices.
 
 drivers/ contains a directory for each device driver that is loaded
 for devices on that particular bus (this assumes that drivers do not
@@ -328,15 +327,29 @@ loaded system modules, for both builtin and loadable modules.
 
 dev/ contains two directories: char/ and block/. Inside these two
 directories there are symlinks named <major>:<minor>.  These symlinks
-point to the sysfs directory for the given device.  /sys/dev provides a
+point to the directories under /sys/devices for each device.  /sys/dev provides a
 quick way to lookup the sysfs interface for a device from the result of
 a stat(2) operation.
 
 More information on driver-model specific features can be found in
 Documentation/driver-api/driver-model/.
 
+block/ contains symlinks to all the block devices discovered on the system.
+These symlinks point to directories under /sys/devices.
 
-TODO: Finish this section.
+class/ contains a directory for each device class, grouped by functional type.
+Each directory in class/ contains symlinks to devices in the /sys/devices directory.
+
+firmware/ contains system firmware data and configuration such as firmware tables,
+ACPI information, and device tree data.
+
+hypervisor/ contains virtualization platform information and provides an interface to
+the underlying hypervisor.  It is only present when running on a virtual machine.
+
+kernel/ contains runtime kernel parameters, configuration settings, and status.
+
+power/ contains power management subsystem information including
+sleep states, suspend/resume capabilities, and policies.
 
 
 Current Interfaces