Merge tag 'docs-7.1' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux

Pull documentation updates from Jonathan Corbet:
 "A busier cycle than I had expected for docs, including:

   - Translations: some overdue updates to the Japanese translations,
     Chinese translations for some of the Rust documentation, and the
     beginnings of a Portuguese translation.

   - New documents covering CPU isolation, managed interrupts, debugging
     Python gbb scripts, and more.

   - More tooling work from Mauro, reducing docs-build warnings, adding
     self tests, improving man-page output, bringing in a proper C
     tokenizer to replace (some of) the mess of kernel-doc regexes, and
     more.

   - Update and synchronize changes.rst and scripts/ver_linux, and put
     both into alphabetical order.

  ... and a long list of documentation updates, typo fixes, and general
  improvements"

* tag 'docs-7.1' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (162 commits)
  Documentation: core-api: real-time: correct spelling
  doc: Add CPU Isolation documentation
  Documentation: Add managed interrupts
  Documentation: seq_file: drop 2.6 reference
  docs/zh_CN: update rust/index.rst translation
  docs/zh_CN: update rust/quick-start.rst translation
  docs/zh_CN: update rust/coding-guidelines.rst translation
  docs/zh_CN: update rust/arch-support.rst translation
  docs/zh_CN: sync process/2.Process.rst with English version
  docs/zh_CN: fix an inconsistent statement in dev-tools/testing-overview
  tracing: Documentation: Update histogram-design.rst for fn() handling
  docs: sysctl: Add documentation for /proc/sys/xen/
  Docs: hid: intel-ish-hid: make long URL usable
  Documentation/kernel-parameters: fix architecture alignment for pt, nopt, and nobypass
  sched/doc: Update yield_task description in sched-design-CFS
  Documentation/rtla: Convert links to RST format
  docs: fix typos and duplicated words across documentation
  docs: fix typo in zoran driver documentation
  docs: add an Assisted-by mention to submitting-patches.rst
  Revert "scripts/checkpatch: add Assisted-by: tag validation"
  ...

7 files changed, 157 insertions, 4 deletions

diff --git a/Documentation/core-api/housekeeping.rst b/Documentation/core-api/housekeeping.rst
index e5417302774c..92c6e53cea75 100644
--- a/Documentation/core-api/housekeeping.rst
+++ b/Documentation/core-api/housekeeping.rst
@@ -15,7 +15,7 @@ various deferrals etc...
 Sometimes housekeeping is just some unbound work (unbound workqueues,
 unbound timers, ...) that gets easily assigned to non-isolated CPUs.
 But sometimes housekeeping is tied to a specific CPU and requires
