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

[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. Document affected_cpus as
world-readable read-only (0444), and the six register-backed controls as
root-only read/write (0600). Out-of-range writes are documented as failing
before 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>
---
 .../ABI/testing/sysfs-devices-system-cpu      | 77 +++++++++++++++++++
 Documentation/arch/arm64/arm-cpumod.rst       | 66 ++++++++++++++++
 Documentation/arch/arm64/index.rst            |  1 +
 3 files changed, 144 insertions(+)
 create mode 100644 Documentation/arch/arm64/arm-cpumod.rst

diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 82d10d556cc89..7275399e33435 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -806,3 +806,80 @@ Date:		Nov 2022
 Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
 Description:
 		(RO) the list of CPUs that can be brought online.
+
+What:		/sys/devices/system/cpu/cpuX/cpumod/affected_cpus
+Date:		August 2026
+Contact:	Koba Ko <kobak@nvidia.com>
+Contact:	Linux ARM Kernel mailing list <linux-arm-kernel@lists.infradead.org>
+Description:
+		(RO) The decimal logical CPU identifier for this cpumod sysfs
+		instance. The file is present only while CPU X is online and its
+		MIDR matches a supported Grace or Vera profile. The file is
+		world-readable and read-only (0444).
+
+What:		/sys/devices/system/cpu/cpuX/cpumod/pf_dis
+Date:		August 2026
+Contact:	Koba Ko <kobak@nvidia.com>
+Contact:	Linux ARM Kernel mailing list <linux-arm-kernel@lists.infradead.org>
+Description:
+		(RW) Hardware prefetch disable control for CPU X. The file is
+		present only while a supported Grace or Vera CPU is online. Reads
+		return a decimal value. Writes accept decimal values 0 and 1.
+		Invalid writes fail with -EINVAL without changing the target CPU
+		register. The file is root-only read/write (0600).
+
+What:		/sys/devices/system/cpu/cpuX/cpumod/pf_mode
+Date:		August 2026
+Contact:	Koba Ko <kobak@nvidia.com>
+Contact:	Linux ARM Kernel mailing list <linux-arm-kernel@lists.infradead.org>
+Description:
+		(RW) Hardware prefetch aggressiveness mode for CPU X. The file is
+		present only while a supported Grace or Vera CPU is online. Reads
+		return a decimal value. Writes accept decimal values 0 through 9;
+		values 10 through 15 are reserved and rejected. Invalid writes fail
+		with -EINVAL without changing the target CPU register. The file is
+		root-only read/write (0600).
+
+What:		/sys/devices/system/cpu/cpuX/cpumod/cbusy_filter_threshold
+Date:		August 2026
+Contact:	Koba Ko <kobak@nvidia.com>
+Contact:	Linux ARM Kernel mailing list <linux-arm-kernel@lists.infradead.org>
+Description:
+		(RW) Grace CPU cache-busy filter threshold. The file is present only
+		while a supported Grace CPU is online. Reads return a decimal value.
+		Writes accept decimal values 0 through 3. Invalid writes fail with
+		-EINVAL without changing the target CPU register. The file is
+		root-only read/write (0600).
+
+What:		/sys/devices/system/cpu/cpuX/cpumod/cbusy_filter_window
+Date:		August 2026
+Contact:	Koba Ko <kobak@nvidia.com>
+Contact:	Linux ARM Kernel mailing list <linux-arm-kernel@lists.infradead.org>
+Description:
+		(RW) Grace CPU cache-busy filter window. The file is present only
+		while a supported Grace CPU is online. Reads return a decimal value.
+		Writes accept decimal values 0 through 3. Invalid writes fail with
+		-EINVAL without changing the target CPU register. The file is
+		root-only read/write (0600).
+
+What:		/sys/devices/system/cpu/cpuX/cpumod/cmc_min_ways
+Date:		August 2026
+Contact:	Koba Ko <kobak@nvidia.com>
+Contact:	Linux ARM Kernel mailing list <linux-arm-kernel@lists.infradead.org>
+Description:
+		(RW) Grace CPU cache-management minimum-way control. The file is
+		present only while a supported Grace CPU is online. Reads return a
+		decimal value. Writes accept decimal values 0 through 7. Invalid
+		writes fail with -EINVAL without changing the target CPU register.
+		The file is root-only read/write (0600).
+
+What:		/sys/devices/system/cpu/cpuX/cpumod/l2spr_cmc_max_ways
+Date:		August 2026
+Contact:	Koba Ko <kobak@nvidia.com>
+Contact:	Linux ARM Kernel mailing list <linux-arm-kernel@lists.infradead.org>
+Description:
+		(RW) Vera CPU cache-management maximum-way control. The file is
+		present only while a supported Vera CPU is online. Reads return a
+		decimal value. Writes accept decimal values 0 through 7. Invalid
+		writes fail with -EINVAL without changing the target CPU register.
+		The file is root-only read/write (0600).
diff --git a/Documentation/arch/arm64/arm-cpumod.rst b/Documentation/arch/arm64/arm-cpumod.rst
new file mode 100644
index 0000000000000..cf4ef9baf165f
--- /dev/null
+++ b/Documentation/arch/arm64/arm-cpumod.rst
@@ -0,0 +1,66 @@
+.. 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.
+
+Sysfs interface
+===============
+
+The ``cpumod`` sysfs attributes are documented in
+``Documentation/ABI/testing/sysfs-devices-system-cpu``.
+``affected_cpus`` is world-readable and read-only (0444). The register-backed
+controls are root-only read/write files (0600).
+
+Invalid writes
+==============
+
+Writes outside the documented range fail with ``-EINVAL`` before the 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