[RFC PATCH 2/3] Documentation/arch/arm64: document arm_cpumod

[KobaK <kobak@nvidia.com>]

From: Koba Ko <kobak@nvidia.com>

Document the ABI intent and scope for the new arm64 cpumod interface.
The sysfs directory is per-CPU and is created only for recognized Grace
and Vera profiles:

  /sys/devices/system/cpu/cpuN/cpumod/

CPUs with unsupported MIDRs are skipped without blocking module load or
CPU hotplug and do not receive a cpumod directory.

Describe the common attributes, the Grace- and Vera-specific attributes,
and the accepted range for each writable field. Out-of-range writes are
documented as failing before either cached sysfs state or target CPU
register state is changed.

Document the CPU hotplug lifecycle explicitly: the cpumod directory is
present only while a supported CPU is online, is removed when that CPU
goes offline, and is recreated when it returns online. Reads and writes
therefore require an online target CPU.

Also document the firmware prerequisite: EL1 must be allowed to access
the relevant implementation control registers. The interface remains an
RFC for controlled performance characterization, is not a general
production tuning ABI, and should stay disabled by default on production
systems.

Reviewed-by: Fenghua Yu <fenghuay@nvidia.com>
Reviewed-by: Tushar Dave <tdave@nvidia.com>
Reviewed-by: Kai-Heng Feng <kaihengf@nvidia.com>
Signed-off-by: Koba Ko <kobak@nvidia.com>
---
 Documentation/arch/arm64/arm-cpumod.rst | 89 +++++++++++++++++++++++++
 Documentation/arch/arm64/index.rst      |  1 +
 2 files changed, 90 insertions(+)
 create mode 100644 Documentation/arch/arm64/arm-cpumod.rst

diff --git a/Documentation/arch/arm64/arm-cpumod.rst b/Documentation/arch/arm64/arm-cpumod.rst
new file mode 100644
index 0000000000000..7dbe2cd5404a2
--- /dev/null
+++ b/Documentation/arch/arm64/arm-cpumod.rst
@@ -0,0 +1,89 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================
+Arm CPU prefetch modulation controls
+====================================
+
+``ARM64_CPUMOD`` exposes selected CPU implementation control register fields
+through per-CPU sysfs attributes under::
+
+  /sys/devices/system/cpu/cpuN/cpumod/
+
+The ``cpumod`` directory is created only when the CPU MIDR matches a recognized
+Grace or Vera profile. CPUs with unsupported MIDRs are skipped without blocking
+module load or CPU hotplug and do not have a ``cpumod`` directory.
+
+The interface is intended for controlled performance characterization and
+evaluation. It is not intended as a general production tuning ABI, and the
+configuration should remain disabled by default on production systems.
+
+Configuration and placement
+===========================
+
+The controls are built when ``CONFIG_ARM64_CPUMOD`` is enabled. The code lives
+under ``arch/arm64/kernel/`` because the exposed state is CPU implementation
+control state accessed by the arm64 kernel, similar in placement to other
+architecture CPU-facing helpers.
+
+The ABI remains separate from the existing arm64 ``cpu*/regs`` sysfs files:
+``cpumod`` exposes a small set of named, range-checked control fields rather
+than a general raw register dump.
+
+CPU hotplug
+===========
+
+A ``cpumod`` directory is created only for online CPUs with a supported
+profile. The directory is removed when a CPU goes offline and recreated when
+the CPU comes back online, again only when its MIDR matches a supported
+profile. Reads and writes require the target CPU to be online.
+
+Firmware requirement
+====================
+
+The controls require firmware to permit EL1 reads and writes to the relevant
+CPU implementation control registers. On systems where firmware traps or
+blocks those accesses, the interface cannot be used.
+
+Current ABI
+===========
+
+Common attributes:
+
+``affected_cpus``
+  Read-only decimal CPU identifier for the sysfs instance.
+
+``pf_dis``
+  Hardware prefetch disable control. Valid values are ``0`` and ``1``.
+
+``pf_mode``
+  Hardware prefetch aggressiveness mode. Valid values are ``0`` through ``9``.
+  Values ``10`` through ``15`` are reserved and rejected.
+
+Grace-only attributes:
+
+``cbusy_filter_threshold``
+  Valid values are ``0`` through ``3``.
+
+``cbusy_filter_window``
+  Valid values are ``0`` through ``3``.
+
+``cmc_min_ways``
+  Valid values are ``0`` through ``7``.
+
+Vera-only attributes:
+
+``l2spr_cmc_max_ways``
+  Valid values are ``0`` through ``7``.
+
+Invalid writes
+==============
+
+Writes outside the documented range fail with ``-EINVAL`` before the cached
+sysfs state or remote CPU register state is updated.
+
+Open register inventory
+=======================
+
+The first RFC intentionally exposes only the currently validated subset. A
+complete documented-field inventory, including L2CDP, should be reviewed before
+adding further ABI nodes.
diff --git a/Documentation/arch/arm64/index.rst b/Documentation/arch/arm64/index.rst
index 98052b4ef4a1e..9e085ce55d9c4 100644
--- a/Documentation/arch/arm64/index.rst
+++ b/Documentation/arch/arm64/index.rst
@@ -8,6 +8,7 @@ ARM64 Architecture
     :maxdepth: 1
 
     acpi_object_usage
+    arm-cpumod
     amu
     arm-acpi
     arm-cca
-- 
2.43.0