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  *  IpcPower Functions:
  83  * =============================================================================
  84  */
  85
  86 /*!
  87  *  @brief      Initialize the IpcPower module
  88  *
  89  *  @sa         IpcPower_exit
  90  */
  91 Void IpcPower_init();
  92
  93 /*!
  94  *  @brief      Finalize the IpcPower module
  95  *
  96  *  @sa         IpcPower_init
  97  */
  98 Void IpcPower_exit();
  99
 100 /*!
 101  *  @brief      Initiate the suspend procedure
 102  */
 103 Void IpcPower_suspend();
 104
 105 /*!
 106  *  @brief      Disable the deep sleep mode in the core
 107  *
 108  *  @sa         IpcPower_wakeUnlock
 109  */
 110 Void IpcPower_wakeLock();
 111
 112 /*!
 113  *  @brief      Enable the core to go to deep sleep mode
 114  *
 115  *  @sa         IpcPower_wakeLock
 116  */
 117 Void IpcPower_wakeUnlock();
 118
 119 /*!
 120  *  @brief      Disable the core to go to suspend / hibernate
 121  *
 122  *  @sa         IpcPower_hibernateUnlock, IpcPower_canHibernate
 123  */
 124 UInt IpcPower_hibernateLock();
 125
 126 /*!
 127  *  @brief      Enable the core to go to suspend / hibernate
 128  *
 129  *  @sa         IpcPower_hibernateLock, IpcPower_canHibernate
 130  */
 131 UInt IpcPower_hibernateUnlock();
 132
 133 /*!
 134  *  @brief      Return TRUE if hibernation is allowed
 135  *
 136  *  @sa         IpcPower_hibernateLock, IpcPower_hibernateUnlock
 137  */
 138 Bool IpcPower_canHibernate();
 139
 140 /*!
 141  *  @brief      Register callback function for a Power event
 142  *
 143  *  @param[in]  event  Power Management callback event type.
 144  *  @param[in]  fxn    Function being registered.
 145  *  @param[in]  data   Data to be passed as argument to function.
 146  *
 147  *  @Returns    Returns SUCCESS or FAIL
 148  *
 149  *  @sa         IpcPower_registerCallback
 150  */
 151 Int IpcPower_registerCallback(Int event, IpcPower_CallbackFuncPtr fxn,
 152                               Ptr data);
 153
 154 /*!
 155  *  @brief      Unregister callback function for a Power event
 156  *
 157  *  @param[in]  event  Power Management callback event type.
 158  *  @param[in]  fxn    Function being unregistered.
 159  *
 160  *  @Returns    Returns SUCCESS or FAIL
 161  *
 162  *  @sa         IpcPower_unregisterCallback
 163  */
 164 Int IpcPower_unregisterCallback(Int event, IpcPower_CallbackFuncPtr fxn);
 165
 166 #if defined (__cplusplus)
 167 }
 168 #endif /* defined (__cplusplus) */
 169
 170 #endif /* ti_ipc_IpcPower__include */