feat(amu): enable per-core AMU auxiliary counters
This change makes AMU auxiliary counters configurable on a per-core
basis, controlled by `ENABLE_AMU_AUXILIARY_COUNTERS`.
Auxiliary counters can be described via the `HW_CONFIG` device tree if
the `ENABLE_AMU_FCONF` build option is enabled, or the platform must
otherwise implement the `plat_amu_topology` function.
A new phandle property for `cpu` nodes (`amu`) has been introduced to
the `HW_CONFIG` specification to allow CPUs to describe the view of
their own AMU:
```
cpu0: cpu@0 {
...
amu = <&cpu0_amu>;
};
```
Multiple cores may share an `amu` handle if they implement the
same set of auxiliary counters.
AMU counters are described for one or more AMUs through the use of a new
`amus` node:
```
amus {
cpu0_amu: amu-0 {
#address-cells = <1>;
#size-cells = <0>;
counter@0 {
reg = <0>;
enable-at-el3;
};
counter@n {
reg = <n>;
...
};
};
};
```
This structure describes the **auxiliary** (group 1) AMU counters.
Architected counters have architecturally-defined behaviour, and as
such do not require DTB entries.
These `counter` nodes support two properties:
- The `reg` property represents the counter register index.
- The presence of the `enable-at-el3` property determines whether
the firmware should enable the counter prior to exiting EL3.
Change-Id: Ie43aee010518c5725a3b338a4899b0857caf4c28
Signed-off-by: Chris Kay <chris.kay@arm.com>
diff --git a/docs/components/activity-monitors.rst b/docs/components/activity-monitors.rst
index 57d81f8..ee280e2 100644
--- a/docs/components/activity-monitors.rst
+++ b/docs/components/activity-monitors.rst
@@ -10,6 +10,23 @@
the |AMU| prior to its exit from EL3, and will save and restore architected
|AMU| counters as necessary upon suspend and resume.
+Auxiliary counters
+------------------
+
+FEAT_AMUv1 describes a set of implementation-defined auxiliary counters (also
+known as group 1 counters), controlled by the ``ENABLE_AMU_AUXILIARY_COUNTERS``
+build option.
+
+As a security precaution, Trusted Firmware-A does not enable these by default.
+Instead, platforms may configure their auxiliary counters through one of two
+possible mechanisms:
+
+- |FCONF|, controlled by the ``ENABLE_AMU_FCONF`` build option.
+- A platform implementation of the ``plat_amu_topology`` function (the default).
+
+See :ref:`Activity Monitor Unit (AMU) Bindings` for documentation on the |FCONF|
+device tree bindings.
+
--------------
*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/components/fconf/amu-bindings.rst b/docs/components/fconf/amu-bindings.rst
new file mode 100644
index 0000000..047f75e
--- /dev/null
+++ b/docs/components/fconf/amu-bindings.rst
@@ -0,0 +1,142 @@
+Activity Monitor Unit (AMU) Bindings
+====================================
+
+To support platform-defined Activity Monitor Unit (|AMU|) auxiliary counters
+through FCONF, the ``HW_CONFIG`` device tree accepts several |AMU|-specific
+nodes and properties.
+
+Bindings
+^^^^^^^^
+
+.. contents::
+ :local:
+
+``/cpus/cpus/cpu*`` node properties
+"""""""""""""""""""""""""""""""""""
+
+The ``cpu`` node has been augmented to support a handle to an associated |AMU|
+view, which should describe the counters offered by the core.
+
++---------------+-------+---------------+-------------------------------------+
+| Property name | Usage | Value type | Description |
++===============+=======+===============+=====================================+
+| ``amu`` | O | ``<phandle>`` | If present, indicates that an |AMU| |
+| | | | is available and its counters are |
+| | | | described by the node provided. |
++---------------+-------+---------------+-------------------------------------+
+
+``/cpus/amus`` node properties
+""""""""""""""""""""""""""""""
+
+The ``amus`` node describes the |AMUs| implemented by the cores in the system.
+This node does not have any properties.
+
+``/cpus/amus/amu*`` node properties
+"""""""""""""""""""""""""""""""""""
+
+An ``amu`` node describes the layout and meaning of the auxiliary counter
+registers of one or more |AMUs|, and may be shared by multiple cores.
+
++--------------------+-------+------------+------------------------------------+
+| Property name | Usage | Value type | Description |
++====================+=======+============+====================================+
+| ``#address-cells`` | R | ``<u32>`` | Value shall be 1. Specifies that |
+| | | | the ``reg`` property array of |
+| | | | children of this node uses a |
+| | | | single cell. |
++--------------------+-------+------------+------------------------------------+
+| ``#size-cells`` | R | ``<u32>`` | Value shall be 0. Specifies that |
+| | | | no size is required in the ``reg`` |
+| | | | property in children of this node. |
++--------------------+-------+------------+------------------------------------+
+
+``/cpus/amus/amu*/counter*`` node properties
+""""""""""""""""""""""""""""""""""""""""""""
+
+A ``counter`` node describes an auxiliary counter belonging to the parent |AMU|
+view.
+
++-------------------+-------+-------------+------------------------------------+
+| Property name | Usage | Value type | Description |
++===================+=======+=============+====================================+
+| ``reg`` | R | array | Represents the counter register |
+| | | | index, and must be a single cell. |
++-------------------+-------+-------------+------------------------------------+
+| ``enable-at-el3`` | O | ``<empty>`` | The presence of this property |
+| | | | indicates that this counter should |
+| | | | be enabled prior to EL3 exit. |
++-------------------+-------+-------------+------------------------------------+
+
+Example
+^^^^^^^
+
+An example system offering four cores made up of two clusters, where the cores
+of each cluster share different |AMUs|, may use something like the following:
+
+.. code-block::
+
+ cpus {
+ #address-cells = <2>;
+ #size-cells = <0>;
+
+ amus {
+ amu0: amu-0 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ counterX: counter@0 {
+ reg = <0>;
+
+ enable-at-el3;
+ };
+
+ counterY: counter@1 {
+ reg = <1>;
+
+ enable-at-el3;
+ };
+ };
+
+ amu1: amu-1 {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ counterZ: counter@0 {
+ reg = <0>;
+
+ enable-at-el3;
+ };
+ };
+ };
+
+ cpu0@00000 {
+ ...
+
+ amu = <&amu0>;
+ };
+
+ cpu1@00100 {
+ ...
+
+ amu = <&amu0>;
+ };
+
+ cpu2@10000 {
+ ...
+
+ amu = <&amu1>;
+ };
+
+ cpu3@10100 {
+ ...
+
+ amu = <&amu1>;
+ };
+ }
+
+In this situation, ``cpu0`` and ``cpu1`` (the two cores in the first cluster),
+share the view of their AMUs defined by ``amu0``. Likewise, ``cpu2`` and
+``cpu3`` (the two cores in the second cluster), share the view of their |AMUs|
+defined by ``amu1``. This will cause ``counterX`` and ``counterY`` to be enabled
+for both ``cpu0`` and ``cpu1``, and ``counterZ`` to be enabled for both ``cpu2``
+and ``cpu3``.
diff --git a/docs/components/fconf/index.rst b/docs/components/fconf/index.rst
index 9020633..00a4e29 100644
--- a/docs/components/fconf/index.rst
+++ b/docs/components/fconf/index.rst
@@ -145,3 +145,4 @@
:maxdepth: 1
fconf_properties
+ amu-bindings
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index f9999e1..8a0167b 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -224,6 +224,10 @@
(also known as group 1 counters). These are implementation-defined counters,
and as such require additional platform configuration. Default is 0.
+- ``ENABLE_AMU_FCONF``: Enables configuration of the AMU through FCONF, which
+ allows platforms with auxiliary counters to describe them via the
+ ``HW_CONFIG`` device tree blob. Default is 0.
+
- ``ENABLE_ASSERTIONS``: This option controls whether or not calls to ``assert()``
are compiled out. For debug builds, this option defaults to 1, and calls to
``assert()`` are left in place. For release builds, this option defaults to 0