Power.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2019, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *  @file       Power.h
 *  @brief      Power Manager
 *
 *  @anchor ti_drivers_Power_Overview
 *  # Overview
 *
 *  The Power Manager facilitates the transition of the MCU from active states
 *  to sleep states and vice versa. It provides other drivers the
 *  ability to set and release dependencies on hardware resources, and keeps
 *  reference counts on each resource to know when to enable or disable the
 *  resource. It provides drivers the ability to register callback functions
 *  to be invoked upon specific power events. In addition, drivers and
 *  applications can set or release constraints to prevent the MCU from
 *  transitioning into specific active or sleep states. Refer to the device
 *  specific power driver header file device specific information.
 *
 *  <hr>
 *  @anchor ti_drivers_Power_Usage
 *  # Usage
 *
 *  This documentation provides a basic @ref ti_drivers_Power_Synopsis
 *  "usage summary" and a set of @ref ti_drivers_Power_Examples "examples"
 *  in the form of commented code fragments. Detailed descriptions of the
 *  APIs are provided in subsequent sections.
 *  @anchor ti_drivers_Power_Synopsis
 *  ## Synopsis
 *  @anchor ti_drivers_Power_Synopsis_Code
 *
 *  @note  <b> The following example demonstrates usage of some of the Power
 *  driver APIs.This example is intended for reference only and is not intended
 *  for application use. You should refer to the device specific Power driver
 *  header for valid API usage and arguments. </b>
 *
 *
 *  @code
 *  // Import Power Driver definitions
 *  #include <ti/drivers/Power.h>
 *
 *  // One-time initialization of Power manager
 *  Power_init();
 *
 *  // Set power dependency on a resource
 *  status = Power_setDependency(resourceId);
 *  if (status != Power_SOK) {
 *      // Error occurred
 *  }
 *
 *  // Set a power constraint
 *  status = Power_setConstraint(constraintId);
 *  if (status != Power_SOK) {
 *      // Error occurred
 *  }
 *
 *  // Other application code
 *
 *  // Release a previously set power constraint
 *  status = Power_releaseConstraint(constraintId);
 *  if (status != Power_SOK) {
 *      // Error occurred
 *  }
 *
 *  status = Power_releaseDependency(resourceId);
 *  if (status != Power_SOK) {
 *      // Error occurred
 *  }
 *  @endcode
 *
 *
 *  <hr>
 *  @anchor ti_drivers_Power_Examples
 *  # Examples
 *
 *  @note
 *  <b>The following examples are intended for reference only and are not
 *  intended for application use. You should refer to the device specific
 *  Power driver header file for more usage information.</b>
 *
 *  @li @ref ti_drivers_Power_Examples_enable "Enabling power policy"
 *  @li @ref ti_drivers_Power_Examples_disable "Disabling power policy"
 *  @li @ref ti_drivers_Power_Examples_constraint "Using power constraints"
 *  @li @ref ti_drivers_Power_Examples_dependency "Using power dependency"
 *  @li @ref ti_drivers_Power_Examples_notify "Using power notify"
 *  @li @ref ti_drivers_Power_Examples_transistion "Power transitions"
 *
 *
 *  @anchor ti_drivers_Power_Examples_enable
 *  ## Enabling Power Policy
 *
 *  @code
 *  // Import Power Driver definitions
 *  #include <ti/drivers/Power.h>
 *
 *  // One-time initialization of Power manager
 *  Power_init();
 *
 *  // Enable power policy
 *  Power_enablePolicy();
 *  @endcode
 *
 *
 *  @anchor ti_drivers_Power_Examples_disable
 *  ## Disabling Power Policy
 *
 *  @code
 *  // Import Power Driver definitions
 *  #include <ti/drivers/Power.h>
 *
 *  bool flag;
 *
 *  // One-time initialization of Power manager
 *  Power_init();
 *
 *  // Disable power policy
 *  flag = Power_disablePolicy();
 *  if (flag == false) {
 *      // Power policy was already disabled
 *  }
 *  @endcode
 *
 *
 *  @anchor ti_drivers_Power_Examples_constraint
 *  ## Using Power Constraints
 *
 *  @code
 *  // Import Power Driver definitions
 *  #include <ti/drivers/Power.h>
 *
 *  uint32_t mask;
 *  int16_t status;
 *
 *  // One-time initialization of Power manager
 *  Power_init();
 *
 *  // Set a power constraint
 *  status = Power_setConstraint(constraintId);
 *  if (status != Power_SOK) {
 *      // Error occurred setting constraint
 *  }
 *
 *  // Read mask of currently set power constraints
 *  mask = Power_getConstraintMask();
 *
 *  // Release previously set constraint
 *  status = Power_releaseConstraint(constraintId);
 *  if (status != Power_SOK) {
 *      // Error occurred releasing constraint
 *  }
 *  @endcode
 *
 *
 *  @anchor ti_drivers_Power_Examples_dependency
 *  ## Using Power Dependency
 *
 *  @code
 *  // Import Power Driver definitions
 *  #include <ti/drivers/Power.h>
 *
 *  int16_t count;
 *  int16_t status;
 *
 *  // One-time initialization of Power manager
 *  Power_init();
 *
 *  // Set a power dependency
 *  status = Power_setDependency(resourceId);
 *  if (status != Power_SOK) {
 *      // Error occurred setting dependency
 *  }
 *
 *  // Get the dependency count of the resource
 *  count = Power_getDependencyCount(resourceId);
 *  if (count == Power_EINVALIDINPUT) {
 *      // Invalid resourceId used
 *  }
 *
 *  if (count > 0) {
 *      // At least 1 dependency exists for the resource.
 *      // Regardless, we may safely release the dependency when we
 *      // no longer need the resource.
 *  }
 *
 *  // Release a power dependency
 *  status = Power_releaseDependency(resourceId);
 *  if (status != Power_SOK) {
 *      // Error occurred releasing dependency
 *  }
 *  @endcode
 *
 *
 *  @anchor ti_drivers_Power_Examples_notify
 *  ## Using Power Notify
 *
 *  The application must define a #Power_NotifyFxn function and
 *  allocate memory for the #Power_NotifyObj object.
 *
 *  @code
 *  // Import Power Driver definitions
 *  #include <ti/drivers/Power.h>
 *
 *  // Application Power_NotifyObj object
 *  Power_NotifyObj powerNotifyObj;
 *
 *  // Application Power_NotifyFxn function prototype
 *  static int postNotifyFxn(unsigned int eventType, uintptr_t eventArg,
 *                           uintptr_t clientArg);
 * @endcode
 *
 *  The application must register for the event. Here, we use pseudo event
 *  names. You should refer to the device specific power driver header file
 *  for eventTypes. Inside the infinite loop, we wait for a semaphore to be
 *  post from our notification callback.
 *
 * @code
 *  // Application thread
 *  void thread(void)
 *  {
 *      int16_t status;
 *      unsigned int eventTypes = LOW_POWER_EXIT | LOW_POWER_ENTER;
 *      uintptr_t clientArg = semaphoreHandle;
 *
 *      status = Power_registerNotify(&powerNotifyObj, eventTypes,
 *                                    postNotifyFxn, clientArg);
 *
 *      while (1)
 *      {
 *          sem_wait(semaphoreHandle);
 *          // Do something
 *
 *          // Unregister for the notification. After this call,
 *          // our postNotifyFxn() will never be called again unless
 *          // we use Power_registerNotify() again.
 *          Power_unregisterNotify(&powerNotifyObj);
 *
 *          break;
 *      }
 *  }
 *  @endcode
 *
 *  The application may implement the power notify function to fit their
 *  needs. The #Power_NotifyFxn should always return #Power_NOTIFYDONE or
 *  #Power_NOTIFYERROR.
 *
 *  @code
 *  // Application Power_NotifyFxn function implementation
 *  static int postNotifyFxn(unsigned int eventType, uintptr_t eventArg,
 *                           uintptr_t clientArg)
 *  {
 *      sem_t semaphoreHandle = (sem_t) clientArg;
 *
 *      if (eventType == LOW_POWER_EXIT) {
 *          sem_post(semaphoreHandle);
 *          return (Power_NOTIFYDONE);
 *      }
 *
 *      if (eventType == LOW_POWER_ENTER) {
 *          // Store something in RAM
 *          return (Power_NOTIFYDONE);
 *      }
 *
 *      // We received an unexpected event type
 *      return (Power_NOTIFYERROR);
 *  }
 *  @endcode
 *
 *
 *  @anchor ti_drivers_Power_Examples_transistion
 *  ## Power transitions
 *
 *  @code
 *  // Import Power Driver definitions
 *  #include <ti/drivers/Power.h>
 *
 *  uint32_t totalLatency, resumeLatency;
 *  int16_t status;
 *
 *  // One-time initialization of Power manager
 *  Power_init();
 *
 *  // Get the current power transition state
 *  status = Power_getTransitionState();
 *
 *  switch (status)
 *  {
 *      case Power_ACTIVE:
 *        // No transitions in progress
 *        break;
 *      case Power_ENTERING_SLEEP:
 *        // Transition to sleep in progress
 *        break;
 *      case Power_EXITING_SLEEP:
 *        // Transition from sleep in progress
 *        break;
 *      case Power_CHANGING_PERF_LEVEL:
 *        // Performance level change in progress
 *        break;
 *  }
 *
 *  // Get the Power_TOTAL and Power_RESUME transition latency for a
 *  // device specific sleepState. Latency is in microseconds.
 *  totalLatency = Power_getTransitionLatency(sleepState, Power_TOTAL);
 *  resumeLatency = Power_getTransitionLatency(sleepState, Power_RESUME);
 *  @endcode
 *
 *
 *  <hr>
 *  @anchor ti_drivers_Power_Configuration
 *  # Configuration
 *
 *  @note The Power Manager APIs and configuration parameters are described here.
 *  For a detailed description of terms and concepts, and usage by different
 *  types of software components (peripheral drivers, power policies,
 *  and applications) please see the
 *  <a href='../../Power_Management.pdf'>SimpleLink SDK Power Management User's Guide</a>.
 *  <hr>
 ******************************************************************************
 */

