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