1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
2 /*
3 *
4 * (C) COPYRIGHT 2016-2022 ARM Limited. All rights reserved.
5 *
6 * This program is free software and is provided to you under the terms of the
7 * GNU General Public License version 2 as published by the Free Software
8 * Foundation, and any use by you of this program is subject to the terms
9 * of such GNU license.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, you can access it online at
18 * http://www.gnu.org/licenses/gpl-2.0.html.
19 *
20 */
21
22 #ifndef _KBASE_IPA_H_
23 #define _KBASE_IPA_H_
24
25 #if defined(CONFIG_MALI_BIFROST_DEVFREQ) && defined(CONFIG_DEVFREQ_THERMAL)
26
27 struct devfreq;
28
29 /**
30 * enum kbase_ipa_block_type - Type of block for which power estimation is done.
31 *
32 * @KBASE_IPA_BLOCK_TYPE_USING_CLK_MALI:
33 * Blocks using clk_mali in dts.
34 * @KBASE_IPA_BLOCK_TYPE_TOP_LEVEL: Top-level block, that covers CSHW,
35 * MEMSYS, Tiler.
36 * @KBASE_IPA_BLOCK_TYPE_SHADER_CORES: All Shader cores.
37 * @KBASE_IPA_BLOCK_TYPE_FOR_CLK_GPU: Dummy for clk_gpu in dts.
38 * @KBASE_IPA_BLOCK_TYPE_NUM: Number of blocks.
39 */
40 enum kbase_ipa_block_type {
41 KBASE_IPA_BLOCK_TYPE_USING_CLK_MALI,
42 KBASE_IPA_BLOCK_TYPE_TOP_LEVEL,
43 KBASE_IPA_BLOCK_TYPE_SHADER_CORES,
44 KBASE_IPA_BLOCK_TYPE_FOR_CLK_GPU,
45 KBASE_IPA_BLOCK_TYPE_NUM
46 };
47
48 /**
49 * struct kbase_ipa_model - Object describing a particular IPA model.
50 * @kbdev: pointer to kbase device
51 * @model_data: opaque pointer to model specific data, accessed
52 * only by model specific methods.
53 * @ops: pointer to object containing model specific methods.
54 * @params: head of the list of debugfs params added for model
55 * @missing_dt_node_warning: flag to limit the matching power model DT not found
56 * warning to once.
57 */
58 struct kbase_ipa_model {
59 struct kbase_device *kbdev;
60 void *model_data;
61 const struct kbase_ipa_model_ops *ops;
62 struct list_head params;
63 bool missing_dt_node_warning;
64 };
65
66 /**
67 * kbase_ipa_model_add_param_s32 - Add an integer model parameter
68 * @model: pointer to IPA model
69 * @name: name of corresponding debugfs entry
70 * @addr: address where the value is stored
71 * @num_elems: number of elements (1 if not an array)
72 * @dt_required: if false, a corresponding devicetree entry is not required,
73 * and the current value will be used. If true, a warning is
74 * output and the data is zeroed
75 *
76 * Return: 0 on success, or an error code
77 */
78 int kbase_ipa_model_add_param_s32(struct kbase_ipa_model *model,
79 const char *name, s32 *addr,
80 size_t num_elems, bool dt_required);
81
82 /**
83 * kbase_ipa_model_add_param_string - Add a string model parameter
84 * @model: pointer to IPA model
85 * @name: name of corresponding debugfs entry
86 * @addr: address where the value is stored
87 * @size: size, in bytes, of the value storage (so the maximum string
88 * length is size - 1)
89 * @dt_required: if false, a corresponding devicetree entry is not required,
90 * and the current value will be used. If true, a warning is
91 * output and the data is zeroed
92 *
93 * Return: 0 on success, or an error code
94 */
95 int kbase_ipa_model_add_param_string(struct kbase_ipa_model *model,
96 const char *name, char *addr,
97 size_t size, bool dt_required);
98
99 struct kbase_ipa_model_ops {
100 char *name;
101 /* The init, recalculate and term ops on the default model are always
102 * called. However, all the other models are only invoked if the model
103 * is selected in the device tree. Otherwise they are never
104 * initialized. Additional resources can be acquired by models in
105 * init(), however they must be terminated in the term().
106 */
107 int (*init)(struct kbase_ipa_model *model);
108 /* Called immediately after init(), or when a parameter is changed, so
109 * that any coefficients derived from model parameters can be
110 * recalculated
111 */
112 int (*recalculate)(struct kbase_ipa_model *model);
113 void (*term)(struct kbase_ipa_model *model);
114 /*
115 * get_dynamic_coeff() - calculate dynamic power coefficient
116 * @model: pointer to model
117 * @coeffp: pointer to return value location
118 *
119 * Calculate a dynamic power coefficient, with units pW/(Hz V^2), which
120 * is then scaled by the IPA framework according to the current OPP's
121 * frequency and voltage.
122 *
123 * Return: 0 on success, or an error code. -EOVERFLOW error code will
124 * indicate that sampling interval was too large and no meaningful
125 * scaling for GPU utiliation can be done.
126 */
127 int (*get_dynamic_coeff)(struct kbase_ipa_model *model, u32 *coeffp);
128 /*
129 * get_static_coeff() - calculate static power coefficient
130 * @model: pointer to model
131 * @coeffp: pointer to return value location
132 *
133 * Calculate a static power coefficient, with units uW/(V^3), which is
134 * scaled by the IPA framework according to the current OPP's voltage.
135 *
136 * Return: 0 on success, or an error code.
137 */
138 int (*get_static_coeff)(struct kbase_ipa_model *model, u32 *coeffp);
139
140 /*
141 * reset_counter_data() - Reset the HW counter data used for calculating
142 * dynamic power coefficient
143 * @model: pointer to model
144 *
145 * This method is currently applicable only to the counter based model.
146 * The next call to get_dynamic_coeff() will have to calculate the
147 * dynamic power coefficient based on the HW counter data generated
148 * from this point onwards.
149 */
150 void (*reset_counter_data)(struct kbase_ipa_model *model);
151 };
152
153 /**
154 * kbase_ipa_init - Initialize the IPA feature
155 * @kbdev: pointer to kbase device
156 *
157 * simple IPA power model is initialized as a fallback model and if that
158 * initialization fails then IPA is not used.
159 * The device tree is read for the name of ipa model to be used, by using the
160 * property string "ipa-model". If that ipa model is supported then it is
161 * initialized but if the initialization fails then simple power model is used.
162 *
163 * Return: 0 on success, negative -errno on error
164 */
165 int kbase_ipa_init(struct kbase_device *kbdev);
166
167 /**
168 * kbase_ipa_term - Terminate the IPA feature
169 * @kbdev: pointer to kbase device
170 *
171 * Both simple IPA power model and model retrieved from device tree are
172 * terminated.
173 */
174 void kbase_ipa_term(struct kbase_device *kbdev);
175
176 /**
177 * kbase_ipa_model_recalculate - Recalculate the model coefficients
178 * @model: pointer to the IPA model object, already initialized
179 *
180 * It shall be called immediately after the model has been initialized
181 * or when the model parameter has changed, so that any coefficients
182 * derived from parameters can be recalculated.
183 * Its a wrapper for the module specific recalculate() method.
184 *
185 * Return: 0 on success, negative -errno on error
186 */
187 int kbase_ipa_model_recalculate(struct kbase_ipa_model *model);
188
189 /**
190 * kbase_ipa_model_ops_find - Lookup an IPA model using its name
191 * @kbdev: pointer to kbase device
192 * @name: name of model to lookup
193 *
194 * Return: Pointer to model's 'ops' structure, or NULL if the lookup failed.
195 */
196 const struct kbase_ipa_model_ops *kbase_ipa_model_ops_find(struct kbase_device *kbdev,
197 const char *name);
198
199 /**
200 * kbase_ipa_counter_model_ops_find - Lookup an IPA counter model using its name
201 * @kbdev: pointer to kbase device
202 * @name: name of counter model to lookup
203 *
204 * Return: Pointer to counter model's 'ops' structure, or NULL if the lookup
205 * failed.
206 */
207 const struct kbase_ipa_model_ops *kbase_ipa_counter_model_ops_find(
208 struct kbase_device *kbdev, const char *name);
209
210 /**
211 * kbase_ipa_model_name_from_id - Find the best model for a given GPU ID
212 * @gpu_id: GPU ID of GPU the model will be used for
213 *
214 * Return: The name of the appropriate counter-based model, or the name of the
215 * fallback model if no counter model exists.
216 */
217 const char *kbase_ipa_model_name_from_id(u32 gpu_id);
218
219 /**
220 * kbase_ipa_counter_model_name_from_id - Find the best counter model for a
221 * given GPU ID
222 * @gpu_id: GPU ID of GPU the counter model will be used for
223 *
224 * Return: The name of the appropriate counter-based model, or NULL if the
225 * no counter model exists.
226 */
227 const char *kbase_ipa_counter_model_name_from_id(u32 gpu_id);
228
229 /**
230 * kbase_ipa_init_model - Initilaize the particular IPA model
231 * @kbdev: pointer to kbase device
232 * @ops: pointer to object containing model specific methods.
233 *
234 * Initialize the model corresponding to the @ops pointer passed.
235 * The init() method specified in @ops would be called.
236 *
237 * Return: pointer to kbase_ipa_model on success, NULL on error
238 */
239 struct kbase_ipa_model *kbase_ipa_init_model(struct kbase_device *kbdev,
240 const struct kbase_ipa_model_ops *ops);
241 /**
242 * kbase_ipa_term_model - Terminate the particular IPA model
243 * @model: pointer to the IPA model object, already initialized
244 *
245 * Terminate the model, using the term() method.
246 * Module specific parameters would be freed.
247 */
248 void kbase_ipa_term_model(struct kbase_ipa_model *model);
249
250 /**
251 * kbase_ipa_protection_mode_switch_event - Inform IPA of the GPU's entry into
252 * protected mode
253 * @kbdev: pointer to kbase device
254 *
255 * Makes IPA aware of the GPU switching to protected mode.
256 */
257 void kbase_ipa_protection_mode_switch_event(struct kbase_device *kbdev);
258
259 /**
260 * kbase_get_real_power() - get the real power consumption of the GPU
261 * @df: dynamic voltage and frequency scaling information for the GPU.
262 * @power: where to store the power consumption, in mW.
263 * @freq: a frequency, in HZ.
264 * @voltage: a voltage, in mV.
265 *
266 * The returned value incorporates both static and dynamic power consumption.
267 *
268 * Return: 0 on success, or an error code.
269 */
270 int kbase_get_real_power(struct devfreq *df, u32 *power,
271 unsigned long freq,
272 unsigned long voltage);
273
274 /* Called by kbase_get_real_power() to invoke the power models.
275 * Must be called with kbdev->ipa.lock held.
276 * This function is only exposed for use by unit tests.
277 */
278 int kbase_get_real_power_locked(struct kbase_device *kbdev, u32 *power,
279 unsigned long freq,
280 unsigned long voltage);
281
282 extern struct devfreq_cooling_power kbase_ipa_power_model_ops;
283
284 /**
285 * kbase_ipa_reset_data() - Reset the data required for power estimation.
286 * @kbdev: Pointer to kbase device.
287 *
288 * This function is called to ensure a meaningful baseline for
289 * kbase_get_real_power(), when thermal governor starts the polling, and
290 * that is achieved by updating the GPU utilization metrics and retrieving
291 * the accumulated value of HW counters.
292 * Basically this function collects all the data required for power estimation
293 * but does not process it.
294 */
295 void kbase_ipa_reset_data(struct kbase_device *kbdev);
296
297 #else /* !(defined(CONFIG_MALI_BIFROST_DEVFREQ) && defined(CONFIG_DEVFREQ_THERMAL)) */
298
kbase_ipa_protection_mode_switch_event(struct kbase_device * kbdev)299 static inline void kbase_ipa_protection_mode_switch_event(struct kbase_device *kbdev)
300 { }
301
302 #endif /* (defined(CONFIG_MALI_BIFROST_DEVFREQ) && defined(CONFIG_DEVFREQ_THERMAL)) */
303
304 #endif
305