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  */
  36
  37 #ifndef ti_pm_IpcPower__include
  38 #define ti_pm_IpcPower__include
  39
  40 #if defined (__cplusplus)
  41 extern "C" {
  42 #endif
  43
  44
  45 /* =============================================================================
  46  *  Structures & Definitions
  47  * =============================================================================
  48  */
  49
  50 /*!
  51  *  @def    IpcPower_S_SUCCESS
  52  *  @brief  Operation is successful.
  53  */
  54 #define IpcPower_S_SUCCESS               (0)
  55
  56 /*!
  57  *  @def    IpcPower_E_FAIL
  58  *  @brief  Operation is not successful.
  59  */
  60 #define IpcPower_E_FAIL                  (-1)
  61
  62 /*!
  63  *  @def    IpcPower_E_MEMORY
  64  *  @brief  Operation resulted in memory failure.
  65  */
  66 #define IpcPower_E_MEMORY                (-2)
  67
  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;
  75
  76 /*!
  77  *  @brief  Power Event Callback function type definition
  78  */
  79 typedef Void (*IpcPower_CallbackFuncPtr)(Int event, Ptr data);
  80
  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;
  90
  91 /* =============================================================================
  92  *  IpcPower Functions:
  93  * =============================================================================
  94  */
  95
  96 /*!
  97  *  @brief      Initialize the IpcPower module
  98  *
  99  *  @sa         IpcPower_exit
 100  */
 101 Void IpcPower_init();
 102
 103 /*!
 104  *  @brief      Finalize the IpcPower module
 105  *
 106  *  @sa         IpcPower_init
 107  */
 108 Void IpcPower_exit();
 109
 110 /*!
 111  *  @brief      Initiate the suspend procedure
 112  */
 113 Void IpcPower_suspend();
 114
 115 /*!
 116  *  @brief      Disable the deep sleep mode in the core
 117  *
 118  *  @sa         IpcPower_wakeUnlock
 119  */
 120 Void IpcPower_wakeLock();
 121
 122 /*!
 123  *  @brief      Enable the core to go to deep sleep mode
 124  *
 125  *  @sa         IpcPower_wakeLock
 126  */
 127 Void IpcPower_wakeUnlock();
 128
 129 /*!
 130  *  @brief      Disable the core to go to suspend / hibernate
 131  *
 132  *  @sa         IpcPower_hibernateUnlock, IpcPower_canHibernate
 133  */
 134 UInt IpcPower_hibernateLock();
 135
 136 /*!
 137  *  @brief      Enable the core to go to suspend / hibernate
 138  *
 139  *  @sa         IpcPower_hibernateLock, IpcPower_canHibernate
 140  */
 141 UInt IpcPower_hibernateUnlock();
 142
 143 /*!
 144  *  @brief      Return TRUE if hibernation is allowed
 145  *
 146  *  @sa         IpcPower_hibernateLock, IpcPower_hibernateUnlock
 147  */
 148 Bool IpcPower_canHibernate();
 149
 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);
 163
 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);
 175
 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);
 184
 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);
 198
 199 #if defined (__cplusplus)
 200 }
 201 #endif /* defined (__cplusplus) */
 202
 203 #endif /* ti_ipc_IpcPower__include */