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

Pull documentation updates from Jonathan Corbet:
 "It has been a not-too-busy cycle for docs; here's the highlights:

   - A (hopefully) consensus change to our LLM-attribution requirements,
     removing the specific model name from the Assisted-by tag

   - A couple of new realtime documents

   - Various docs-build-system fixes

   - Ongoing work with the Chinese, Portuguese, and Japanese
     translations

  ...and lots of typo fixes, grammar tweaks, etc"

* tag 'docs-7.3' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (85 commits)
  Doc: admin-guide: pm: Remove unnecessary backticks and fix a spell
  Documentation: Extend the real-time hardware bits with some firmware bits
  docs: pt_BR: Reorganize process/index.rst to follow english structure
  docs: conf.py: fix the 'utf-8' typo
  doc tools: fix 'path' typos
  Documentation: real-time: Add kernel configuration guide
  docs: python: abi_regex: convert adjacent index placeholders
  docs: python: abi_regex: catch the right exception for a bad regex
  docs: sphinx-build-wrapper: include localversion in kernel version string
  Documentation: html: adjust sidebar section titles styling
  Documentation: html: show sections in the sidebar
  checkpatch.pl: adapt to new Assisted-by: format
  MAINTAINERS: update Traditional Chinese documentation maintainers
  docs: pt_BR: process: Translate CVE documentation
  docs: pt_BR: translate the management-style.rst to Brazilian Portuguese
  docs: xforms_lists: support DEFINE_IDTENTRY_IRQ()
  coding-assistants: simplify attribution
  docs: translations: pt_BR: translate email-clients.rst
  docs: pt_BR: process: Translate the security-bugs.rst
  doc:it_IT: align doc-guide translation
  ...

10 files changed, 429 insertions, 18 deletions

diff --git a/Documentation/core-api/SMP.rst b/Documentation/core-api/SMP.rst
new file mode 100644
index 000000000000..0265a9835f23
--- /dev/null
+++ b/Documentation/core-api/SMP.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+==============
+SMP primitives
+==============
+
+.. kernel-doc:: include/linux/smp.h
+   :internal:
+
+.. kernel-doc:: kernel/smp.c
+   :export:
diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index ca75b3541679..ba23a472f794 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -508,7 +508,7 @@ call to dma_iova_try_alloc.  This can be useful in the unmap path.
 
 Is used to link ranges to the IOVA previously allocated.  The start of all
 but the first call to dma_iova_link for a given state must be aligned
-to the DMA merge boundary returned by ``dma_get_merge_boundary())``, and
+to the DMA merge boundary returned by ``dma_get_merge_boundary()``, and
 the size of all but the last range must be aligned to the DMA merge boundary
 as well.
 
diff --git a/Documentation/core-api/errseq.rst b/Documentation/core-api/errseq.rst
index ff332e272405..d298d4cd2f60 100644
--- a/Documentation/core-api/errseq.rst
+++ b/Documentation/core-api/errseq.rst
@@ -143,7 +143,7 @@ Because of this, it's often advantageous to first do an errseq_check to
 see if anything has changed, and only later do an
 errseq_check_and_advance after taking the lock. e.g.::
 
