feat(mpmm): add support for MPMM
MPMM - the Maximum Power Mitigation Mechanism - is an optional
microarchitectural feature present on some Armv9-A cores, introduced
with the Cortex-X2, Cortex-A710 and Cortex-A510 cores.
MPMM allows the SoC firmware to detect and limit high activity events
to assist in SoC processor power domain dynamic power budgeting and
limit the triggering of whole-rail (i.e. clock chopping) responses to
overcurrent conditions.
This feature is enabled via the `ENABLE_MPMM` build option.
Configuration can be done via FCONF by enabling `ENABLE_MPMM_FCONF`, or
by via the plaform-implemented `plat_mpmm_topology` function.
Change-Id: I77da82808ad4744ece8263f0bf215c5a091c3167
Signed-off-by: Chris Kay <chris.kay@arm.com>
diff --git a/docs/components/activity-monitors.rst b/docs/components/activity-monitors.rst
index ee280e2..dd45c43 100644
--- a/docs/components/activity-monitors.rst
+++ b/docs/components/activity-monitors.rst
@@ -10,6 +10,8 @@
the |AMU| prior to its exit from EL3, and will save and restore architected
|AMU| counters as necessary upon suspend and resume.
+.. _Activity Monitor Auxiliary Counters:
+
Auxiliary counters
------------------
diff --git a/docs/components/fconf/index.rst b/docs/components/fconf/index.rst
index 00a4e29..029f324 100644
--- a/docs/components/fconf/index.rst
+++ b/docs/components/fconf/index.rst
@@ -146,3 +146,4 @@
fconf_properties
amu-bindings
+ mpmm-bindings
diff --git a/docs/components/fconf/mpmm-bindings.rst b/docs/components/fconf/mpmm-bindings.rst
new file mode 100644
index 0000000..d3cc857
--- /dev/null
+++ b/docs/components/fconf/mpmm-bindings.rst
@@ -0,0 +1,48 @@
+Maximum Power Mitigation Mechanism (MPMM) Bindings
+==================================================
+
+|MPMM| support cannot be determined at runtime by the firmware. Instead, these
+DTB bindings allow the platform to communicate per-core support for |MPMM| via
+the ``HW_CONFIG`` device tree blob.
+
+Bindings
+^^^^^^^^
+
+.. contents::
+ :local:
+
+``/cpus/cpus/cpu*`` node properties
+"""""""""""""""""""""""""""""""""""
+
+The ``cpu`` node has been augmented to allow the platform to indicate support
+for |MPMM| on a given core.
+
++-------------------+-------+-------------+------------------------------------+
+| Property name | Usage | Value type | Description |
++===================+=======+=============+====================================+
+| ``supports-mpmm`` | O | ``<empty>`` | If present, indicates that |MPMM| |
+| | | | is available on this core. |
++-------------------+-------+-------------+------------------------------------+
+
+Example
+^^^^^^^
+
+An example system offering two cores, one with support for |MPMM| and one
+without, can be described as follows:
+
+.. code-block::
+
+ cpus {
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ cpu0@00000 {
+ ...
+
+ supports-mpmm;
+ };
+
+ cpu1@00100 {
+ ...
+ };
+ }
diff --git a/docs/components/index.rst b/docs/components/index.rst
index e467516..754526d 100644
--- a/docs/components/index.rst
+++ b/docs/components/index.rst
@@ -14,6 +14,7 @@
fconf/index
firmware-update
measured_boot/index
+ mpmm
platform-interrupt-controller-API
ras
romlib-design
diff --git a/docs/components/mpmm.rst b/docs/components/mpmm.rst
new file mode 100644
index 0000000..1b1c6d8
--- /dev/null
+++ b/docs/components/mpmm.rst
@@ -0,0 +1,30 @@
+Maximum Power Mitigation Mechanism (MPMM)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+|MPMM| is an optional microarchitectural power management mechanism supported by
+some Arm Armv9-A cores, beginning with the Cortex-X2, Cortex-A710 and
+Cortex-A510 cores. This mechanism detects and limits high-activity events to
+assist in |SoC| processor power domain dynamic power budgeting and limit the
+triggering of whole-rail (i.e. clock chopping) responses to overcurrent
+conditions.
+
+|MPMM| is enabled on a per-core basis by the EL3 runtime firmware. The presence
+of |MPMM| cannot be determined at runtime by the firmware, and therefore the
+platform must expose this information through one of two possible mechanisms:
+
+- |FCONF|, controlled by the ``ENABLE_MPMM_FCONF`` build option.
+- A platform implementation of the ``plat_mpmm_topology`` function (the
+ default).
+
+See :ref:`Maximum Power Mitigation Mechanism (MPMM) Bindings` for documentation
+on the |FCONF| device tree bindings.
+
+.. warning::
+
+ |MPMM| exposes gear metrics through the auxiliary |AMU| counters. An
+ external power controller can use these metrics to budget SoC power by
+ limiting the number of cores that can execute higher-activity workloads or
+ switching to a different DVFS operating point. When this is the case, the
+ |AMU| counters that make up the |MPMM| gears must be enabled by the EL3
+ runtime firmware - please see :ref:`Activity Monitor Auxiliary Counters` for
+ documentation on enabling auxiliary |AMU| counters.
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index 8a0167b..da8d554 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -265,6 +265,16 @@
partitioning in EL3, however. Platform initialisation code should configure
and use partitions in EL3 as required. This option defaults to ``0``.
+- ``ENABLE_MPMM``: Boolean option to enable support for the Maximum Power
+ Mitigation Mechanism supported by certain Arm cores, which allows the SoC
+ firmware to detect and limit high activity events to assist in SoC processor
+ power domain dynamic power budgeting and limit the triggering of whole-rail
+ (i.e. clock chopping) responses to overcurrent conditions. Defaults to ``0``.
+
+- ``ENABLE_MPMM_FCONF``: Enables configuration of MPMM through FCONF, which
+ allows platforms with cores supporting MPMM to describe them via the
+ ``HW_CONFIG`` device tree blob. Default is 0.
+
- ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE)
support within generic code in TF-A. This option is currently only supported
in BL2_AT_EL3, BL31, and BL32 (TSP) for AARCH64 binaries, and in BL32
diff --git a/docs/global_substitutions.txt b/docs/global_substitutions.txt
index a70f15e..af15146 100644
--- a/docs/global_substitutions.txt
+++ b/docs/global_substitutions.txt
@@ -25,6 +25,7 @@
.. |Linaro| replace:: :term:`Linaro`
.. |MMU| replace:: :term:`MMU`
.. |MPAM| replace:: :term:`MPAM`
+.. |MPMM| replace:: :term:`MPMM`
.. |MPIDR| replace:: :term:`MPIDR`
.. |MTE| replace:: :term:`MTE`
.. |OEN| replace:: :term:`OEN`
diff --git a/docs/glossary.rst b/docs/glossary.rst
index a062319..aeeb133 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -92,6 +92,10 @@
MPAM
Memory Partitioning And Monitoring. An optional Armv8.4 extension.
+ MPMM
+ Maximum Power Mitigation Mechanism, an optional power management mechanism
+ supported by some Arm Armv9-A cores.
+
MPIDR
Multiprocessor Affinity Register