Power.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015-2019, Texas Instruments Incorporated
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
12  * * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  *
16  * * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 /*!****************************************************************************
33  * @file Power.h
34  * @brief Power Manager
35  *
36  * @anchor ti_drivers_Power_Overview
37  * # Overview
38  *
39  * The Power Manager facilitates the transition of the MCU from active states
40  * to sleep states and vice versa. It provides other drivers the
41  * ability to set and release dependencies on hardware resources, and keeps
42  * reference counts on each resource to know when to enable or disable the
43  * resource. It provides drivers the ability to register callback functions
44  * to be invoked upon specific power events. In addition, drivers and
45  * applications can set or release constraints to prevent the MCU from
46  * transitioning into specific active or sleep states. Refer to the device
47  * specific power driver header file device specific information.
48  *
49  * <hr>
50  * @anchor ti_drivers_Power_Usage
51  * # Usage
52  *
53  * This documentation provides a basic @ref ti_drivers_Power_Synopsis
54  * "usage summary" and a set of @ref ti_drivers_Power_Examples "examples"
55  * in the form of commented code fragments. Detailed descriptions of the
56  * APIs are provided in subsequent sections.
57  * @anchor ti_drivers_Power_Synopsis
58  * ## Synopsis
59  * @anchor ti_drivers_Power_Synopsis_Code
60  *
61  * @note <b> The following example demonstrates usage of some of the Power
62  * driver APIs.This example is intended for reference only and is not intended
63  * for application use. You should refer to the device specific Power driver
64  * header for valid API usage and arguments. </b>
65  *
66  *
67  * @code
68  * // Import Power Driver definitions
69  * #include <ti/drivers/Power.h>
70  *
71  * // One-time initialization of Power manager
72  * Power_init();
73  *
74  * // Set power dependency on a resource
75  * status = Power_setDependency(resourceId);
76  * if (status != Power_SOK) {
77  * // Error occurred
78  * }
79  *
80  * // Set a power constraint
81  * status = Power_setConstraint(constraintId);
82  * if (status != Power_SOK) {
83  * // Error occurred
84  * }
85  *
86  * // Other application code
87  *
88  * // Release a previously set power constraint
89  * status = Power_releaseConstraint(constraintId);
90  * if (status != Power_SOK) {
91  * // Error occurred
92  * }
93  *
94  * status = Power_releaseDependency(resourceId);
95  * if (status != Power_SOK) {
96  * // Error occurred
97  * }
98  * @endcode
99  *
100  *
101  * <hr>
102  * @anchor ti_drivers_Power_Examples
103  * # Examples
104  *
105  * @note
106  * <b>The following examples are intended for reference only and are not
107  * intended for application use. You should refer to the device specific
108  * Power driver header file for more usage information.</b>
109  *
110  * @li @ref ti_drivers_Power_Examples_enable "Enabling power policy"
111  * @li @ref ti_drivers_Power_Examples_disable "Disabling power policy"
112  * @li @ref ti_drivers_Power_Examples_constraint "Using power constraints"
113  * @li @ref ti_drivers_Power_Examples_dependency "Using power dependency"
114  * @li @ref ti_drivers_Power_Examples_notify "Using power notify"
115  * @li @ref ti_drivers_Power_Examples_transistion "Power transitions"
116  *
117  *
118  * @anchor ti_drivers_Power_Examples_enable
119  * ## Enabling Power Policy
120  *
121  * @code
122  * // Import Power Driver definitions
123  * #include <ti/drivers/Power.h>
124  *
125  * // One-time initialization of Power manager
126  * Power_init();
127  *
128  * // Enable power policy
129  * Power_enablePolicy();
130  * @endcode
131  *
132  *
133  * @anchor ti_drivers_Power_Examples_disable
134  * ## Disabling Power Policy
135  *
136  * @code
137  * // Import Power Driver definitions
138  * #include <ti/drivers/Power.h>
139  *
140  * bool flag;
141  *
142  * // One-time initialization of Power manager
143  * Power_init();
144  *
145  * // Disable power policy
146  * flag = Power_disablePolicy();
147  * if (flag == false) {
148  * // Power policy was already disabled
149  * }
150  * @endcode
151  *
152  *
153  * @anchor ti_drivers_Power_Examples_constraint
154  * ## Using Power Constraints
155  *
156  * @code
157  * // Import Power Driver definitions
158  * #include <ti/drivers/Power.h>
159  *
160  * uint32_t mask;
161  * int16_t status;
162  *
163  * // One-time initialization of Power manager
164  * Power_init();
165  *
166  * // Set a power constraint
167  * status = Power_setConstraint(constraintId);
168  * if (status != Power_SOK) {
169  * // Error occurred setting constraint
170  * }
171  *
172  * // Read mask of currently set power constraints
173  * mask = Power_getConstraintMask();
174  *
175  * // Release previously set constraint
176  * status = Power_releaseConstraint(constraintId);
177  * if (status != Power_SOK) {
178  * // Error occurred releasing constraint
179  * }
180  * @endcode
181  *
182  *
183  * @anchor ti_drivers_Power_Examples_dependency
184  * ## Using Power Dependency
185  *
186  * @code
187  * // Import Power Driver definitions
188  * #include <ti/drivers/Power.h>
189  *
190  * int16_t count;
191  * int16_t status;
192  *
193  * // One-time initialization of Power manager
194  * Power_init();
195  *
196  * // Set a power dependency
197  * status = Power_setDependency(resourceId);
198  * if (status != Power_SOK) {
199  * // Error occurred setting dependency
200  * }
201  *
202  * // Get the dependency count of the resource
203  * count = Power_getDependencyCount(resourceId);
204  * if (count == Power_EINVALIDINPUT) {
205  * // Invalid resourceId used
206  * }
207  *
208  * if (count > 0) {
209  * // At least 1 dependency exists for the resource.
210  * // Regardless, we may safely release the dependency when we
211  * // no longer need the resource.
212  * }
213  *
214  * // Release a power dependency
215  * status = Power_releaseDependency(resourceId);
216  * if (status != Power_SOK) {
217  * // Error occurred releasing dependency
218  * }
219  * @endcode
220  *
221  *
222  * @anchor ti_drivers_Power_Examples_notify
223  * ## Using Power Notify
224  *
225  * The application must define a #Power_NotifyFxn function and
226  * allocate memory for the #Power_NotifyObj object.
227  *
228  * @code
229  * // Import Power Driver definitions
230  * #include <ti/drivers/Power.h>
231  *
232  * // Application Power_NotifyObj object
233  * Power_NotifyObj powerNotifyObj;
234  *
235  * // Application Power_NotifyFxn function prototype
236  * static int postNotifyFxn(unsigned int eventType, uintptr_t eventArg,
237  * uintptr_t clientArg);
238  * @endcode
239  *
240  * The application must register for the event. Here, we use pseudo event
241  * names. You should refer to the device specific power driver header file
242  * for eventTypes. Inside the infinite loop, we wait for a semaphore to be
243  * post from our notification callback.
244  *
245  * @code
246  * // Application thread
247  * void thread(void)
248  * {
249  * int16_t status;
250  * unsigned int eventTypes = LOW_POWER_EXIT | LOW_POWER_ENTER;
251  * uintptr_t clientArg = semaphoreHandle;
252  *
253  * status = Power_registerNotify(&powerNotifyObj, eventTypes,
254  * postNotifyFxn, clientArg);
255  *
256  * while (1)
257  * {
258  * sem_wait(semaphoreHandle);
259  * // Do something
260  *
261  * // Unregister for the notification. After this call,
262  * // our postNotifyFxn() will never be called again unless
263  * // we use Power_registerNotify() again.
264  * Power_unregisterNotify(&powerNotifyObj);
265  *
266  * break;
267  * }
268  * }
269  * @endcode
270  *
271  * The application may implement the power notify function to fit their
272  * needs. The #Power_NotifyFxn should always return #Power_NOTIFYDONE or
273  * #Power_NOTIFYERROR.
274  *
275  * @code
276  * // Application Power_NotifyFxn function implementation
277  * static int postNotifyFxn(unsigned int eventType, uintptr_t eventArg,
278  * uintptr_t clientArg)
279  * {
280  * sem_t semaphoreHandle = (sem_t) clientArg;
281  *
282  * if (eventType == LOW_POWER_EXIT) {
283  * sem_post(semaphoreHandle);
284  * return (Power_NOTIFYDONE);
285  * }
286  *
287  * if (eventType == LOW_POWER_ENTER) {
288  * // Store something in RAM
289  * return (Power_NOTIFYDONE);
290  * }
291  *
292  * // We received an unexpected event type
293  * return (Power_NOTIFYERROR);
294  * }
295  * @endcode
296  *
297  *
298  * @anchor ti_drivers_Power_Examples_transistion
299  * ## Power transitions
300  *
301  * @code
302  * // Import Power Driver definitions
303  * #include <ti/drivers/Power.h>
304  *
305  * uint32_t totalLatency, resumeLatency;
306  * int16_t status;
307  *
308  * // One-time initialization of Power manager
309  * Power_init();
310  *
311  * // Get the current power transition state
312  * status = Power_getTransitionState();
313  *
314  * switch (status)
315  * {
316  * case Power_ACTIVE:
317  * // No transitions in progress
318  * break;
319  * case Power_ENTERING_SLEEP:
320  * // Transition to sleep in progress
321  * break;
322  * case Power_EXITING_SLEEP:
323  * // Transition from sleep in progress
324  * break;
325  * case Power_CHANGING_PERF_LEVEL:
326  * // Performance level change in progress
327  * break;
328  * }
329  *
330  * // Get the Power_TOTAL and Power_RESUME transition latency for a
331  * // device specific sleepState. Latency is in microseconds.
332  * totalLatency = Power_getTransitionLatency(sleepState, Power_TOTAL);
333  * resumeLatency = Power_getTransitionLatency(sleepState, Power_RESUME);
334  * @endcode
335  *
336  *
337  * <hr>
338  * @anchor ti_drivers_Power_Configuration
339  * # Configuration
340  *
341  * @note The Power Manager APIs and configuration parameters are described here.
342  * For a detailed description of terms and concepts, and usage by different
343  * types of software components (peripheral drivers, power policies,
344  * and applications) please see the
345  * <a href='../../Power_Management.pdf'>SimpleLink SDK Power Management User's Guide</a>.
346  * <hr>
347  ******************************************************************************
348  */
349 
350 #ifndef ti_drivers_Power__include
351 #define ti_drivers_Power__include
352 
353 /* @cond */
354 #include <stdbool.h>
355 #include <stdint.h>
356 /* @endcond */
357 
358 #include <ti/drivers/utils/List.h>
359 
360 #ifdef __cplusplus
361 extern "C" {
362 #endif
363 
367 #define Power_TOTAL (1U)
368 #define Power_RESUME (2U)
374 #define Power_NOTIFYDONE (0)
375 #define Power_NOTIFYERROR (-1)
381 #define Power_SOK (0)
382 #define Power_EFAIL (-1)
383 #define Power_EINVALIDINPUT (-2)
384 #define Power_EINVALIDPOINTER (-3)
385 #define Power_ECHANGE_NOT_ALLOWED (-4)
386 #define Power_EBUSY (-5)
392 #define Power_ACTIVE (1U)
393 #define Power_ENTERING_SLEEP (2U)
394 #define Power_EXITING_SLEEP (3U)
395 #define Power_ENTERING_SHUTDOWN (4U)
396 #define Power_CHANGING_PERF_LEVEL (5U)
402 typedef void (*Power_PolicyInitFxn)(void);
403 
407 typedef void (*Power_PolicyFxn)(void);
408 
430 typedef int_fast16_t (*Power_NotifyFxn)(uint_fast16_t eventType,
431  uintptr_t eventArg, uintptr_t clientArg);
432 
443 typedef struct {
445  uint_fast16_t eventTypes;
447  uintptr_t clientArg;
449 
466 bool Power_disablePolicy(void);
467 
489 void Power_enablePolicy(void);
490 
514 uint_fast32_t Power_getConstraintMask(void);
515 
536 int_fast16_t Power_getDependencyCount(uint_fast16_t resourceId);
537 
550 uint_fast16_t Power_getPerformanceLevel(void);
551 
575 uint_fast32_t Power_getTransitionLatency(uint_fast16_t sleepState,
576  uint_fast16_t type);
577 
596 uint_fast16_t Power_getTransitionState(void);
597 
608 void Power_idleFunc(void);
609 
622 int_fast16_t Power_init(void);
623 
688 int_fast16_t Power_registerNotify(Power_NotifyObj *pNotifyObj,
689  uint_fast16_t eventTypes,
690  Power_NotifyFxn notifyFxn,
691  uintptr_t clientArg);
692 
731 int_fast16_t Power_releaseConstraint(uint_fast16_t constraintId);
732 
757 int_fast16_t Power_releaseDependency(uint_fast16_t resourceId);
758 
786 int_fast16_t Power_setConstraint(uint_fast16_t constraintId);
787 
823 int_fast16_t Power_setDependency(uint_fast16_t resourceId);
824 
866 int_fast16_t Power_setPerformanceLevel(uint_fast16_t level);
867 
876 void Power_setPolicy(Power_PolicyFxn policy);
877 
923 int_fast16_t Power_shutdown(uint_fast16_t shutdownState,
924  uint_fast32_t shutdownTime);
925 
949 int_fast16_t Power_sleep(uint_fast16_t sleepState);
950 
964 void Power_unregisterNotify(Power_NotifyObj *pNotifyObj);
965 
966 #ifdef __cplusplus
967 }
968 #endif
969 
970 #endif /* ti_drivers_Power__include */
uint_fast32_t Power_getTransitionLatency(uint_fast16_t sleepState, uint_fast16_t type)
Get the hardware transition latency for a sleep state.
int_fast16_t Power_getDependencyCount(uint_fast16_t resourceId)
Get the current dependency count for a resource.
int_fast16_t Power_sleep(uint_fast16_t sleepState)
Transition the device into a sleep state.
int_fast16_t Power_init(void)
Power initialization function.
Power_NotifyFxn notifyFxn
Definition: Power.h:446
int_fast16_t(* Power_NotifyFxn)(uint_fast16_t eventType, uintptr_t eventArg, uintptr_t clientArg)
Power notify callback function used with the Power_registerNotify()
Definition: Power.h:430
int_fast16_t Power_setPerformanceLevel(uint_fast16_t level)
Set the MCU performance level.
int_fast16_t Power_setConstraint(uint_fast16_t constraintId)
Declare an operational constraint.
int_fast16_t Power_registerNotify(Power_NotifyObj *pNotifyObj, uint_fast16_t eventTypes, Power_NotifyFxn notifyFxn, uintptr_t clientArg)
Register a function to be called upon a specific power event.
void(* Power_PolicyFxn)(void)
Power policy function pointer.
Definition: Power.h:407
bool Power_disablePolicy(void)
Disable the configured power policy from running when the CPU is idle.
uintptr_t clientArg
Definition: Power.h:447
int_fast16_t Power_shutdown(uint_fast16_t shutdownState, uint_fast32_t shutdownTime)
Put the device into a shutdown state.
uint_fast16_t eventTypes
Definition: Power.h:445
uint_fast16_t Power_getPerformanceLevel(void)
Get the current performance level.
void Power_setPolicy(Power_PolicyFxn policy)
Set a new Power policy.
Power notify object structure.
Definition: Power.h:443
int_fast16_t Power_releaseDependency(uint_fast16_t resourceId)
Release a previously declared dependency.
void Power_unregisterNotify(Power_NotifyObj *pNotifyObj)
Unregister previously registered notifications.
uint_fast32_t Power_getConstraintMask(void)
Get the constraints that have been declared with Power.
uint_fast16_t Power_getTransitionState(void)
Get the current transition state of the Power Manager.
List_Elem link
Definition: Power.h:444
int_fast16_t Power_releaseConstraint(uint_fast16_t constraintId)
Release a previously declared constraint.
int_fast16_t Power_setDependency(uint_fast16_t resourceId)
Declare a dependency upon a resource.
void Power_enablePolicy(void)
Enable the configured power policy to run when the CPU is idle.
void Power_idleFunc(void)
Power function to be added to the application idle loop.
Definition: List.h:126
Linked List interface for use in drivers.
© Copyright 1995-2020, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale