1\ingroup GroupModules Modules 2\defgroup GroupDvfs Dynamic Voltage and Frequency Scaling (DVFS) 3 4# DVFS Module Architecture {#module_dvfs_architecture_architecture} 5 6## Overview {#module_dvfs_architecture_overview} 7 8This module implements a Hardware Abstraction Layer (HAL) API for DVFS 9transactions. 10 11The DVFS (Dynamic Voltage and Frequency Scaling) module provides an 12interface for modules to get and set the operating frequency level 13and limits for a DVFS/performance domain. 14 15The DVFS module defines a driver interface on which it relies to read and set 16the voltage and frequency of the clock and PSU devices for each DVFS domain. 17 18A response event notifies the caller of the transaction completion if required. 19 20This module complies with the deferred response architecture. 21 22### DVFS asynchronous operations {#module_dvfs_architecture_set} 23 24The DVFS module implements the SCMI Performance domain management protocol 25`PERFORMANCE_LIMITS_GET`/`SET` and `PERFORMANCE_LEVEL_GET`/`SET` commands. 26 27The DVFS module uses a "fire and forget" mechanism for the `set_level`/ 28'set_limits` operations. These operations will only report the status of 29the initial issuing/queueing of the operation, they do not report the status 30of the operation itself. 31 32The request may fail when it is eventually executed but the agent will not 33be notified of the failure. A failing request will be retried a number of times 34but will be discarded if it cannot be completed within those retries. 35 36Note that a `set_level` operation will not be retried upon failure. 37 38A `set_limits` request will be retried a maximum of `DVFS_MAX_RETRIES` times. 39 40The DVFS `set_level`/`set_limits` operations return to the requestor immediately 41the request has been queued for later execution. 42 43If a DVFS/performance domain receives a `set_limits`/`set_level` request which 44cannot be initiated immediately it queues the request for later processing. 45If there is a request already pending/queued for that domain the new request 46will overwrite the pending request. There is only ever a single pending/queued 47request with the last level/limits values requested. 48 49## DVFS set frequency/limits flow {#module_dvfs_architecture_flow} 50 511) DVFS_set_limits(domain, limits) 52 53 Find the frequency corresponding to the Operating Performance Point (OPP) 54 for the requested limits. 55 56 If the DVFS domain is busy go to (3). 57 58 Queue event_set_frequency event for DVFS module using the frequency from 59 the OPP. 60 61 The request has been queued, return SUCCESS to agent. 62 63 The request will now be handled asynchronously, go to (4). 64 652) DVFS_set_level(domain, level) 66 67 Find the frequency corresponding to the Operating Performance Point (OPP) 68 for the requested level. 69 70 If the DVFS domain is busy go to (3). 71 72 Queue event_set_frequency event for DVFS module using the frequency from 73 the OPP. 74 75 The request has been queued, return SUCCESS to agent. 76 77 The request will now be handled asynchronously, go to (4). 78 793) DVFS domain request in progress(domain, OPP) 80 81 Is there a request pending already ? 82 Yes. 83 Overwrite the request OPP with the new OPP. 84 No. 85 Set the initial values for the pending request. 86 number of retries, OPP, etc. 87 Exit. 88 89 904) DVFS asynchronous set frequency, process_event(domain, frequency) 91 92 event_set_frequency received by the DVFS event handler, 93 mod_dvfs_process_event() 94 - Retrieve the OPP (voltage, frequency) for the requested frequency. 95 This OPP is now the target OPP. 96 - Get the voltage from the domain PSU (*) or use the current value if 97 available. 98 If the current voltage is less than the requested voltage 99 Increase the voltage to the OPP voltage (*) 100 Set the frequency to the OPP frequency (*) 101 Else if the current voltage is higher than the requested voltage 102 Set the frequency to the OPP frequency (*) 103 Decrease the voltage to the OPP voltage (*) 104 - DVFS set_level operation complete, check status. 105 - SUCCESS 106 Does the domain have a request pending, (see 3 above) ? 107 Yes, go to (5) with the frequency from the _pending_ 108 request. 109 No, all done, exit. 110 - FAILURE 111 Does this request require a retry ? 112 Yes. 113 Increment the total number of retries for this request. 114 115 If the maximum number of attempts for this request has not 116 yet been tried go to (5) using the frequency from the 117 _current_ request. 118 119 Maximum number of attempts has been reached, discard the 120 request. 121 122 Does the domain have a request pending, (see 3 above) ? 123 Yes, go to (5) with the frequency from the _pending_ 124 request. 125 No, all done, exit. 126 No. 127 Discard the current request. 128 Does the domain have a request pending, (see 3 above) ? 129 Yes, go to (5) with the frequency from the _pending_ 130 request. 131 No, all done, exit. 132 133(*) Note that this operation may be asynchronous and in that case will follow 134the deferred_response architecture. 135 1365) Start next request(domain, frequency) 137 138 Does the domain have a timer configured ? 139 Yes. 140 141 Start the timer. When the callback triggers go to (2). 142 143 We use a timer with a short delay to start the next request rather 144 than starting the operation immediately. This is configurable for 145 each platform. This may be required for platforms which have a 146 slow bus, eg I2C, to allow the transaction which is currently in 147 progress to cpmplete before we initiate the next request. 148 149 No. 150 Go to (2). Start the next request immediately. 151