docs/design/psci-pd-tree.rst

7 #. A platform must export the ``plat_get_aff_count()`` and
8    ``plat_get_aff_state()`` APIs to enable the generic PSCI code to
9    populate a tree that describes the hierarchy of power domains in the
10    system. This approach is inflexible because a change to the topology
11    requires a change in the code.
13    It would be much simpler for the platform to describe its power domain tree
16 #. The generic PSCI code generates MPIDRs in order to populate the power domain
17    tree. It also uses an MPIDR to find a node in the tree. The assumption that
18    a platform will use exactly the same MPIDRs as generated by the generic PSCI
19    code is not scalable. The use of an MPIDR also restricts the number of
20    levels in the power domain tree to four.
22    Therefore, there is a need to decouple allocation of MPIDRs from the
23    mechanism used to populate the power domain topology tree.
25 #. The current arrangement of the power domain tree requires a binary search
26    over the sibling nodes at a particular level to find a specified power
27    domain node. During a power management operation, the tree is traversed from
28    a 'start' to an 'end' power level. The binary search is required to find the
30    start from a leaf node and follow the parent node pointer to reach the end
33    Therefore, there is a need to define data structures that implement the tree in
36 #. The attributes of a core power domain differ from the attributes of power
39    performing a power management operation on the core power domain.
41    Therefore, there is a need to implement the tree in a way which facilitates this
53 To fulfill requirement 1., the existing platform APIs
57 #. The first entry in the array specifies the number of power domains at the
58    highest power level implemented in the platform. This caters for platforms
59    where the power domain tree does not have a single root node, for example,
60    the FVP has two cluster power domains at the highest level (1).
62 #. Each subsequent entry corresponds to a power domain and contains the number
65 #. The size of the array minus the first entry will be equal to the number of
68 #. The value in each entry in the array is used to find the number of entries
69    to consider at the next level. The sum of the values (number of children) of
70    all the entries at a level specifies the number of entries in the array for
71    the next level.
73 The following example power domain topology tree will be used to describe the
110 This tree is defined by the platform as the array described above as follows:
124 To fulfill requirement 2., it is assumed that the platform assigns a
127 populate the tree.
129 ``plat_core_pos_by_mpidr(mpidr)`` will return the core index for the core
130 corresponding to the MPIDR. It will return an error (-1) if an MPIDR is passed
132 platform API have changed since it is required to validate the passed MPIDR. It
135 Another mandatory API, ``plat_my_core_pos()`` has been added to return the core
136 index for the calling core. This API provides a more lightweight mechanism to get
137 the index since there is no need to validate the MPIDR of the calling core.
139 The platform should assign the core indices (as illustrated in the diagram above)
140 such that, if the core nodes are numbered from left to right, then the index
141 for a core domain will be the same as the index returned by
143 relationship allows the core nodes to be allocated in a separate array
144 (requirement 4.) during ``psci_setup()`` in such an order that the index of the
145 core in the array is the same as the return value from these APIs.
150 For platforms where the number of allocated MPIDRs is equal to the number of
151 core power domains, for example, Juno and FVPs, the logic to convert an MPIDR to
155 It is possible that on some platforms, the allocation of MPIDRs is not
156 contiguous or certain cores have been disabled. This essentially means that the
157 MPIDRs have been sparsely allocated, that is, the size of the range of MPIDRs
158 used by the platform is not equal to the number of core power domains.
160 The platform could adopt one of the following approaches to deal with this
164    maintaining the relationship described earlier. This means that the power
166    disabled or absent. Entries will not be allocated in the tree for these
170    in the power domain descriptor, that is, the number of core nodes described
171    is equal to the size of the range of MPIDRs allocated. This approach will
172    lead to memory wastage since entries will be allocated in the tree but will
179 to represent leaf and non-leaf power domain nodes in the tree.
184      * The following two data structures implement the power domain tree. The tree
185      * is used to track the state of all the nodes i.e. power domain instances
186      * described by the platform. The tree consists of nodes that describe CPU power
192          * Index of the first CPU power domain node level 0 which has this node
198          * Number of CPU power domains which are siblings of the domain indexed
199          * by 'cpu_start_idx' i.e. all the domains in the range 'cpu_start_idx
204         /* Index of the parent power domain node */
213         /* Index of the parent power domain node */
219 The power domain tree is implemented as a combination of the following data
227 Populating the power domain tree
230 The ``populate_power_domain_tree()`` function in ``psci_setup.c`` implements the
231 algorithm to parse the power domain descriptor exported by the platform to
232 populate the two arrays. It is essentially a breadth-first-search. The nodes for
233 each level starting from the root are laid out one after another in the
241 For the example power domain tree illustrated above, the ``psci_cpu_pd_nodes``
242 will be populated as follows. The value in each entry is the index of the parent
276 each entry is the index of the parent node.
296 Each core can find its node in the ``psci_cpu_pd_nodes`` array using the
297 ``plat_my_core_pos()`` function. When a core is turned on, the normal world
299 the MPIDR before using it to find the corresponding core node. The non-core power