-        if (errseq_check(&wd.wd_err, READ_ONCE(su.s_wd_err)) {
+        if (errseq_check(&wd.wd_err, READ_ONCE(su.s_wd_err))) {
                 /* su.s_wd_err is protected by s_wd_err_lock */
                 spin_lock(&su.s_wd_err_lock);
                 err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err);
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 13769d5c40bf..92f91c6a0d79 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -81,6 +81,7 @@ Documentation/locking/index.rst for more related documentation.
    padata
    ../RCU/index
    wrappers/memory-barriers.rst
+   SMP
 
 Low-level hardware management
 =============================
diff --git a/Documentation/core-api/list.rst b/Documentation/core-api/list.rst
index 479aa91cc395..df8b078bb366 100644
--- a/Documentation/core-api/list.rst
+++ b/Documentation/core-api/list.rst
@@ -458,7 +458,7 @@ The list_move() and list_move_tail() functions can be used to move an entry
 from one list to another, to either the start or end respectively.
 
 In the following example, we'll assume we start with two lists ("clowns" and
-"sidewalk" in the following initial state "State 0"::
+"sidewalk") in the following initial state "State 0"::
 
          .----------------------------------------------------------------.
          v                                                                |
diff --git a/Documentation/core-api/min_heap.rst b/Documentation/core-api/min_heap.rst
index 9f57766581df..919dcf1bdec7 100644
--- a/Documentation/core-api/min_heap.rst
+++ b/Documentation/core-api/min_heap.rst
@@ -240,19 +240,6 @@ This macro returns `true` if the heap is full, otherwise `false`.
 
 **Inline Version:** min_heap_full_inline(heap)
 
-- **min_heap_empty(heap)**: Checks whether the heap is empty.
-  Complexity: **O(1)**.
-
-.. code-block:: c
-
-    bool empty = min_heap_empty(heap);
-
-- `heap`: A pointer to the min-heap to check.
-
-This macro returns `true` if the heap is empty, otherwise `false`.
-
-**Inline Version:** min_heap_empty_inline(heap)
-
 Example Usage
 =============
 
diff --git a/Documentation/core-api/packing.rst b/Documentation/core-api/packing.rst
index f68f1e08fef9..cff1a262efce 100644
--- a/Documentation/core-api/packing.rst
+++ b/Documentation/core-api/packing.rst
@@ -330,7 +330,7 @@ Here is an example of how to use the fields APIs:
 
    void unpack_your_data(const packed_buf_t *buf, struct data *unpacked)
    {
-           BUILD_BUG_ON(sizeof(*buf) != SIZE;
+           BUILD_BUG_ON(sizeof(*buf) != SIZE);
 
            unpack_fields(buf, sizeof(*buf), unpacked, fields,
                          QUIRK_LITTLE_ENDIAN);
@@ -338,7 +338,7 @@ Here is an example of how to use the fields APIs:
 
    void pack_your_data(const struct data *unpacked, packed_buf_t *buf)
    {
-           BUILD_BUG_ON(sizeof(*buf) != SIZE;
+           BUILD_BUG_ON(sizeof(*buf) != SIZE);
 
            pack_fields(buf, sizeof(*buf), unpacked, fields,
                        QUIRK_LITTLE_ENDIAN);
diff --git a/Documentation/core-api/real-time/hardware.rst b/Documentation/core-api/real-time/hardware.rst
index 19f9bb3786e0..9f95e75e6aa1 100644
--- a/Documentation/core-api/real-time/hardware.rst
+++ b/Documentation/core-api/real-time/hardware.rst
@@ -130,3 +130,107 @@ https://github.com/Linutronix/RTC-Testbench.
 The goal of this project is to validate real-time network communication. It can
 be thought of as a "cyclictest" for networking and also serves as a starting
 point for application development.
+
+Firmware
+--------
+
+The firmware often plays a significant role in system operation because it can
+perform tasks that the kernel cannot directly access, and in some cases it can
+even preempt or intercept the kernel.
+
+A common example of firmware assisting the kernel is when it provides a generic
+interface to a resource. Instead of accessing an RTC chip through an I2C host
+controller, the kernel may query the firmware for the current time, and the
+firmware then accesses the RTC behind the scenes.
+
+Firmware can also intercept kernel execution by providing services that
+temporarily take control of the system. One example is memory scrubbing, where
+the firmware periodically pauses the kernel, reads back portions of system
+memory, and then returns control. During this time, the kernel is effectively
+interrupted.
+In contrast, some systems provide hardware-based memory scrubbing, which
+operates independently of firmware or software. See
+Documentation/edac/scrub.rst for details.
+
+If the kernel is intercepted for longer periods then these periods can be made
+visible with the hardware latency detector. See
+Documentation/trace/hwlat_detector.rst.
+
+The kernel can also be intercepted in response to specific events, such as
+overheating. In this case, the firmware may throttle the CPU or shut it down
+immediately to prevent hardware damage.
+
+Unless the firmware is well documented, it should be thoroughly tested to
+uncover any unexpected behaviour.
+
+EFI
+~~~~
+
+EFI provides runtime services that act as a communication interface between the
+firmware and the operating system. One such service is reading and writing EFI
+variables, which are used, for example, to determine the boot source.
+
+Invoking a runtime service may require the architecture to disable kernel
+preemption or interrupts during the call. This means the duration of a service
+invocation directly affects the system’s observable latency. There is also
+nothing that prevents a service call from disabling interrupts internally while
+it runs.
+
+For these reasons, EFI runtime services are disabled by default on a PREEMPT_RT
+kernel. They can still be enabled at boot time or via a Kconfig option if
+required.
+The native EFI runtime service implementation (where both the EFI service and
+the kernel are either 32-bit or 64-bit executables) uses a wrapper mechanism
+that invokes the service through a dedicated workqueue. This workqueue is named
+efi_runtime, and it can be restricted to a housekeeping CPU using the
+``/sys/devices/virtual/workqueue/efi_runtime/cpumask`` sysfs file. Assigning it
+to a housekeeping CPU ensures that potentially long service invocations do not
+impact the real-time workload which is restricted to other CPUs.
+
+It must also be verified that the runtime services behave as expected. Some
+implementations on the x86 architecture pause all other CPUs while one CPU
+performs the service call. In such cases, the interruption affects all CPUs,
+and restricting the workqueue to a single CPU provides no benefit.
+
+OP-TEE (ARM)
+~~~~~~~~~~~~
+
+Execution flows from the normal world (Linux) into the secure world (OP-TEE)
+through the secure monitor at EL3. The transition is initiated by the `smc`
+(Secure Monitor Call) opcode or the `hvc` (Hypervisor Call) opcode together
+with a function identifier. The calling convention defines two types of calls:
+**yielding calls** and **fast calls**:
+
+- A **yielding call** unmasks interrupts before handling the requested service,
+  allowing normal world interrupts to occur.
+- A **fast call** handles the requested service atomically, without allowing
+  interrupts from either the normal world or the secure world.
+
+In addition, the secure world (EL3 and OP-TEE) can receive interrupts routed to
+the secure world. While a secure world interrupt is being serviced,
+normal world interrupts are masked and cannot preempt the operation.
+
+The transition from normal world to secure monitor to OP-TEE and back introduces
+additional latency due to world switching and context save/restore. This
+overhead is typically a few microseconds and usually remains within the noise
+floor.
+
+It is worth noting that the normal world cannot mask secure interrupts, while
+the secure world can mask normal-world interrupts during execution. How OP-TEE
+affects real-time workloads depends on whether secure interrupts are enabled
+and which OP-TEE services are invoked.
+
+A practical concern is any fast call that runs longer than expected, for
+example a function that occasionally performs a long-running cryptographic
+computation. Another example that may block in an unexpected way are OP-TEE
+drivers that issue RPC requests. An OP-TEE service in the secure world (RPMB
+for instance) may need to issue a request back to the normal world (the Linux
+driver) in order to complete the operation. While Linux remains preemptible,
+the thread that issued the request stays blocked until the RPC completes and
+the secure function call returns.
+
+The TF-A project provides documentation on interrupt management:
+https://trustedfirmware-a.readthedocs.io/en/latest/design/interrupt-framework-design.html#interrupt-management-framework
+
+The OP-TEE project provides documentation on how interrupts are handled:
+https://optee.readthedocs.io/en/latest/architecture/core.html#interrupt-handling
diff --git a/Documentation/core-api/real-time/index.rst b/Documentation/core-api/real-time/index.rst
index f08d2395a22c..a17a3dec535c 100644
--- a/Documentation/core-api/real-time/index.rst
+++ b/Documentation/core-api/real-time/index.rst
@@ -15,3 +15,4 @@ the required changes compared to a non-PREEMPT_RT configuration.
    differences
    hardware
    architecture-porting
+   kernel-configuration
diff --git a/Documentation/core-api/real-time/kernel-configuration.rst b/Documentation/core-api/real-time/kernel-configuration.rst
new file mode 100644
index 000000000000..d7f08e7b8760
--- /dev/null
+++ b/Documentation/core-api/real-time/kernel-configuration.rst
@@ -0,0 +1,307 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
+Real-Time Kernel configuration
+==============================
+
+.. contents:: Table of Contents
+   :depth: 3
+   :local:
+
+Introduction
+============
+
+This document lists the kernel configuration options that might affect a
+real-time kernel's worst-case latency.  It is intended for system integrators.
+
+Configuration options
+=====================
+
+.. Please keep the configuration listings alphabetically ordered
+
+CPU frequency governors
+-----------------------
+
+``CONFIG_CPU_FREQ``
+^^^^^^^^^^^^^^^^^^^
+
+:Expectation: enabled
+:Severity: *high*
+
+The CPU frequency scaling subsystem ensures that the processor can operate at
+its maximum supported frequency.  While, in general, bootloaders are tasked
+with setting the CPU clock to the highest speed on boot, some do not.  It is
+thus desirable to keep this option enabled.
+
+.. caution::
+
+  A real-time kernel is not about being "as fast as possible", however
+  real-time requirements may demand that the CPU is clocked at a particular
+  speed.
+
+``CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:Expectation: enabled
+:Severity: *high*
+
+Real-Time workloads expect a fixed CPU frequency during execution.  Using the
+performance governor is an easy way to achieve that purely from kernel
+configuration.
+
+This is not an absolute rule.  Some setups might prefer to clock the CPU to
+lower speeds due to thermal packaging or other requirements.  The key is that
+the CPU frequency remains constant once set.
+
+Non-performance CPU frequency governors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:Expectation: disabled
+:Severity: *medium*
+
+To ensure reproducible system latency measurements, disable the
+non-``PERFORMANCE`` CPU frequency governors whenever possible.  This avoids
+the risk of unknown userspace tasks implicitly or explicitly setting a
+different CPU frequency governor, and thereby changing latency behavior while
+the system is running.
+
+If disabling other frequency governors is not an option, use a governor that
+keeps the CPU frequency fixed.  For example,
+``CONFIG_CPU_FREQ_DEFAULT_GOV_USERSPACE`` can be enabled when userspace is
+responsible for setting a *stable* frequency during system initialization.
+
+If a low CPU frequency is desired, then
+``CONFIG_CPU_FREQ_DEFAULT_GOV_POWERSAVE`` can be set.
+
+The ``ONDEMAND`` governor should not be enabled on a real-time system.  Its
+frequency changes depend on workload behavior and can significantly harm
+determinism.
+
+For more information, see Documentation/admin-guide/pm/cpufreq.rst
+
+``CONFIG_CPU_IDLE``
+-------------------
+
+:Expectation: enabled
+:Severity: *info*
+
+CPU idle states (C-states) allow the processor to enter low-power modes during
+periods of inactivity.  Very-low CPU idle states may require flushing the CPU
+caches and lowering or disabling the clocking.  This can lower power
+consumption, but it also increases the entry and exit latency from such
+states.
+
+While disabling this option eliminates cpuidle-related latencies, doing so can
+significantly impact hardware longevity, warranty, and thermal behavior.
+Users should cap the maximum C-state to C1 instead.  For ACPI platforms, this
+can be achieved by using the boot parameter [1]_::
+
+  processor.max_cstate=1
+
+Higher C-states can be acceptable depending on the user workload's latency
+requirements.  For ACPI-based platforms, use the ``cpupower idle-info``
+command to inspect the available idle states.
+
+For more information, please see:
+
+- ``linux/tools/power/cpupower``
+- Documentation/admin-guide/pm/cpuidle.rst
+- Documentation/admin-guide/pm/index.rst
+
+``CONFIG_DRM``
+--------------
+
+:Expectation: disabled
+:Severity: *info*
+
+GPU-accelerated workloads can share system resources with the CPU, including
+last-level cache (LLC) and memory bandwidth.  Modern integrated GPUs optimize
+graphics performance at the expense of CPU determinism.
+
+Examples of affected platforms:
+
+- Intel processors with integrated graphics (Gen9 and later)
+- AMD APUs with Radeon Graphics
+- Xilinx Zynq UltraScale+ MPSoC EG/EV series
+
+If graphics workloads must run alongside real-time tasks, users must conduct
+thorough stress testing using tools like ``glmark2`` while measuring the
+overall system latency.
+
+For more information, please check:
+
+- Documentation/core-api/real-time/hardware.rst ("Regarding hardware" section)
+- Documentation/filesystems/resctrl.rst
+- `Real-Time and Graphics: A Contradiction? <https://web.archive.org/web/20221025085614/https://linutronix.de/PDF/Realtime_and_graphics-acontradiction2021.pdf>`_
+
+``CONFIG_EFI_DISABLE_RUNTIME``
+------------------------------
+
+:Expectation: enabled
+:Severity: *medium*
+
+EFI is the standard boot and firmware interface for multiple architectures.
+EFI runtime services provide callback functions to be called from the kernel;
+e.g., as utilized by (``CONFIG_EFI_VARS*``) or (``CONFIG_RTC_DRV_EFI``).  For
+the former, the kernel calls into EFI to update the EFI variables.
+
+Calling into EFI means invoking firmware callbacks.  During such invocations,
+the system might not be able to react to interrupts and will thus not be able
+to perform a context switch.  This can cause significant latency spikes for
+the real-time system.
+
+``CONFIG_PREEMPT_RT`` enables this option by default.  If this option is
+manually disabled at build time, the following boot parameter [1]_ may be used
+to disable EFI runtime at boot up::
+
+  efi=noruntime
+
+Alternatively, confine EFI runtime service calls to a housekeeping CPU by
+restricting the ``efi_runtime`` workqueue CPU affinity.  For example, set that
+workqueue's affinity to CPU #0 and pin your RT tasks to a different CPU range.
+See Documentation/core-api/workqueue.rst
+
+``CONFIG_NO_HZ`` / ``CONFIG_NO_HZ_FULL``
+----------------------------------------
+
+:Expectation: disabled
+:Severity: *medium*
+
+Tickless operation can increase kernel-to-userspace transition latency due to
+the extra accounting and state book-keeping.
+
+*Guidance by real-time workload type:*
+
+- For periodic workloads; e.g., control loops executing every 100 µs, avoid
+  ``NO_HZ`` modes.  Consistent kernel ticks are preferable.
+
+- For computation-intensive workloads; e.g. extended userspace execution,
+  ``NO_HZ_FULL`` may be beneficial.  In such cases, users should offload the
+  kernel housekeeping to dedicated CPUs and isolate compute cores.
+
+See also Documentation/timers/no_hz.rst
+
+``CONFIG_PREEMPT_RT``
+---------------------
+
+:Expectation: enabled
+:Severity: **fatal**
+
+This option must be enabled, or the resulting kernel will not be fully
+preemptible and real-time capable.
+
+``CONFIG_TRACING`` (and tracing options)
+----------------------------------------
+
+:Expectation: enabled
+:Severity: *info*
+
+Shipping kernels with tracing support enabled (but not actively running) is
+highly recommended.  This will allow the users to extract more information if
+latency problems arise.  Nonetheless, some tracers do incur latency overhead
+just by being enabled.
+
+.. caution::
+
+  Users should *not* make use of tracers or trace events during production
+  real-time kernel operation as they can add considerable overhead and degrade
+  the system's latency.
+
+``CONFIG_IRQSOFF_TRACER`` and ``CONFIG_PREEMPT_TRACER``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:Expectation: disabled
+:Severity: *high*
+
+These tracers do incur measurable latency overhead even when tracing is not
+currently active.
+
+Kernel Debug Options
+====================
+
+Most kernel debug options add runtime overhead that increases the worst-case
+latency.
+
+.. caution::
+
+  During development and early testing, users are encouraged to run their
+  real-time workloads and peripherals with lockdep (:ref:`lockdep`) and other
+  kernel debug options enabled, for a considerable amount of time.  Such
+  workloads might trigger kernel code paths that were not triggered during the
+  internal Linux real-time kernel development, thus helping to uncover locking
+  and other types of kernel bugs.
+
+``CONFIG_DEBUG_ATOMIC_SLEEP``
+-----------------------------
+
+:Expectation: allowed
+
+This sanity check catches common kernel programming errors with a tolerable
+latency cost.  It also increases overall scheduling as each ``might_sleep()``
+can lead to a context switch.
+
+``CONFIG_DEBUG_BUGVERBOSE`` and ``CONFIG_DEBUG_INFO*``
+------------------------------------------------------
+
+:Expectation: allowed
+
+These options increase the kernel image size but have no latency impact.  They
+are also essential for meaningful BUG logs, crash dumps, and profiling.
+
+``CONFIG_DEBUG_FS``
+-------------------
+
+:Expectation: allowed
+
+This is safe to include in real-time kernels, *provided that debugfs is not
+accessed during production runtime*.
+
+``CONFIG_DEBUG_KERNEL``
+-----------------------
+
+:Expectation: allowed
+
+Meta-option which allows debug features to be enabled.  It has no runtime
+impact, but beware of any debug features that it may have implicitly enabled.
+
+``CONFIG_LOCKUP_DETECTOR``
+--------------------------
+
+:Expectation: disabled
+:Severity: *high*
+
+The lockup detector creates kernel timer callbacks that execute every few
+seconds, in hard-IRQ context, even on real-time kernels.  These periodic
+interrupts can cause latency spikes.
+
+Users should use hardware watchdogs instead, which will provide a similar
+functionality without the software-induced latency.
+
+.. _lockdep:
+
+``CONFIG_PROVE_LOCKING``
+------------------------
+
+:Expectation: disabled
+:Severity: *high*
+
+Proving the correctness of all kernel locking adds substantial overhead and
+significantly increases worst-case latency.
+
+Summary
+=======
+
+There is no "one size fits all" solution for configuring a real-time Linux
+system.  Beginning with the system real-time requirements, integrators must
+consider the features and functions of the system's hardware, kernel, and
+userspace.  All such components must be properly configured in order to
+establish and constrain the system's maximum latency.
+
+With that in mind, any incorrect real-time kernel configuration could cause a
+new maximum latency that shows up at the wrong time and is catastrophic for
+the real-time system's latency.
+
+References
+==========
+
+.. [1] See Documentation/admin-guide/kernel-parameters.rst