#ifndef ti_drivers_Power__include
#define ti_drivers_Power__include

/* @cond */
#include <stdbool.h>
#include <stdint.h>
/* @endcond */

#include <ti/drivers/utils/List.h>

#ifdef __cplusplus
extern "C" {
#endif

#define Power_TOTAL               (1U)   
#define Power_RESUME              (2U)   
#define Power_NOTIFYDONE          (0)   
#define Power_NOTIFYERROR         (-1)  
#define Power_SOK                 (0)    
#define Power_EFAIL               (-1)   
#define Power_EINVALIDINPUT       (-2)   
#define Power_EINVALIDPOINTER     (-3)   
#define Power_ECHANGE_NOT_ALLOWED (-4)   
#define Power_EBUSY               (-5)   
#define Power_ACTIVE              (1U)   
#define Power_ENTERING_SLEEP      (2U)   
#define Power_EXITING_SLEEP       (3U)   
#define Power_ENTERING_SHUTDOWN   (4U)   
#define Power_CHANGING_PERF_LEVEL (5U)   
typedef void (*Power_PolicyInitFxn)(void);

typedef void (*Power_PolicyFxn)(void);

typedef int_fast16_t (*Power_NotifyFxn)(uint_fast16_t eventType,
     uintptr_t eventArg, uintptr_t clientArg);

typedef struct {
    List_Elem link;             
    uint_fast16_t eventTypes;   
    Power_NotifyFxn notifyFxn;  
    uintptr_t clientArg;        
} Power_NotifyObj;

bool Power_disablePolicy(void);

void Power_enablePolicy(void);

uint_fast32_t Power_getConstraintMask(void);

int_fast16_t Power_getDependencyCount(uint_fast16_t resourceId);

uint_fast16_t Power_getPerformanceLevel(void);

uint_fast32_t Power_getTransitionLatency(uint_fast16_t sleepState,
    uint_fast16_t type);

uint_fast16_t Power_getTransitionState(void);

void Power_idleFunc(void);

int_fast16_t Power_init(void);

int_fast16_t Power_registerNotify(Power_NotifyObj *pNotifyObj,
                                  uint_fast16_t eventTypes,
                                  Power_NotifyFxn notifyFxn,
                                  uintptr_t clientArg);

int_fast16_t Power_releaseConstraint(uint_fast16_t constraintId);

int_fast16_t Power_releaseDependency(uint_fast16_t resourceId);

int_fast16_t Power_setConstraint(uint_fast16_t constraintId);

int_fast16_t Power_setDependency(uint_fast16_t resourceId);

int_fast16_t Power_setPerformanceLevel(uint_fast16_t level);

void Power_setPolicy(Power_PolicyFxn policy);

int_fast16_t Power_shutdown(uint_fast16_t shutdownState,
    uint_fast32_t shutdownTime);

int_fast16_t Power_sleep(uint_fast16_t sleepState);

void Power_unregisterNotify(Power_NotifyObj *pNotifyObj);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_Power__include */