46b769d98de86df3999ab4592a7f595a552cd80a
[ipc/ipcdev.git] / packages / ti / pm / IpcPower.h
1 /*
2  * Copyright (c) 2011-2013, 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       IpcPower.h
34  *  ============================================================================
35  */
37 #ifndef ti_pm_IpcPower__include
38 #define ti_pm_IpcPower__include
40 #if defined (__cplusplus)
41 extern "C" {
42 #endif
45 /* =============================================================================
46  *  Structures & Definitions
47  * =============================================================================
48  */
50 /*!
51  *  @def    IpcPower_S_SUCCESS
52  *  @brief  Operation is successful.
53  */
54 #define IpcPower_S_SUCCESS               (0)
56 /*!
57  *  @def    IpcPower_E_FAIL
58  *  @brief  Operation is not successful.
59  */
60 #define IpcPower_E_FAIL                  (-1)
62 /*!
63  *  @def    IpcPower_E_MEMORY
64  *  @brief  Operation resulted in memory failure.
65  */
66 #define IpcPower_E_MEMORY                (-2)
68 /*!
69  *  @brief  Event types for power management callbacks
70  */
71 typedef enum IpcPower_Event {
72     IpcPower_Event_SUSPEND  = 0, /*! Callback event for Power suspend */
73     IpcPower_Event_RESUME   = 1  /*! Callback event for Power resume  */
74 } IpcPower_Event;
76 /*!
77  *  @brief  Power Event Callback function type definition
78  */
79 typedef Void (*IpcPower_CallbackFuncPtr)(Int event, Ptr data);
81 /*!
82  *  @brief  Type representing OMAP's WUGEN_MEVT[0|1] registers
83  *
84  *  For APIs IpcPower_getWugenEvtMask() and IpcPower_setWugenEvtMask()
85  */
86 typedef struct IpcPower_WugenEvtMask {
87     UInt32 mevt0;
88     UInt32 mevt1;
89 } IpcPower_WugenEvtMask;
91 /* =============================================================================
92  *  IpcPower Functions:
93  * =============================================================================
94  */
96 /*!
97  *  @brief      Initialize the IpcPower module
98  *
99  *  @sa         IpcPower_exit
100  */
101 Void IpcPower_init();
103 /*!
104  *  @brief      Finalize the IpcPower module
105  *
106  *  @sa         IpcPower_init
107  */
108 Void IpcPower_exit();
110 /*!
111  *  @brief      Initiate the suspend procedure
112  */
113 Void IpcPower_suspend();
115 /*!
116  *  @brief      Disable the deep sleep mode in the core
117  *
118  *  @sa         IpcPower_wakeUnlock
119  */
120 Void IpcPower_wakeLock();
122 /*!
123  *  @brief      Enable the core to go to deep sleep mode
124  *
125  *  @sa         IpcPower_wakeLock
126  */
127 Void IpcPower_wakeUnlock();
129 /*!
130  *  @brief      Disable the core to go to suspend / hibernate
131  *
132  *  @sa         IpcPower_hibernateUnlock, IpcPower_canHibernate
133  */
134 UInt IpcPower_hibernateLock();
136 /*!
137  *  @brief      Enable the core to go to suspend / hibernate
138  *
139  *  @sa         IpcPower_hibernateLock, IpcPower_canHibernate
140  */
141 UInt IpcPower_hibernateUnlock();
143 /*!
144  *  @brief      Return TRUE if hibernation is allowed
145  *
146  *  @sa         IpcPower_hibernateLock, IpcPower_hibernateUnlock
147  */
148 Bool IpcPower_canHibernate();
150 /*!
151  *  @brief      Register callback function for a Power event
152  *
153  *  @param[in]  event  Power Management callback event type.
154  *  @param[in]  fxn    Function being registered.
155  *  @param[in]  data   Data to be passed as argument to function.
156  *
157  *  @Returns    Returns SUCCESS or FAIL
158  *
159  *  @sa         IpcPower_registerCallback
160  */
161 Int IpcPower_registerCallback(Int event, IpcPower_CallbackFuncPtr fxn,
162                               Ptr data);
164 /*!
165  *  @brief      Unregister callback function for a Power event
166  *
167  *  @param[in]  event  Power Management callback event type.
168  *  @param[in]  fxn    Function being unregistered.
169  *
170  *  @Returns    Returns SUCCESS or FAIL
171  *
172  *  @sa         IpcPower_unregisterCallback
173  */
174 Int IpcPower_unregisterCallback(Int event, IpcPower_CallbackFuncPtr fxn);
176 /*!
177  *  @brief      Retrieve current WUGEN mask used for suspend
178  *
179  *  @param[in]  mask  Pointer to structure for holding WUGEN event mask
180  *
181  *  @sa         IpcPower_suspend, IpcPower_setWugenEvtMask
182  */
183 Void IpcPower_getWugenEvtMask(IpcPower_WugenEvtMask *mask);
185 /*!
186  *  @brief      Set WUGEN mask used for suspend
187  *
188  *  The values in the passed structure are copied into the internal
189  *  WUGEN event mask. To achieve an ORing of certain bits in the mask,
190  *  first retrieve the current mask with IpcPower_getWugenEvtMask() and
191  *  then OR in the bits you want to enable.
192  *
193  *  @param[in]  mask  Pointer to WUGEN event mask structure
194  *
195  *  @sa         IpcPower_suspend, IpcPower_getWugenEvtMask
196  */
197 Void IpcPower_setWugenEvtMask(IpcPower_WugenEvtMask *mask);
199 #if defined (__cplusplus)
201 #endif /* defined (__cplusplus) */
203 #endif /* ti_ipc_IpcPower__include */