1 /*
2  * Arm SCP/MCP Software
3  * Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 
8 #ifndef MOD_PERF_CONTROLLER_H_
9 #define MOD_PERF_CONTROLLER_H_
10 
11 #include <fwk_id.h>
12 
13 #include <stdint.h>
14 
15 /*!
16  * \ingroup GroupModules
17  * \defgroup GroupPERF_CONTROLLER performance controller
18  * \{
19  */
20 
21 /*!
22  * \brief Core performance API.
23  */
24 struct mod_perf_controller_perf_api {
25     /*!
26      * \brief Set performance level for a controller.
27      *
28      * \param cluster_id Cluster identifier.
29      * \param performance_level Desirable performance level.
30      *
31      * \retval ::FWK_E_ACCESS Wrong id.
32      * \retval ::FWK_SUCCESS If the call is successful.
33      * \return One of the standard framework error codes.
34      */
35     int (*set_performance_level)(
36         fwk_id_t cluster_id,
37         uintptr_t cookie,
38         uint32_t performance_level);
39 };
40 
41 /*!
42  * \brief Performance driver interface.
43  */
44 struct mod_perf_controller_drv_api {
45     /*! Name of the driver */
46     const char *name;
47 
48     /*!
49      * \brief Set performance level for a performance domain.
50      *
51      * \param domain_id Domain identifier.
52      * \param performance_level Desirable performance level.
53      *
54      * \retval ::FWK_E_ACCESS Wrong id.
55      * \retval ::FWK_SUCCESS If the call is successful.
56      * \return One of the standard framework error codes.
57      */
58     int (*set_performance_level)(
59         fwk_id_t domain_id,
60         uintptr_t cookie,
61         uint32_t performance_level);
62 };
63 
64 /*!
65  * \brief Cluster apply performance granted API.
66  */
67 struct mod_perf_controller_apply_performance_granted_api {
68     /*!
69      * \brief Provides the means to apply the output performance level after
70      *      setting the power limits for each cluster.
71      *
72      * \retval ::FWK_SUCCESS If the call is successful.
73      * \return One of the standard framework error codes.
74      */
75     int (*apply_performance_granted)(void);
76 };
77 
78 /*!
79  * \brief Power Model API
80  */
81 struct mod_perf_controller_power_model_api {
82     /*!
83      * \brief Converts from power value to the corresponding
84      *        performance level.
85      *
86      * \param model_id Power model identifier.
87      * \param power Power value.
88      * \param[out] perfomance_level
89      *
90      * \retval ::FWK_SUCCESS If the call is successful.
91      * \return One of the standard framework error codes.
92      */
93     int (*power_to_performance)(
94         fwk_id_t model_id,
95         uint32_t power,
96         uint32_t *performance_level);
97 };
98 
99 struct mod_perf_controller_cluster_config {
100     /*! Module or element identifier of the performance driver. */
101     fwk_id_t performance_driver_id;
102 
103     /*! API identifier of the performance driver. */
104     fwk_id_t performance_driver_api_id;
105 
106     /*! Module or element identifier of the power model driver. */
107     fwk_id_t power_model_id;
108 
109     /*! API identifier of the power model driver. */
110     fwk_id_t power_model_api_id;
111 
112     /*! Initial performance limit. */
113     uint32_t initial_performance_limit;
114 };
115 
116 /*!
117  * \brief Performance controller API IDs
118  */
119 enum mod_perf_controller_api_idx {
120     /*! Index for the core performance adjustments API */
121     MOD_PERF_CONTROLLER_CLUSTER_PERF_API = 0U,
122 
123     /*! Index for the cluster power adjustments API */
124     MOD_PERF_CONTROLLER_CORE_POWER_API,
125 
126     /*! Index for the controller apply performance granted API*/
127     MOD_PERF_CONTROLLER_APPLY_PERFORMANCE_GRANTED_API,
128 
129     /*! Number of APIs */
130     MOD_PERF_CONTROLLER_API_COUNT
131 };
132 
133 /*!
134  * \}
135  */
136 
137 #endif /* MOD_PERF_CONTROLLER_H_ */
138