1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 /* 3 * 4 * (C) COPYRIGHT 2020-2021 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_CSF_IPA_CONTROL_H_ 23 #define _KBASE_CSF_IPA_CONTROL_H_ 24 25 #include <mali_kbase.h> 26 27 /* 28 * Maximum index accepted to configure an IPA Control performance counter. 29 */ 30 #define KBASE_IPA_CONTROL_CNT_MAX_IDX ((u8)64 * 3) 31 32 /** 33 * struct kbase_ipa_control_perf_counter - Performance counter description 34 * 35 * @scaling_factor: Scaling factor by which the counter's value shall be 36 * multiplied. A scaling factor of 1 corresponds to units 37 * of 1 second if values are normalised by GPU frequency. 38 * @gpu_norm: Indicating whether counter values shall be normalized by 39 * GPU frequency. If true, returned values represent 40 * an interval of time expressed in seconds (when the scaling 41 * factor is set to 1). 42 * @type: Type of counter block for performance counter. 43 * @idx: Index of the performance counter inside the block. 44 * It may be dependent on GPU architecture. 45 * It cannot be greater than KBASE_IPA_CONTROL_CNT_MAX_IDX. 46 * 47 * This structure is used by clients of the IPA Control component to describe 48 * a performance counter that they intend to read. The counter is identified 49 * by block and index. In addition to that, the client also specifies how 50 * values shall be represented. Raw values are a number of GPU cycles; 51 * if normalized, they are divided by GPU frequency and become an interval 52 * of time expressed in seconds, since the GPU frequency is given in Hz. 53 * The client may specify a scaling factor to multiply counter values before 54 * they are divided by frequency, in case the unit of time of 1 second is 55 * too low in resolution. For instance: a scaling factor of 1000 implies 56 * that the returned value is a time expressed in milliseconds; a scaling 57 * factor of 1000 * 1000 implies that the returned value is a time expressed 58 * in microseconds. 59 */ 60 struct kbase_ipa_control_perf_counter { 61 u64 scaling_factor; 62 bool gpu_norm; 63 enum kbase_ipa_core_type type; 64 u8 idx; 65 }; 66 67 /** 68 * kbase_ipa_control_init - Initialize the IPA Control component 69 * 70 * @kbdev: Pointer to Kbase device. 71 */ 72 void kbase_ipa_control_init(struct kbase_device *kbdev); 73 74 /** 75 * kbase_ipa_control_term - Terminate the IPA Control component 76 * 77 * @kbdev: Pointer to Kbase device. 78 */ 79 void kbase_ipa_control_term(struct kbase_device *kbdev); 80 81 /** 82 * kbase_ipa_control_register - Register a client to the IPA Control component 83 * 84 * @kbdev: Pointer to Kbase device. 85 * @perf_counters: Array of performance counters the client intends to read. 86 * For each counter the client specifies block, index, 87 * scaling factor and whether it must be normalized by GPU 88 * frequency. 89 * @num_counters: Number of performance counters. It cannot exceed the total 90 * number of counters that exist on the IPA Control interface. 91 * @client: Handle to an opaque structure set by IPA Control if 92 * the registration is successful. This handle identifies 93 * a client's session and shall be provided in its future 94 * queries. 95 * 96 * A client needs to subscribe to the IPA Control component by declaring which 97 * performance counters it intends to read, and specifying a scaling factor 98 * and whether normalization is requested for each performance counter. 99 * The function shall configure the IPA Control interface accordingly and start 100 * a session for the client that made the request. A unique handle is returned 101 * if registration is successful in order to identify the client's session 102 * and be used for future queries. 103 * 104 * Return: 0 on success, negative -errno on error 105 */ 106 int kbase_ipa_control_register( 107 struct kbase_device *kbdev, 108 const struct kbase_ipa_control_perf_counter *perf_counters, 109 size_t num_counters, void **client); 110 111 /** 112 * kbase_ipa_control_unregister - Unregister a client from IPA Control 113 * 114 * @kbdev: Pointer to kbase device. 115 * @client: Handle to an opaque structure that identifies the client session 116 * to terminate, as returned by kbase_ipa_control_register. 117 * 118 * Return: 0 on success, negative -errno on error 119 */ 120 int kbase_ipa_control_unregister(struct kbase_device *kbdev, 121 const void *client); 122 123 /** 124 * kbase_ipa_control_query - Query performance counters 125 * 126 * @kbdev: Pointer to kbase device. 127 * @client: Handle to an opaque structure that identifies the client 128 * session, as returned by kbase_ipa_control_register. 129 * @values: Array of values queried from performance counters, whose 130 * length depends on the number of counters requested at 131 * the time of registration. Values are scaled and normalized 132 * and represent the difference since the last query. 133 * @num_values: Number of entries in the array of values that has been 134 * passed by the caller. It must be at least equal to the 135 * number of performance counters the client registered itself 136 * to read. 137 * @protected_time: Time spent in protected mode since last query, 138 * expressed in nanoseconds. This pointer may be NULL if the 139 * client doesn't want to know about this. 140 * 141 * A client that has already opened a session by registering itself to read 142 * some performance counters may use this function to query the values of 143 * those counters. The values returned are normalized by GPU frequency if 144 * requested and then multiplied by the scaling factor provided at the time 145 * of registration. Values always represent a difference since the last query. 146 * 147 * Performance counters are not updated while the GPU operates in protected 148 * mode. For this reason, returned values may be unreliable if the GPU has 149 * been in protected mode since the last query. The function returns success 150 * in that case, but it also gives a measure of how much time has been spent 151 * in protected mode. 152 * 153 * Return: 0 on success, negative -errno on error 154 */ 155 int kbase_ipa_control_query(struct kbase_device *kbdev, const void *client, 156 u64 *values, size_t num_values, 157 u64 *protected_time); 158 159 /** 160 * kbase_ipa_control_handle_gpu_power_on - Handle the GPU power on event 161 * 162 * @kbdev: Pointer to kbase device. 163 * 164 * This function is called after GPU has been powered and is ready for use. 165 * After the GPU power on, IPA Control component needs to ensure that the 166 * counters start incrementing again. 167 */ 168 void kbase_ipa_control_handle_gpu_power_on(struct kbase_device *kbdev); 169 170 /** 171 * kbase_ipa_control_handle_gpu_power_off - Handle the GPU power off event 172 * 173 * @kbdev: Pointer to kbase device. 174 * 175 * This function is called just before the GPU is powered off when it is still 176 * ready for use. 177 * IPA Control component needs to be aware of the GPU power off so that it can 178 * handle the query from Clients appropriately and return meaningful values 179 * to them. 180 */ 181 void kbase_ipa_control_handle_gpu_power_off(struct kbase_device *kbdev); 182 183 /** 184 * kbase_ipa_control_handle_gpu_reset_pre - Handle the pre GPU reset event 185 * 186 * @kbdev: Pointer to kbase device. 187 * 188 * This function is called when the GPU is about to be reset. 189 */ 190 void kbase_ipa_control_handle_gpu_reset_pre(struct kbase_device *kbdev); 191 192 /** 193 * kbase_ipa_control_handle_gpu_reset_post - Handle the post GPU reset event 194 * 195 * @kbdev: Pointer to kbase device. 196 * 197 * This function is called after the GPU has been reset. 198 */ 199 void kbase_ipa_control_handle_gpu_reset_post(struct kbase_device *kbdev); 200 201 #if MALI_UNIT_TEST 202 /** 203 * kbase_ipa_control_rate_change_notify_test - Notify GPU rate change 204 * (only for testing) 205 * 206 * @kbdev: Pointer to kbase device. 207 * @clk_index: Index of the clock for which the change has occurred. 208 * @clk_rate_hz: Clock frequency(Hz). 209 * 210 * Notify the IPA Control component about a GPU rate change. 211 */ 212 void kbase_ipa_control_rate_change_notify_test(struct kbase_device *kbdev, 213 u32 clk_index, u32 clk_rate_hz); 214 #endif /* MALI_UNIT_TEST */ 215 216 /** 217 * kbase_ipa_control_protm_entered - Tell IPA_CONTROL that protected mode 218 * has been entered. 219 * 220 * @kbdev: Pointer to kbase device. 221 * 222 * This function provides a means through which IPA_CONTROL can be informed 223 * that the GPU has entered protected mode. Since the GPU cannot access 224 * performance counters while in this mode, this information is useful as 225 * it implies (a) the values of these registers cannot change, so theres no 226 * point trying to read them, and (b) IPA_CONTROL has a means through which 227 * to record the duration of time the GPU is in protected mode, which can 228 * then be forwarded on to clients, who may wish, for example, to assume 229 * that the GPU was busy 100% of the time while in this mode. 230 */ 231 void kbase_ipa_control_protm_entered(struct kbase_device *kbdev); 232 233 /** 234 * kbase_ipa_control_protm_exited - Tell IPA_CONTROL that protected mode 235 * has been exited. 236 * 237 * @kbdev: Pointer to kbase device 238 * 239 * This function provides a means through which IPA_CONTROL can be informed 240 * that the GPU has exited from protected mode. 241 */ 242 void kbase_ipa_control_protm_exited(struct kbase_device *kbdev); 243 244 #endif /* _KBASE_CSF_IPA_CONTROL_H_ */ 245