On Mon, Aug 17, 2026 at 10:23:34AM +0800, KobaK wrote: > From: Koba Ko <[email protected]> > > 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 <[email protected]> > Reviewed-by: Tushar Dave <[email protected]> > Reviewed-by: Kai-Heng Feng <[email protected]> > Signed-off-by: Koba Ko <[email protected]> > --- > 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
