1PSCI Performance Measurement
2============================
3
4TF-A provides two instrumentation tools for performing analysis of the PSCI
5implementation:
6
7* PSCI STAT
8* Runtime Instrumentation
9
10This page explains how they may be enabled and used to perform all varieties of
11analysis.
12
13Performance Measurement Framework
14---------------------------------
15
16The Performance Measurement Framework :ref:`PMF <firmware_design_pmf>`
17is a framework that provides mechanisms for collecting and retrieving timestamps
18at runtime from the Performance Measurement Unit
19(:ref:`PMU <Performance Monitoring Unit>`).
20The PMU is a generalized abstraction for accessing CPU hardware registers used to
21measure hardware events. This means, for instance, that the PMU might be used to
22place instrumentation points at logical locations in code for tracing purposes.
23
24TF-A utilises the PMF as a backend for the two instrumentation services it
25provides--PSCI Statistics and Runtime Instrumentation. The PMF is used by
26these services to facilitate collection and retrieval of timestamps. For
27instance, the PSCI Statistics service registers the PMF service
28``psci_svc`` to track its residency statistics.
29
30This is reserved a unique ID, name, and space in memory by the PMF. The
31framework provides a convenient interface for PSCI Statistics to retrieve
32values from ``psci_svc`` at runtime.  Alternatively, the service may be
33configured such that the PMF dumps those values to the console. A platform may
34choose to expose SMCs that allow retrieval of these timestamps from the
35service.
36
37This feature is enabled with the Boolean flag ``ENABLE_PMF``.
38
39PSCI Statistics
40---------------
41
42PSCI Statistics is a runtime service that provides residency statistics for
43power states used by the platform. The service tracks residency time and
44entry count. Residency time is the total time spent in a particular power
45state by a PE. The entry count is the number of times the PE has entered
46the power state. PSCI Statistics implements the optional functions
47``PSCI_STAT_RESIDENCY`` and ``PSCI_STAT_COUNT`` from the `PSCI`_
48specification.
49
50
51.. c:macro:: PSCI_STAT_RESIDENCY
52
53    :param target_cpu: Contains copy of affinity fields in the MPIDR register
54      for identifying the target core (See section 5.1.4 of `PSCI`_
55      specifications for more details).
56    :param power_state: identifier for a specific local
57      state. Generally, this parameter takes the same form as the power_state
58      parameter described for CPU_SUSPEND in section 5.4.2.
59
60    :returns: Time spent in ``power_state``, in microseconds, by ``target_cpu``
61      and the highest level expressed in ``power_state``.
62
63
64.. c:macro:: PSCI_STAT_COUNT
65
66    :param target_cpu: follows the same format as ``PSCI_STAT_RESIDENCY``.
67    :param power_state: follows the same format as ``PSCI_STAT_RESIDENCY``.
68
69    :returns: Number of times the state expressed in ``power_state`` has been
70      used by ``target_cpu`` and the highest level expressed in
71      ``power_state``.
72
73The implementation provides residency statistics only for low power states,
74and does this regardless of the entry mechanism into those states. The
75statistics it collects are set to 0 during shutdown or reset.
76
77PSCI Statistics is enabled with the Boolean build flag
78``ENABLE_PSCI_STAT``.  All Arm platforms utilise the PMF unless another
79collection backend is provided (``ENABLE_PMF`` is implicitly enabled).
80
81Runtime Instrumentation
82-----------------------
83
84The Runtime Instrumentation Service is an instrumentation tool that wraps
85around the PMF to provide timestamp data. Although the service is not
86restricted to PSCI, it is used primarily in TF-A to quantify the total time
87spent in the PSCI implementation. The tool can be used to instrument other
88components in TF-A as well. It is enabled with the Boolean flag
89``ENABLE_RUNTIME_INSTRUMENTATION``, and as with PSCI STAT, requires PMF to
90be enabled.
91
92In PSCI, this service provides instrumentation points in the
93following code paths:
94
95* Entry into the PSCI SMC handler
96* Exit from the PSCI SMC handler
97* Entry to low power state
98* Exit from low power state
99* Entry into cache maintenance operations in PSCI
100* Exit from cache maintenance operations in PSCI
101
102The service captures the cycle count, which allows for the time spent in the
103implementation to be calculated, given the frequency counter.
104
105PSCI SMC Handler Instrumentation
106~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107
108The timestamp during entry into the handler is captured as early as possible
109during the runtime exception, prior to entry into the handler itself. All
110timestamps are stored in memory for later retrieval. The exit timestamp is
111captured after normal return from the PSCI SMC handler, or, if a low power state
112was requested, it is captured in the warm boot path.
113
114*Copyright (c) 2023, Arm Limited. All rights reserved.*
115
116.. _PSCI: https://developer.arm.com/documentation/den0022/latest/
117