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