-elaborated tricks to be offloaded to non-isolated CPUs (RCU_NOCB, remote
+elaborate tricks to be offloaded to non-isolated CPUs (RCU_NOCB, remote
 scheduler tick, etc...).
 
 Thus, a housekeeping CPU can be considered as the reverse of an isolated
diff --git a/Documentation/core-api/irq/index.rst b/Documentation/core-api/irq/index.rst
index 0d65d11e5420..13bd24dd2b1c 100644
--- a/Documentation/core-api/irq/index.rst
+++ b/Documentation/core-api/irq/index.rst
@@ -9,3 +9,4 @@ IRQs
    irq-affinity
    irq-domain
    irqflags-tracing
+   managed_irq
diff --git a/Documentation/core-api/irq/managed_irq.rst b/Documentation/core-api/irq/managed_irq.rst
new file mode 100644
index 000000000000..05e295f3c289
--- /dev/null
+++ b/Documentation/core-api/irq/managed_irq.rst
@@ -0,0 +1,116 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+Affinity managed interrupts
+===========================
+
+The IRQ core provides support for managing interrupts according to a specified
+CPU affinity. Under normal operation, an interrupt is associated with a
+particular CPU. If that CPU is taken offline, the interrupt is migrated to
+another online CPU.
+
+Devices with large numbers of interrupt vectors can stress the available vector
+space. For example, an NVMe device with 128 I/O queues typically requests one
+interrupt per queue on systems with at least 128 CPUs. Two such devices
+therefore request 256 interrupts. On x86, the interrupt vector space is
+notoriously low, providing only 256 vectors per CPU, and the kernel reserves a
+subset of these, further reducing the number available for device interrupts.
+In practice this is not an issue because the interrupts are distributed across
+many CPUs, so each CPU only receives a small number of vectors.
+
+During system suspend, however, all secondary CPUs are taken offline and all
+interrupts are migrated to the single CPU that remains online. This can exhaust
+the available interrupt vectors on that CPU and cause the suspend operation to
+fail.
+
+Affinity‑managed interrupts address this limitation. Each interrupt is assigned
+a CPU affinity mask that specifies the set of CPUs on which the interrupt may
+be targeted. When a CPU in the mask goes offline, the interrupt is moved to the
+next CPU in the mask. If the last CPU in the mask goes offline, the interrupt
+is shut down. Drivers using affinity‑managed interrupts must ensure that the
+associated queue is quiesced before the interrupt is disabled so that no
+further interrupts are generated. When a CPU in the affinity mask comes back
+online, the interrupt is re‑enabled.
+
+Implementation
+--------------
+
+Devices must provide per‑instance interrupts, such as per‑I/O‑queue interrupts
+for storage devices like NVMe. The driver allocates interrupt vectors with the
+required affinity settings using struct irq_affinity. For MSI‑X devices, this
+is done via pci_alloc_irq_vectors_affinity() with the PCI_IRQ_AFFINITY flag
+set.
+
+Based on the provided affinity information, the IRQ core attempts to spread the
+interrupts evenly across the system. The affinity masks are computed during
+this allocation step, but the final IRQ assignment is performed when
+request_irq() is invoked.
+
+Isolated CPUs
+-------------
+
+The affinity of managed interrupts is handled entirely in the kernel and cannot
+be modified from user space through the /proc interfaces. The managed_irq
+sub‑parameter of the isolcpus boot option specifies a CPU mask that managed
+interrupts should attempt to avoid. This isolation is best‑effort and only
+applies if the automatically assigned interrupt mask also contains online CPUs
+outside the avoided mask. If the requested mask contains only isolated CPUs,
+the setting has no effect.
+
+CPUs listed in the avoided mask remain part of the interrupt’s affinity mask.
+This means that if all non‑isolated CPUs go offline while isolated CPUs remain
+online, the interrupt will be assigned to one of the isolated CPUs.
+
+The following examples assume a system with 8 CPUs.
+
+- A QEMU instance is booted with "-device virtio-scsi-pci".
+  The MSI‑X device exposes 11 interrupts: 3 "management" interrupts and 8
+  "queue" interrupts. The driver requests the 8 queue interrupts, each of which
+  is affine to exactly one CPU. If that CPU goes offline, the interrupt is shut
+  down.
+
+  Assuming interrupt 48 is one of the queue interrupts, the following appears::
+
+    /proc/irq/48/effective_affinity_list:7
+    /proc/irq/48/smp_affinity_list:7
+
+  This indicates that the interrupt is served only by CPU7. Shutting down CPU7
+  does not migrate the interrupt to another CPU::
+
+    /proc/irq/48/effective_affinity_list:0
+    /proc/irq/48/smp_affinity_list:7
+
+  This can be verified via the debugfs interface
+  (/sys/kernel/debug/irq/irqs/48). The dstate field will include
+  IRQD_IRQ_DISABLED, IRQD_IRQ_MASKED and IRQD_MANAGED_SHUTDOWN.
+
+- A QEMU instance is booted with "-device virtio-scsi-pci,num_queues=2"
+  and the kernel command line includes:
+  "irqaffinity=0,1 isolcpus=domain,2-7 isolcpus=managed_irq,1-3,5-7".
+  The MSI‑X device exposes 5 interrupts: 3 management interrupts and 2 queue
+  interrupts. The management interrupts follow the irqaffinity= setting. The
+  queue interrupts are spread across available CPUs::
+
+    /proc/irq/47/effective_affinity_list:0
+    /proc/irq/47/smp_affinity_list:0-3
+    /proc/irq/48/effective_affinity_list:4
+    /proc/irq/48/smp_affinity_list:4-7
+
+  The two queue interrupts are evenly distributed. Interrupt 48 is placed on CPU4
+  because the managed_irq mask avoids CPUs 5–7 when possible.
+
+  Replacing the managed_irq argument with "isolcpus=managed_irq,1-3,4-5,7"
+  results in::
+
+    /proc/irq/48/effective_affinity_list:6
+    /proc/irq/48/smp_affinity_list:4-7
+
+  Interrupt 48 is now served on CPU6 because the system avoids CPUs 4, 5 and
+  7. If CPU6 is taken offline, the interrupt migrates to one of the "isolated"
+  CPUs::
+
+    /proc/irq/48/effective_affinity_list:7
+    /proc/irq/48/smp_affinity_list:4-7
+
+  The interrupt is shut down once all CPUs listed in its smp_affinity mask are
+  offline.
diff --git a/Documentation/core-api/memory-hotplug.rst b/Documentation/core-api/memory-hotplug.rst
index 8fc97c2379de..46b0490f5319 100644
--- a/Documentation/core-api/memory-hotplug.rst
+++ b/Documentation/core-api/memory-hotplug.rst
@@ -96,7 +96,7 @@ NODE_CANCEL_ADDING_FIRST_MEMORY
  Generated if NODE_ADDING_FIRST_MEMORY fails.
 
 NODE_ADDED_FIRST_MEMORY
- Generated when memory has become available fo this node for the first time.
+ Generated when memory has become available for this node for the first time.
 
 NODE_REMOVING_LAST_MEMORY
  Generated when the last memory available to this node is about to be offlined.
diff --git a/Documentation/core-api/printk-basics.rst b/Documentation/core-api/printk-basics.rst
index 2dde24ca7d9f..48eaff0ce44c 100644
--- a/Documentation/core-api/printk-basics.rst
+++ b/Documentation/core-api/printk-basics.rst
@@ -103,6 +103,42 @@ For debugging purposes there are also two conditionally-compiled macros:
 pr_debug() and pr_devel(), which are compiled-out unless ``DEBUG`` (or
 also ``CONFIG_DYNAMIC_DEBUG`` in the case of pr_debug()) is defined.
 
+Avoiding lockups from excessive printk() use
+============================================
+
+.. note::
+
+   This section is relevant only for legacy console drivers (those not
+   using the nbcon API) and !PREEMPT_RT kernels. Once all console drivers
+   are updated to nbcon, this documentation can be removed.
+
+Using ``printk()`` in hot paths (such as interrupt handlers, timer
+callbacks, or high-frequency network receive routines) with legacy
+consoles (e.g., ``console=ttyS0``) may cause lockups. Legacy consoles
+synchronously acquire ``console_sem`` and block while flushing messages,
+potentially disabling interrupts long enough to trigger hard or soft
+lockup detectors.
+
+To avoid this:
+
+- Use rate-limited variants (e.g., ``pr_*_ratelimited()``) or one-time
+  macros (e.g., ``pr_*_once()``) to reduce message frequency.
+- Assign lower log levels (e.g., ``KERN_DEBUG``) to non-essential messages
+  and filter console output via ``console_loglevel``.
+- Use ``printk_deferred()`` to log messages immediately to the ringbuffer
+  and defer console printing. This is a workaround for legacy consoles.
+- Port legacy console drivers to the non-blocking ``nbcon`` API (indicated
+  by ``CON_NBCON``). This is the preferred solution, as nbcon consoles
+  offload message printing to a dedicated kernel thread.
+
+For temporary debugging, ``trace_printk()`` can be used, but it must not
+appear in mainline code. See ``Documentation/trace/debugging.rst`` for
+more information.
+
+If more permanent output is needed in a hot path, trace events can be used.
+See ``Documentation/trace/events.rst`` and
+``samples/trace_events/trace-events-sample.[ch]``.
+
 
 Function reference
 ==================
diff --git a/Documentation/core-api/real-time/architecture-porting.rst b/Documentation/core-api/real-time/architecture-porting.rst
index c90a426d8062..c9a39d708866 100644
--- a/Documentation/core-api/real-time/architecture-porting.rst
+++ b/Documentation/core-api/real-time/architecture-porting.rst
@@ -74,7 +74,7 @@ Exception handlers
   Enabling interrupts is especially important on PREEMPT_RT, where certain
   locks, such as spinlock_t, become sleepable. For example, handling an
   invalid opcode may result in sending a SIGILL signal to the user task. A
-  debug excpetion will send a SIGTRAP signal.
+  debug exception will send a SIGTRAP signal.
   In both cases, if the exception occurred in user space, it is safe to enable
   interrupts early. Sending a signal requires both interrupts and kernel
   preemption to be enabled.
diff --git a/Documentation/core-api/real-time/differences.rst b/Documentation/core-api/real-time/differences.rst
index 83ec9aa1c61a..a129570dab5a 100644
--- a/Documentation/core-api/real-time/differences.rst
+++ b/Documentation/core-api/real-time/differences.rst
@@ -213,7 +213,7 @@ to suspend until the callback completes, ensuring forward progress without
 risking livelock.
 
 In order to solve the problem at the API level, the sequence locks were extended
-to allow a proper handover between the the spinning reader and the maybe
+to allow a proper handover between the spinning reader and the maybe
 blocked writer.
 
 Sequence locks