le_ulpm_interface.h

    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_ulpm Ultra Low Power Mode
   14  *
   15  * @ref le_ulpm_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * This API is used to set the boot sources and switch the device to ultra-low power state. Ultra-
   20  * low power mode is achieved by shutting down major components (e.g. app processor, modem, etc.)
   21  * while keeping an ultra-low power component alive. This ultra-low power component is used to
   22  * monitor boot sources that are set before switching to ultra-low power mode.
   23  *
   24  * @section API_Usage_usage Typical Usage
   25  *
   26  * Typically, this API is used like this:
   27  *
   28  *   - Boot sources are set by calling le_ulpm_BootOnGpio()/le_ulpm_BootOnTimer(). If multiple
   29  *      boot sources are configured, the module will boot if any of the boot sources are triggered.
   30  *
   31  *   - After configuring boot source, le_ulpm_ShutDown() can be called to initiate shutdown
   32  *      (i.e. shutt down all major components like the app processor, modem, etc.).
   33  *
   34  * @section ulpm_example Sample Code
   35  *
   36  * This C code sample calls low power manager API to switch low power mode:
   37  *
   38  *  @code
   39  *
   40  *  void SwitchToLowPowerMode
   41  *  (
   42  *      void
   43  *  )
   44  *  {
   45  *      char version[LE_ULPM_MAX_VERS_LEN+1];
   46  *
   47  *      // Get ultra low power manager firmware version
   48  *      LE_FATAL_IF(le_ulpm_GetFirmwareVersion(version, sizeof(version)) != LE_OK,
   49  *          "Failed to get ultra low power firmware version");
   50  *
   51  *       LE_INFO("Ultra Low Power Manager Firmware version: %s", version);
   52  *
   53  *      // Boot after 1000 second of shutdown.
   54  *      LE_ERROR_IF(le_ulpm_BootOnTimer(1000) != LE_OK, "Can't set timer as boot source");
   55  *
   56  *      // Boot if GPIO36 voltage level is high.
   57  *      LE_ERROR_IF(le_ulpm_BootOnGpio(36, LE_ULPM_GPIO_HIGH) != LE_OK, "Can't set gpio36 as boot source");
   58  *
   59  *      // Boot if GPIO38 voltage level is low.
   60  *      LE_ERROR_IF(le_ulpm_BootOnGpio(38, LE_ULPM_GPIO_LOW) != LE_OK, "Can't set gpio38 as boot source");
   61  *
   62  *      // Initiate shutdown.
   63  *      LE_ERROR_IF(le_ulpm_ShutDown() != LE_OK, "Can't initiate shutdown");
   64  *  }
   65  *
   66  *  @endcode
   67  *
   68  * <HR>
   69  *
   70  * Copyright (C) Sierra Wireless Inc.
   71  */
   72 /**
   73  * @file le_ulpm_interface.h
   74  *
   75  * Legato @ref c_ulpm include file.
   76  *
   77  * Copyright (C) Sierra Wireless Inc.
   78  */
   79 
   80 #ifndef LE_ULPM_INTERFACE_H_INCLUDE_GUARD
   81 #define LE_ULPM_INTERFACE_H_INCLUDE_GUARD
   82 
   83 
   84 #include "legato.h"
   85 
   86 // Internal includes for this interface
   87 #include "le_ulpm_common.h"
   88 //--------------------------------------------------------------------------------------------------
   89 /**
   90  * Type for handler called when a server disconnects.
   91  */
   92 //--------------------------------------------------------------------------------------------------
   93 typedef void (*le_ulpm_DisconnectHandler_t)(void *);
   94 
   95 //--------------------------------------------------------------------------------------------------
   96 /**
   97  *
   98  * Connect the current client thread to the service providing this API. Block until the service is
   99  * available.
  100  *
  101  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  102  * called before any other functions in this API.  Normally, ConnectService is automatically called
  103  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  104  *
  105  * This function is created automatically.
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 void le_ulpm_ConnectService
  109 (
  110     void
  111 );
  112 
  113 //--------------------------------------------------------------------------------------------------
  114 /**
  115  *
  116  * Try to connect the current client thread to the service providing this API. Return with an error
  117  * if the service is not available.
  118  *
  119  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  120  * called before any other functions in this API.  Normally, ConnectService is automatically called
  121  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  122  *
  123  * This function is created automatically.
  124  *
  125  * @return
  126  *  - LE_OK if the client connected successfully to the service.
  127  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  128  *    bound.
  129  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  130  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  131  */
  132 //--------------------------------------------------------------------------------------------------
  133 le_result_t le_ulpm_TryConnectService
  134 (
  135     void
  136 );
  137 
  138 //--------------------------------------------------------------------------------------------------
  139 /**
  140  * Set handler called when server disconnection is detected.
  141  *
  142  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  143  * to continue without exiting, it should call longjmp() from inside the handler.
  144  */
  145 //--------------------------------------------------------------------------------------------------
  146 LE_FULL_API void le_ulpm_SetServerDisconnectHandler
  147 (
  148     le_ulpm_DisconnectHandler_t disconnectHandler,
  149     void *contextPtr
  150 );
  151 
  152 //--------------------------------------------------------------------------------------------------
  153 /**
  154  *
  155  * Disconnect the current client thread from the service providing this API.
  156  *
  157  * Normally, this function doesn't need to be called. After this function is called, there's no
  158  * longer a connection to the service, and the functions in this API can't be used. For details, see
  159  * @ref apiFilesC_client.
  160  *
  161  * This function is created automatically.
  162  */
  163 //--------------------------------------------------------------------------------------------------
  164 void le_ulpm_DisconnectService
  165 (
  166     void
  167 );
  168 
  169 
  170 //--------------------------------------------------------------------------------------------------
  171 /**
  172  * State of gpio pin. This state will be used to exit from low power state.
  173  */
  174 //--------------------------------------------------------------------------------------------------
  175 
  176 
  177 //--------------------------------------------------------------------------------------------------
  178 /**
  179  * Configure the system to boot based on a state change of a given GPIO.
  180  *
  181  * @return
  182  *      - LE_OK if specified gpio is configured as boot source.
  183  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to configure the GPIO as a
  184  *        boot source.
  185  *      - LE_UNSUPPORTED if the device lacks the ability to boot based on the given GPIO.
  186  *      - LE_BAD_PARAMETER if the state parameter was rejected.
  187  *      - LE_FAULT if there is a non-specific failure.
  188  */
  189 //--------------------------------------------------------------------------------------------------
  190 le_result_t le_ulpm_BootOnGpio
  191 (
  192     uint32_t gpioNum,
  193         ///< [IN] Gpio number to boot.
  194     le_ulpm_GpioState_t state
  195         ///< [IN] State which should cause boot.
  196 );
  197 
  198 //--------------------------------------------------------------------------------------------------
  199 /**
  200  * Boot after expiration of timer interval.
  201  *
  202  * @return
  203  *      - LE_OK if timer is configured as boot source.
  204  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to configure the timer as a
  205  *        boot source.
  206  *      - LE_UNSUPPORTED if the device lacks the ability to boot based on a timer.
  207  *      - LE_BAD_PARAMETER if the state parameter was rejected.
  208  *      - LE_FAULT if there is a non-specific failure.
  209  */
  210 //--------------------------------------------------------------------------------------------------
  211 le_result_t le_ulpm_BootOnTimer
  212 (
  213     uint32_t expiryVal
  214         ///< [IN] Expiration time(in second) to boot. This is relative time from
  215         ///< modem/app processor shutdown.
  216 );
  217 
  218 //--------------------------------------------------------------------------------------------------
  219 /**
  220  * Configure and enable an ADC as a boot source.
  221  *
  222  * It is possible to specify a single range of operation or two ranges of operation with a
  223  * non-operational range in between.  When bootAboveAdcReading is less than bootBelowAdcReading,
  224  * then a single range bootAboveReading to bootBelowReading is the configured operational range.
  225  * However if bootAboveAdcReading is greater than bootBelowAdcReading, then there are two
  226  * operational ranges.  The first is any reading less than bootBelowAdcReading and the second is any
  227  * reading greater than bootAboveAdcReading.
  228  *
  229  * @return
  230  *      - LE_OK on success
  231  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to configure the adc as a
  232  *        boot source.
  233  *      - LE_OVERFLOW if the provided bootAboveAdcReading or bootBelowAdcReading are too large to
  234  *        convert to fit in the internal string buffer.
  235  *      - LE_BAD_PARAMETER if the pollIntervalInMs, bootAboveAdcReading or bootBelowAdcReading
  236  *        parameter were rejected.
  237  *      - LE_UNSUPPORTED if the device does not support using the given adc as a boot source.
  238  *      - LE_FAULT if there is a non-specific failure.
  239  */
  240 //--------------------------------------------------------------------------------------------------
  241 le_result_t le_ulpm_BootOnAdc
  242 (
  243     uint32_t adcNum,
  244         ///< [IN] Number of the ADC to configure
  245     uint32_t pollIntervalInMs,
  246         ///< [IN] How frequently to poll the ADC while sleeping
  247     double bootAboveAdcReading,
  248         ///< [IN] Reading above which the system should boot
  249     double bootBelowAdcReading
  250         ///< [IN] Reading below which the system should boot
  251 );
  252 
  253 //--------------------------------------------------------------------------------------------------
  254 /**
  255  * Get the ultra low power manager firmware version.
  256  *
  257  * @return
  258  *      - LE_OK on success
  259  *      - LE_OVERFLOW if version string to big to fit in provided buffer
  260  *      - LE_FAULT for any other errors
  261  */
  262 //--------------------------------------------------------------------------------------------------
  263 le_result_t le_ulpm_GetFirmwareVersion
  264 (
  265     char* version,
  266         ///< [OUT] Firmware version string
  267     size_t versionSize
  268         ///< [IN]
  269 );
  270 
  271 //--------------------------------------------------------------------------------------------------
  272 /**
  273  * Initiate shutting down of app processor/modem etc.
  274  *
  275  * @return
  276  *      - LE_OK if entry to ultra low power mode initiates properly.
  277  *      - LE_NOT_POSSIBLE if shutting is not possible now. Try again.
  278  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to perform a shutdown.
  279  *      - LE_UNSUPPORTED if the device lacks the ability to shutdown via ULPM.
  280  *      - LE_FAULT if there is a non-specific failure.
  281  */
  282 //--------------------------------------------------------------------------------------------------
  283 le_result_t le_ulpm_ShutDown
  284 (
  285     void
  286 );
  287 
  288 #endif // LE_ULPM_INTERFACE_H_INCLUDE_GUARD
