3 * (C) COPYRIGHT 2010-2015 ARM Limited. All rights reserved.
5 * This program is free software and is provided to you under the terms of the
6 * GNU General Public License version 2 as published by the Free Software
7 * Foundation, and any use by you of this program is subject to the terms
10 * A copy of the licence is included with the program, and can also be obtained
11 * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
12 * Boston, MA 02110-1301, USA.
21 * @file mali_kbase_config.h
22 * Configuration API and Attributes for KBase
25 #ifndef _KBASE_CONFIG_H_
26 #define _KBASE_CONFIG_H_
30 #include <mali_malisw.h>
31 #include <mali_kbase_backend_config.h>
34 * @addtogroup base_api
39 * @addtogroup base_kbase_api
44 * @addtogroup kbase_config Configuration API and Attributes
48 #if !MALI_CUSTOMER_RELEASE
49 /* This flag is set for internal builds so we can run tests without credentials. */
50 #define KBASE_HWCNT_DUMP_BYPASS_ROOT 1
52 #define KBASE_HWCNT_DUMP_BYPASS_ROOT 0
55 #include <linux/rbtree.h>
57 /* Forward declaration of struct kbase_device */
61 * kbase_platform_funcs_conf - Specifies platform init/term function pointers
63 * Specifies the functions pointers for platform specific initialization and
64 * termination. By default no functions are required. No additional platform
65 * specific control is necessary.
67 struct kbase_platform_funcs_conf {
69 * platform_init_func - platform specific init function pointer
70 * @kbdev - kbase_device pointer
72 * Returns 0 on success, negative error code otherwise.
74 * Function pointer for platform specific initialization or NULL if no
75 * initialization function is required. At the point this the GPU is
76 * not active and its power and clocks are in unknown (platform specific
77 * state) as kbase doesn't yet have control of power and clocks.
79 * The platform specific private pointer kbase_device::platform_context
80 * can be accessed (and possibly initialized) in here.
82 int (*platform_init_func)(struct kbase_device *kbdev);
84 * platform_term_func - platform specific termination function pointer
85 * @kbdev - kbase_device pointer
87 * Function pointer for platform specific termination or NULL if no
88 * termination function is required. At the point this the GPU will be
89 * idle but still powered and clocked.
91 * The platform specific private pointer kbase_device::platform_context
92 * can be accessed (and possibly terminated) in here.
94 void (*platform_term_func)(struct kbase_device *kbdev);
98 * @brief Specifies the callbacks for power management
100 * By default no callbacks will be made and the GPU must not be powered off.
102 struct kbase_pm_callback_conf {
103 /** Callback for when the GPU is idle and the power to it can be switched off.
105 * The system integrator can decide whether to either do nothing, just switch off
106 * the clocks to the GPU, or to completely power down the GPU.
107 * The platform specific private pointer kbase_device::platform_context can be accessed and modified in here. It is the
108 * platform \em callbacks responsiblity to initialize and terminate this pointer if used (see @ref kbase_platform_funcs_conf).
110 void (*power_off_callback)(struct kbase_device *kbdev);
112 /** Callback for when the GPU is about to become active and power must be supplied.
114 * This function must not return until the GPU is powered and clocked sufficiently for register access to
115 * succeed. The return value specifies whether the GPU was powered down since the call to power_off_callback.
116 * If the GPU state has been lost then this function must return 1, otherwise it should return 0.
117 * The platform specific private pointer kbase_device::platform_context can be accessed and modified in here. It is the
118 * platform \em callbacks responsiblity to initialize and terminate this pointer if used (see @ref kbase_platform_funcs_conf).
120 * The return value of the first call to this function is ignored.
122 * @return 1 if the GPU state may have been lost, 0 otherwise.
124 int (*power_on_callback)(struct kbase_device *kbdev);
126 /** Callback for when the system is requesting a suspend and GPU power
127 * must be switched off.
129 * Note that if this callback is present, then this may be called
130 * without a preceding call to power_off_callback. Therefore this
131 * callback must be able to take any action that might otherwise happen
132 * in power_off_callback.
134 * The platform specific private pointer kbase_device::platform_context
135 * can be accessed and modified in here. It is the platform \em
136 * callbacks responsibility to initialize and terminate this pointer if
137 * used (see @ref kbase_platform_funcs_conf).
139 void (*power_suspend_callback)(struct kbase_device *kbdev);
141 /** Callback for when the system is resuming from a suspend and GPU
142 * power must be switched on.
144 * Note that if this callback is present, then this may be called
145 * without a following call to power_on_callback. Therefore this
146 * callback must be able to take any action that might otherwise happen
147 * in power_on_callback.
149 * The platform specific private pointer kbase_device::platform_context
150 * can be accessed and modified in here. It is the platform \em
151 * callbacks responsibility to initialize and terminate this pointer if
152 * used (see @ref kbase_platform_funcs_conf).
154 void (*power_resume_callback)(struct kbase_device *kbdev);
156 /** Callback for handling runtime power management initialization.
158 * The runtime power management callbacks @ref power_runtime_off_callback and @ref power_runtime_on_callback
159 * will become active from calls made to the OS from within this function.
160 * The runtime calls can be triggered by calls from @ref power_off_callback and @ref power_on_callback.
161 * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature.
163 * @return 0 on success, else int erro code.
165 int (*power_runtime_init_callback)(struct kbase_device *kbdev);
167 /** Callback for handling runtime power management termination.
169 * The runtime power management callbacks @ref power_runtime_off_callback and @ref power_runtime_on_callback
170 * should no longer be called by the OS on completion of this function.
171 * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature.
173 void (*power_runtime_term_callback)(struct kbase_device *kbdev);
175 /** Callback for runtime power-off power management callback
177 * For linux this callback will be called by the kernel runtime_suspend callback.
178 * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature.
180 * @return 0 on success, else OS error code.
182 void (*power_runtime_off_callback)(struct kbase_device *kbdev);
184 /** Callback for runtime power-on power management callback
186 * For linux this callback will be called by the kernel runtime_resume callback.
187 * Note: for linux the kernel must have CONFIG_PM_RUNTIME enabled to use this feature.
189 int (*power_runtime_on_callback)(struct kbase_device *kbdev);
192 * Optional callback for checking if GPU can be suspended when idle
194 * This callback will be called by the runtime power management core
195 * when the reference count goes to 0 to provide notification that the
196 * GPU now seems idle.
198 * If this callback finds that the GPU can't be powered off, or handles
199 * suspend by powering off directly or queueing up a power off, a
200 * non-zero value must be returned to prevent the runtime PM core from
201 * also triggering a suspend.
203 * Returning 0 will cause the runtime PM core to conduct a regular
206 * This callback is optional and if not provided regular ausosuspend
209 * Note: The Linux kernel must have CONFIG_PM_RUNTIME enabled to use
212 * Return 0 if GPU can be suspended, positive value if it can not be
213 * suspeneded by runtime PM, else OS error code
215 int (*power_runtime_idle_callback)(struct kbase_device *kbdev);
219 * kbase_cpuprops_get_default_clock_speed - default for CPU_SPEED_FUNC
220 * @clock_speed - see kbase_cpu_clk_speed_func for details on the parameters
222 * Returns 0 on success, negative error code otherwise.
224 * Default implementation of CPU_SPEED_FUNC. This function sets clock_speed
225 * to 100, so will be an underestimate for any real system.
227 int kbase_cpuprops_get_default_clock_speed(u32 * const clock_speed);
230 * kbase_cpu_clk_speed_func - Type of the function pointer for CPU_SPEED_FUNC
231 * @param clock_speed - pointer to store the current CPU clock speed in MHz
233 * Returns 0 on success, otherwise negative error code.
235 * This is mainly used to implement OpenCL's clGetDeviceInfo().
237 typedef int (*kbase_cpu_clk_speed_func) (u32 *clock_speed);
240 * kbase_gpu_clk_speed_func - Type of the function pointer for GPU_SPEED_FUNC
241 * @param clock_speed - pointer to store the current GPU clock speed in MHz
243 * Returns 0 on success, otherwise negative error code.
244 * When an error is returned the caller assumes maximum GPU speed stored in
247 * If the system timer is not available then this function is required
248 * for the OpenCL queue profiling to return correct timing information.
251 typedef int (*kbase_gpu_clk_speed_func) (u32 *clock_speed);
254 struct kbase_platform_config {
259 * @brief Specifies start and end of I/O memory region.
261 struct kbase_io_memory_region {
267 * @brief Specifies I/O related resources like IRQs and memory region for I/O operations.
269 struct kbase_io_resources {
273 struct kbase_io_memory_region io_memory_region;
276 struct kbase_platform_config {
277 const struct kbase_io_resources *io_resources;
280 #endif /* CONFIG_OF */
283 * @brief Gets the pointer to platform config.
285 * @return Pointer to the platform config
287 struct kbase_platform_config *kbase_get_platform_config(void);
290 * kbasep_platform_device_init: - Platform specific call to initialize hardware
291 * @kbdev: kbase device pointer
293 * Function calls a platform defined routine if specified in the configuration
294 * attributes. The routine can initialize any hardware and context state that
295 * is required for the GPU block to function.
297 * Return: 0 if no errors have been found in the config.
298 * Negative error code otherwise.
300 int kbasep_platform_device_init(struct kbase_device *kbdev);
303 * kbasep_platform_device_term - Platform specific call to terminate hardware
304 * @kbdev: Kbase device pointer
306 * Function calls a platform defined routine if specified in the configuration
307 * attributes. The routine can destroy any platform specific context state and
308 * shut down any hardware functionality that are outside of the Power Management
312 void kbasep_platform_device_term(struct kbase_device *kbdev);
316 * kbase_platform_early_init - Early initialisation of the platform code
318 * This function will be called when the module is loaded to perform any
319 * early initialisation required by the platform code. Such as reading
320 * platform specific device tree entries for the GPU.
322 * Return: 0 for success, any other fail causes module initialisation to fail
324 int kbase_platform_early_init(void);
327 #ifdef CONFIG_MALI_PLATFORM_FAKE
329 * kbase_platform_fake_register - Register a platform device for the GPU
331 * This can be used to register a platform device on systems where device tree
332 * is not enabled and the platform initialisation code in the kernel doesn't
333 * create the GPU device. Where possible device tree should be used instead.
335 * Return: 0 for success, any other fail causes module initialisation to fail
337 int kbase_platform_fake_register(void);
340 * kbase_platform_fake_unregister - Unregister a fake platform device
342 * Unregister the platform device created with kbase_platform_fake_register()
344 void kbase_platform_fake_unregister(void);
348 /** @} *//* end group kbase_config */
349 /** @} *//* end group base_kbase_api */
350 /** @} *//* end group base_api */
352 #endif /* _KBASE_CONFIG_H_ */