1 /*
2  *
3  * (C) COPYRIGHT 2010-2015 ARM Limited. All rights reserved.
4  *
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
8  * of such GNU licence.
9  *
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.
13  *
14  */
15 
16 
17 
18 
19 
20 /**
21  * @file mali_kbase_pm.h
22  * Power management API definitions
23  */
24 
25 #ifndef _KBASE_PM_H_
26 #define _KBASE_PM_H_
27 
28 #include "mali_kbase_hwaccess_pm.h"
29 
30 #define PM_ENABLE_IRQS       0x01
31 #define PM_HW_ISSUES_DETECT  0x02
32 
33 
34 /** Initialize the power management framework.
35  *
36  * Must be called before any other power management function
37  *
38  * @param kbdev     The kbase device structure for the device (must be a valid pointer)
39  *
40  * @return 0 if the power management framework was successfully initialized.
41  */
42 int kbase_pm_init(struct kbase_device *kbdev);
43 
44 /** Power up GPU after all modules have been initialized and interrupt handlers installed.
45  *
46  * @param kbdev     The kbase device structure for the device (must be a valid pointer)
47  *
48  * @param flags     Flags to pass on to kbase_pm_init_hw
49  *
50  * @return 0 if powerup was successful.
51  */
52 int kbase_pm_powerup(struct kbase_device *kbdev, unsigned int flags);
53 
54 /**
55  * Halt the power management framework.
56  * Should ensure that no new interrupts are generated,
57  * but allow any currently running interrupt handlers to complete successfully.
58  * The GPU is forced off by the time this function returns, regardless of
59  * whether or not the active power policy asks for the GPU to be powered off.
60  *
61  * @param kbdev     The kbase device structure for the device (must be a valid pointer)
62  */
63 void kbase_pm_halt(struct kbase_device *kbdev);
64 
65 /** Terminate the power management framework.
66  *
67  * No power management functions may be called after this
68  * (except @ref kbase_pm_init)
69  *
70  * @param kbdev     The kbase device structure for the device (must be a valid pointer)
71  */
72 void kbase_pm_term(struct kbase_device *kbdev);
73 
74 /** Increment the count of active contexts.
75  *
76  * This function should be called when a context is about to submit a job. It informs the active power policy that the
77  * GPU is going to be in use shortly and the policy is expected to start turning on the GPU.
78  *
79  * This function will block until the GPU is available.
80  *
81  * This function ASSERTS if a suspend is occuring/has occurred whilst this is
82  * in use. Use kbase_pm_contect_active_unless_suspending() instead.
83  *
84  * @note a Suspend is only visible to Kernel threads; user-space threads in a
85  * syscall cannot witness a suspend, because they are frozen before the suspend
86  * begins.
87  *
88  * @param kbdev     The kbase device structure for the device (must be a valid pointer)
89  */
90 void kbase_pm_context_active(struct kbase_device *kbdev);
91 
92 
93 /** Handler codes for doing kbase_pm_context_active_handle_suspend() */
94 enum kbase_pm_suspend_handler {
95 	/** A suspend is not expected/not possible - this is the same as
96 	 * kbase_pm_context_active() */
97 	KBASE_PM_SUSPEND_HANDLER_NOT_POSSIBLE,
98 	/** If we're suspending, fail and don't increase the active count */
99 	KBASE_PM_SUSPEND_HANDLER_DONT_INCREASE,
100 	/** If we're suspending, succeed and allow the active count to increase iff
101 	 * it didn't go from 0->1 (i.e., we didn't re-activate the GPU).
102 	 *
103 	 * This should only be used when there is a bounded time on the activation
104 	 * (e.g. guarantee it's going to be idled very soon after) */
105 	KBASE_PM_SUSPEND_HANDLER_DONT_REACTIVATE
106 };
107 
108 /** Suspend 'safe' variant of kbase_pm_context_active()
109  *
110  * If a suspend is in progress, this allows for various different ways of
111  * handling the suspend. Refer to @ref enum kbase_pm_suspend_handler for details.
112  *
113  * We returns a status code indicating whether we're allowed to keep the GPU
114  * active during the suspend, depending on the handler code. If the status code
115  * indicates a failure, the caller must abort whatever operation it was
116  * attempting, and potentially queue it up for after the OS has resumed.
117  *
118  * @param kbdev     The kbase device structure for the device (must be a valid pointer)
119  * @param suspend_handler The handler code for how to handle a suspend that might occur
120  * @return zero     Indicates success
121  * @return non-zero Indicates failure due to the system being suspending/suspended.
122  */
123 int kbase_pm_context_active_handle_suspend(struct kbase_device *kbdev, enum kbase_pm_suspend_handler suspend_handler);
124 
125 /** Decrement the reference count of active contexts.
126  *
127  * This function should be called when a context becomes idle. After this call the GPU may be turned off by the power
128  * policy so the calling code should ensure that it does not access the GPU's registers.
129  *
130  * @param kbdev     The kbase device structure for the device (must be a valid pointer)
131  */
132 void kbase_pm_context_idle(struct kbase_device *kbdev);
133 
134 /**
135  * Suspend the GPU and prevent any further register accesses to it from Kernel
136  * threads.
137  *
138  * This is called in response to an OS suspend event, and calls into the various
139  * kbase components to complete the suspend.
140  *
141  * @note the mechanisms used here rely on all user-space threads being frozen
142  * by the OS before we suspend. Otherwise, an IOCTL could occur that powers up
143  * the GPU e.g. via atom submission.
144  *
145  * @param kbdev     The kbase device structure for the device (must be a valid pointer)
146  */
147 void kbase_pm_suspend(struct kbase_device *kbdev);
148 
149 /**
150  * Resume the GPU, allow register accesses to it, and resume running atoms on
151  * the GPU.
152  *
153  * This is called in response to an OS resume event, and calls into the various
154  * kbase components to complete the resume.
155  *
156  * @param kbdev     The kbase device structure for the device (must be a valid pointer)
157  */
158 void kbase_pm_resume(struct kbase_device *kbdev);
159 
160 /**
161  * kbase_pm_vsync_callback - vsync callback
162  *
163  * @buffer_updated: 1 if a new frame was displayed, 0 otherwise
164  * @data: Pointer to the kbase device as returned by kbase_find_device()
165  *
166  * Callback function used to notify the power management code that a vsync has
167  * occurred on the display.
168  */
169 void kbase_pm_vsync_callback(int buffer_updated, void *data);
170 
171 #endif				/* _KBASE_PM_H_ */
172