1Activity Monitor Unit (AMU) Bindings
2====================================
3
4To support platform-defined Activity Monitor Unit (|AMU|) auxiliary counters
5through FCONF, the ``HW_CONFIG`` device tree accepts several |AMU|-specific
6nodes and properties.
7
8Bindings
9^^^^^^^^
10
11.. contents::
12    :local:
13
14``/cpus/cpus/cpu*`` node properties
15"""""""""""""""""""""""""""""""""""
16
17The ``cpu`` node has been augmented to support a handle to an associated |AMU|
18view, which should describe the counters offered by the core.
19
20+---------------+-------+---------------+-------------------------------------+
21| Property name | Usage | Value type    | Description                         |
22+===============+=======+===============+=====================================+
23| ``amu``       | O     | ``<phandle>`` | If present, indicates that an |AMU| |
24|               |       |               | is available and its counters are   |
25|               |       |               | described by the node provided.     |
26+---------------+-------+---------------+-------------------------------------+
27
28``/cpus/amus`` node properties
29""""""""""""""""""""""""""""""
30
31The ``amus`` node describes the |AMUs| implemented by the cores in the system.
32This node does not have any properties.
33
34``/cpus/amus/amu*`` node properties
35"""""""""""""""""""""""""""""""""""
36
37An ``amu`` node describes the layout and meaning of the auxiliary counter
38registers of one or more |AMUs|, and may be shared by multiple cores.
39
40+--------------------+-------+------------+------------------------------------+
41| Property name      | Usage | Value type | Description                        |
42+====================+=======+============+====================================+
43| ``#address-cells`` | R     | ``<u32>``  | Value shall be 1. Specifies that   |
44|                    |       |            | the ``reg`` property array of      |
45|                    |       |            | children of this node uses a       |
46|                    |       |            | single cell.                       |
47+--------------------+-------+------------+------------------------------------+
48| ``#size-cells``    | R     | ``<u32>``  | Value shall be 0. Specifies that   |
49|                    |       |            | no size is required in the ``reg`` |
50|                    |       |            | property in children of this node. |
51+--------------------+-------+------------+------------------------------------+
52
53``/cpus/amus/amu*/counter*`` node properties
54""""""""""""""""""""""""""""""""""""""""""""
55
56A ``counter`` node describes an auxiliary counter belonging to the parent |AMU|
57view.
58
59+-------------------+-------+-------------+------------------------------------+
60| Property name     | Usage | Value type  | Description                        |
61+===================+=======+=============+====================================+
62| ``reg``           | R     | array       | Represents the counter register    |
63|                   |       |             | index, and must be a single cell.  |
64+-------------------+-------+-------------+------------------------------------+
65| ``enable-at-el3`` | O     | ``<empty>`` | The presence of this property      |
66|                   |       |             | indicates that this counter should |
67|                   |       |             | be enabled prior to EL3 exit.      |
68+-------------------+-------+-------------+------------------------------------+
69
70Example
71^^^^^^^
72
73An example system offering four cores made up of two clusters, where the cores
74of each cluster share different |AMUs|, may use something like the following:
75
76.. code-block::
77
78    cpus {
79        #address-cells = <2>;
80        #size-cells = <0>;
81
82        amus {
83            amu0: amu-0 {
84                #address-cells = <1>;
85                #size-cells = <0>;
86
87                counterX: counter@0 {
88                    reg = <0>;
89
90                    enable-at-el3;
91                };
92
93                counterY: counter@1 {
94                    reg = <1>;
95
96                    enable-at-el3;
97                };
98            };
99
100            amu1: amu-1 {
101                #address-cells = <1>;
102                #size-cells = <0>;
103
104                counterZ: counter@0 {
105                    reg = <0>;
106
107                    enable-at-el3;
108                };
109            };
110        };
111
112        cpu0@00000 {
113            ...
114
115            amu = <&amu0>;
116        };
117
118        cpu1@00100 {
119            ...
120
121            amu = <&amu0>;
122        };
123
124        cpu2@10000 {
125            ...
126
127            amu = <&amu1>;
128        };
129
130        cpu3@10100 {
131            ...
132
133            amu = <&amu1>;
134        };
135    }
136
137In this situation, ``cpu0`` and ``cpu1`` (the two cores in the first cluster),
138share the view of their AMUs defined by ``amu0``. Likewise, ``cpu2`` and
139``cpu3`` (the two cores in the second cluster), share the view of their |AMUs|
140defined by ``amu1``. This will cause ``counterX`` and ``counterY`` to be enabled
141for both ``cpu0`` and ``cpu1``, and ``counterZ`` to be enabled for both ``cpu2``
142and ``cpu3``.
143