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

[Rob Herring <robh@kernel.org>]

On Mon, Aug 17, 2026 at 10:23:34AM +0800, KobaK wrote:
> 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.

How does the kernel discover if the interface can be enabled? Write a 
register and if we're still alive we can enable it?

> +
> +Current ABI

Is the future ABI going to be different? ;)

> +===========
> +
> +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``.

There is already a standard way to document sysfs entries. Use that.

Rob