le_ulpm_GetFirmwareVersion
le_result_t le_ulpm_GetFirmwareVersion(char *version, size_t versionSize)
le_ulpm_ShutDown
le_result_t le_ulpm_ShutDown(void)
le_result_t
le_result_t
Definition: le_basics.h:35
le_ulpm_SetServerDisconnectHandler
LE_FULL_API void le_ulpm_SetServerDisconnectHandler(le_ulpm_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_ulpm_DisconnectService
void le_ulpm_DisconnectService(void)
le_ulpm_BootOnAdc
le_result_t le_ulpm_BootOnAdc(uint32_t adcNum, uint32_t pollIntervalInMs, double bootAboveAdcReading, double bootBelowAdcReading)
le_ulpm_ConnectService
void le_ulpm_ConnectService(void)
le_ulpm_DisconnectHandler_t
void(* le_ulpm_DisconnectHandler_t)(void *)
Definition: le_ulpm_interface.h:93
le_ulpm_BootOnGpio
le_result_t le_ulpm_BootOnGpio(uint32_t gpioNum, le_ulpm_GpioState_t state)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_ulpm_BootOnTimer
le_result_t le_ulpm_BootOnTimer(uint32_t expiryVal)
le_ulpm_TryConnectService
le_result_t le_ulpm_TryConnectService(void)