Message-ID: <20260203214342.584712-42-ben.horgan@arm.com>
Date: Tue,  3 Feb 2026 21:43:42 +0000
From: Ben Horgan <ben.horgan@....com>
To: ben.horgan@....com
Cc: amitsinght@...vell.com,
	baisheng.gao@...soc.com,
	baolin.wang@...ux.alibaba.com,
	carl@...amperecomputing.com,
	dave.martin@....com,
	david@...nel.org,
	dfustini@...libre.com,
	fenghuay@...dia.com,
	gshan@...hat.com,
	james.morse@....com,
	jonathan.cameron@...wei.com,
	kobak@...dia.com,
	lcherian@...vell.com,
	linux-arm-kernel@...ts.infradead.org,
	linux-kernel@...r.kernel.org,
	peternewman@...gle.com,
	punit.agrawal@....qualcomm.com,
	quic_jiles@...cinc.com,
	reinette.chatre@...el.com,
	rohit.mathew@....com,
	scott@...amperecomputing.com,
	sdonthineni@...dia.com,
	tan.shaopeng@...itsu.com,
	xhao@...ux.alibaba.com,
	catalin.marinas@....com,
	will@...nel.org,
	corbet@....net,
	maz@...nel.org,
	oupton@...nel.org,
	joey.gouly@....com,
	suzuki.poulose@....com,
	kvmarm@...ts.linux.dev,
	zengheng4@...wei.com,
	linux-doc@...r.kernel.org
Subject: [PATCH v4 41/41] arm64: mpam: Add initial MPAM documentation

MPAM (Memory Partitioning and Monitoring) is now exposed to user-space via
resctrl. Add some documentation so the user knows what features to expect.

Signed-off-by: James Morse <james.morse@....com>
Signed-off-by: Ben Horgan <ben.horgan@....com>
---
Changes by Ben:
Some tidying, update for current heuristics
---
 Documentation/arch/arm64/index.rst |  1 +
 Documentation/arch/arm64/mpam.rst  | 93 ++++++++++++++++++++++++++++++
 2 files changed, 94 insertions(+)
 create mode 100644 Documentation/arch/arm64/mpam.rst

diff --git a/Documentation/arch/arm64/index.rst b/Documentation/arch/arm64/index.rst
index 6a012c98bdcd..189fa760dade 100644
--- a/Documentation/arch/arm64/index.rst
+++ b/Documentation/arch/arm64/index.rst
@@ -23,6 +23,7 @@ ARM64 Architecture
     memory
     memory-tagging-extension
     mops
+    mpam
     perf
     pointer-authentication
     ptdump
diff --git a/Documentation/arch/arm64/mpam.rst b/Documentation/arch/arm64/mpam.rst
new file mode 100644
index 000000000000..0769bccff25e
--- /dev/null
+++ b/Documentation/arch/arm64/mpam.rst
@@ -0,0 +1,93 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+MPAM
+====
+
+What is MPAM
+============
+  MPAM (Memory Partitioning and Monitoring) is a feature in the CPUs and memory
+  system components such as the caches or memory controllers that allow memory
+  traffic to be labelled, partitioned and monitored.
+
+  Traffic is labelled by the CPU, based on the control or monitor group the
+  current task is assigned to using resctrl.  Partitioning policy can be set
+  using the schemata file in resctrl, and monitor values read via resctrl.
+  See Documentation/filesystems/resctrl.rst for more details.
+
+  This allows tasks that share memory system resources, such as caches, to be
+  isolated from each other according to the partitioning policy (so called noisy
+  neighbours).
+
+Supported Platforms
+===================
+  Use of this feature requires CPU support, support in the memory system
+  components, and a description from firmware of where the MPAM device controls
+  are in the MMIO address space. (e.g. the 'MPAM' ACPI table).
+
+  The MMIO device that provides MPAM controls/monitors for a memory system
+  component is called a memory system component. (MSC).
+
+  Because the user interface to MPAM is via resctrl, only MPAM features that are
+  compatible with resctrl can be exposed to user-space.
+
+  MSC are considered as a group based on the topology. MSC that correspond with
+  the L3 cache are considered together, it is not possible to mix MSC between L2
+  and L3 to 'cover' a resctrl schema.
+
+  The supported features are:
+    * Cache portion bitmap controls (CPOR) on the L2 or L3 caches.  To expose
+      CPOR at L2 or L3, every CPU must have a corresponding CPU cache at this
+      level that also supports the feature.  Mismatched big/little platforms are
+      not supported as resctrl's controls would then also depend on task
+      placement.
+
+    * Memory bandwidth maximum controls (MBW_MAX) on or after the L3 cache.
+      resctrl uses the L3 cache-id to identify where the memory bandwidth
+      control is applied. For this reason the platform must have an L3 cache
+      with cache-id's supplied by firmware. (It doesn't need to support MPAM.)
+
+      To be exported as the 'MB' schema, the topology of the group of MSC chosen
+      must match the topology of the L3 cache so that the cache-id's can be
+      repainted. For example: Platforms with Memory bandwidth maximum controls
+      on CPU-less NUMA nodes cannot expose the 'MB' schema to resctrl as these
+      nodes do not have a corresponding L3 cache. If the memory bandwidth
+      control is on the memory rather than the L3 then there must be a single
+      global L3 as otherwise it is unknown which L3 the traffic came from.
+
+      When the MPAM driver finds multiple groups of MSC it can use for the 'MB'
+      schema, it prefers the group closest to the L3 cache.
+
+    * Cache Storage Usage (CSU) counters can expose the 'llc_occupancy' provided
+      there is at least one CSU monitor on each MSC that makes up the L3 group.
+      Exposing CSU counters from other caches or devices is not supported.
+
+    * Memory Bandwidth Usage (MBWU) on or after the L3 cache.  resctrl uses the
+      L3 cache-id to identify where the memory bandwidth is measured. For this
+      reason the platform must have an L3 cache with cache-id's supplied by
+      firmware. (It doesn't need to support MPAM.)
+
+      Memory bandwidth monitoring makes use of MBWU monitors in each MSC that
+      makes up the L3 group. If there are more monitors than the maximum number
+      of control and monitor groups, these will be allocated and configured at
+      boot. Otherwise, the monitors will not be usable as they are required to
+      be free running. If the memory bandwidth monitoring is on the memory
+      rather than the L3 then there must be a single global L3 as otherwise it
+      is unknown which L3 the traffic came from.
+
+      To expose 'mbm_total_bytes', the topology of the group of MSC chosen must
+      match the topology of the L3 cache so that the cache-id's can be
+      repainted. For example: Platforms with Memory bandwidth monitors on
+      CPU-less NUMA nodes cannot expose 'mbm_total_bytes' as these nodes do not
+      have a corresponding L3 cache. 'mbm_local_bytes' is not exposed as MPAM
+      cannot distinguish local traffic from global traffic.
+
+Feature emulation
+=================
+  MPAM will emulate the Code Data Prioritisation (CDP) feature on all platforms.
+
+Reporting Bugs
+==============
+  If you are not seeing the counters or controls you expect please share the
+  debug messages produced when enabling dynamic debug and booting with:
+  dyndbg="file mpam_resctrl.c +pl"
-- 
2.43.0

Powered by blists - more mailing lists