le_ulpm_interface.h

Go to the documentation of this file.
    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_ulpm Ultra Low Power Mode
   12  *
   13  * @ref le_ulpm_interface.h "API Reference"
   14  *
   15  * <HR>
   16  *
   17  * This API is used to set the boot sources and switch the device to ultra-low power state. Ultra-
   18  * low power mode is achieved by shutting down major components (e.g. app processor, modem, etc.)
   19  * while keeping an ultra-low power component alive. This ultra-low power component is used to
   20  * monitor boot (or wakeup) sources that are set before switching to ultra-low power mode.
   21  *
   22  * @section API_Usage_usage Typical Usage
   23  *
   24  * Typically, this API is used like this:
   25  *
   26  *   - Boot sources are set by calling le_ulpm_BootOnGpio()/le_ulpm_BootOnTimer(). If multiple
   27  *      boot sources are configured, the module will boot if any of the boot sources are triggered.
   28  *
   29  *   - After configuring boot source, le_ulpm_ShutDown() can be called to initiate shutdown
   30  *      (i.e. shutt down all major components like the app processor, modem, etc.).
   31  *
   32  * @section ulpm_example Sample Code
   33  *
   34  * This C code sample calls low power manager API to switch low power mode:
   35  *
   36  *  @code
   37  *
   38  *  void SwitchToLowPowerMode
   39  *  (
   40  *      void
   41  *  )
   42  *  {
   43  *      char version[LE_ULPM_MAX_VERS_LEN+1];
   44  *
   45  *      // Get ultra low power manager firmware version
   46  *      LE_FATAL_IF(le_ulpm_GetFirmwareVersion(version, sizeof(version)) != LE_OK,
   47  *          "Failed to get ultra low power firmware version");
   48  *
   49  *       LE_INFO("Ultra Low Power Manager Firmware version: %s", version);
   50  *
   51  *      // Boot after 1000 second of shutdown.
   52  *      LE_ERROR_IF(le_ulpm_BootOnTimer(1000) != LE_OK, "Can't set timer as boot source");
   53  *
   54  *      // Boot if GPIO36 voltage level is high.
   55  *      LE_ERROR_IF(le_ulpm_BootOnGpio(36, LE_ULPM_GPIO_HIGH) != LE_OK, "Can't set gpio36 as boot source");
   56  *
   57  *      // Boot if GPIO38 voltage level is low.
   58  *      LE_ERROR_IF(le_ulpm_BootOnGpio(38, LE_ULPM_GPIO_LOW) != LE_OK, "Can't set gpio38 as boot source");
   59  *
   60  *      // Initiate shutdown.
   61  *      LE_ERROR_IF(le_ulpm_ShutDown() != LE_OK, "Can't initiate shutdown");
   62  *  }
   63  *
   64  *  @endcode
   65  *
   66  * <HR>
   67  *
   68  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   69  */
   70 /**
   71  * @file le_ulpm_interface.h
   72  *
   73  * Legato @ref c_ulpm include file.
   74  *
   75  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   76  */
   77 
   78 #ifndef LE_ULPM_INTERFACE_H_INCLUDE_GUARD
   79 #define LE_ULPM_INTERFACE_H_INCLUDE_GUARD
   80 
   81 
   82 #include "legato.h"
   83 
   84 //--------------------------------------------------------------------------------------------------
   85 /**
   86  *
   87  * Connect the current client thread to the service providing this API. Block until the service is
   88  * available.
   89  *
   90  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   91  * called before any other functions in this API.  Normally, ConnectService is automatically called
   92  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   93  *
   94  * This function is created automatically.
   95  */
   96 //--------------------------------------------------------------------------------------------------
   97 void le_ulpm_ConnectService
   98 (
   99     void
  100 );
  101 
  102 //--------------------------------------------------------------------------------------------------
  103 /**
  104  *
  105  * Try to connect the current client thread to the service providing this API. Return with an error
  106  * if the service is not available.
  107  *
  108  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  109  * called before any other functions in this API.  Normally, ConnectService is automatically called
  110  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  111  *
  112  * This function is created automatically.
  113  *
  114  * @return
  115  *  - LE_OK if the client connected successfully to the service.
  116  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  117  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  118  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  119  */
  120 //--------------------------------------------------------------------------------------------------
  121 le_result_t le_ulpm_TryConnectService
  122 (
  123     void
  124 );
  125 
  126 //--------------------------------------------------------------------------------------------------
  127 /**
  128  *
  129  * Disconnect the current client thread from the service providing this API.
  130  *
  131  * Normally, this function doesn't need to be called. After this function is called, there's no
  132  * longer a connection to the service, and the functions in this API can't be used. For details, see
  133  * @ref apiFilesC_client.
  134  *
  135  * This function is created automatically.
  136  */
  137 //--------------------------------------------------------------------------------------------------
  138 void le_ulpm_DisconnectService
  139 (
  140     void
  141 );
  142 
  143 
  144 //--------------------------------------------------------------------------------------------------
  145 /**
  146  * Maximum version length of mcu firmware.
  147  */
  148 //--------------------------------------------------------------------------------------------------
  149 #define LE_ULPM_MAX_VERS_LEN 8
  150 
  151 
  152 //--------------------------------------------------------------------------------------------------
  153 /**
  154  * State of gpio pin. This state will be used to exit from low power state.
  155  */
  156 //--------------------------------------------------------------------------------------------------
  157 typedef enum
  158 {
  159     LE_ULPM_GPIO_LOW = 0,
  160         ///< Gpio voltage level low.
  161 
  162     LE_ULPM_GPIO_HIGH = 1,
  163         ///< Gpio voltage level high.
  164 
  165     LE_ULPM_GPIO_RISING = 2,
  166         ///< Gpio edge rising.
  167 
  168     LE_ULPM_GPIO_FALLING = 3,
  169         ///< Gpio edge falling.
  170 
  171     LE_ULPM_GPIO_BOTH = 4,
  172         ///< Gpio edge either rising or falling.
  173 
  174     LE_ULPM_GPIO_OFF = 5
  175         ///< Gpio off.
  176 }
  177 le_ulpm_GpioState_t;
  178 
  179 //--------------------------------------------------------------------------------------------------
  180 /**
  181  * Boot on changing of a gpio state. Gpio number is specified as parameter.
  182  *
  183  * @return
  184  *      - LE_OK if specified gpio is configured as boot source.
  185  *      - LE_FAULT if failed to configure.
  186  *
  187  * @note The process exits if invalid gpio number is passed.  Check corresponding device documents
  188  * for valid list of gpio.
  189  */
  190 //--------------------------------------------------------------------------------------------------
  191 le_result_t le_ulpm_BootOnGpio
  192 (
  193     uint32_t gpioNum,
  194         ///< [IN] Gpio number to boot.
  195 
  196     le_ulpm_GpioState_t state
  197         ///< [IN] State which should cause boot.
  198 );
  199 
  200 //--------------------------------------------------------------------------------------------------
  201 /**
  202  * Boot after expiration of timer interval.
  203  *
  204  * @return
  205  *      - LE_OK if specified timer is configured as boot source.
  206  *      - LE_FAULT if failed to configure.
  207  *
  208  */
  209 //--------------------------------------------------------------------------------------------------
  210 le_result_t le_ulpm_BootOnTimer
  211 (
  212     uint32_t expiryVal
  213         ///< [IN] Expiration time(in second) to boot. This is relative time from
  214         ///<      modem/app processor shutdown.
  215 );
  216 
  217 //--------------------------------------------------------------------------------------------------
  218 /**
  219  * Get the ultra low power manager firmware version.
  220  *
  221  * @return
  222  *      - LE_OK on success
  223  *      - LE_OVERFLOW if version string to big to fit in provided buffer
  224  *      - LE_FAULT for any other errors
  225  */
  226 //--------------------------------------------------------------------------------------------------
  227 le_result_t le_ulpm_GetFirmwareVersion
  228 (
  229     char* version,
  230         ///< [OUT] Firmware version string
  231 
  232     size_t versionNumElements
  233         ///< [IN]
  234 );
  235 
  236 //--------------------------------------------------------------------------------------------------
  237 /**
  238  * Initiate shutting down of app processor/modem etc.
  239  *
  240  * @return
  241  *      - LE_OK if entry to ultra low power mode initiates properly.
  242  *      - LE_NOT_POSSIBLE if shutting is not possible now. Try again.
  243  *      - LE_FAULT if failed to initiate.
  244  *
  245  */
  246 //--------------------------------------------------------------------------------------------------
  247 le_result_t le_ulpm_ShutDown
  248 (
  249     void
  250 );
  251 
  252 
  253 #endif // LE_ULPM_INTERFACE_H_INCLUDE_GUARD
  254 
le_ulpm_GpioState_t
le_ulpm_GpioState_t
Definition: le_ulpm_interface.h:157


le_ulpm_ShutDown
le_result_t le_ulpm_ShutDown(void)


le_result_t
le_result_t
Definition: le_basics.h:35


LE_ULPM_GPIO_BOTH
Gpio edge either rising or falling. 
Definition: le_ulpm_interface.h:171


LE_ULPM_GPIO_LOW
Gpio voltage level low. 
Definition: le_ulpm_interface.h:159


le_ulpm_GetFirmwareVersion
le_result_t le_ulpm_GetFirmwareVersion(char *version, size_t versionNumElements)


le_ulpm_DisconnectService
void le_ulpm_DisconnectService(void)


LE_ULPM_GPIO_OFF
Gpio off. 
Definition: le_ulpm_interface.h:174


le_ulpm_ConnectService
void le_ulpm_ConnectService(void)


LE_ULPM_GPIO_RISING
Gpio edge rising. 
Definition: le_ulpm_interface.h:165


LE_ULPM_GPIO_FALLING
Gpio edge falling. 
Definition: le_ulpm_interface.h:168


le_ulpm_BootOnGpio
le_result_t le_ulpm_BootOnGpio(uint32_t gpioNum, le_ulpm_GpioState_t state)



LE_ULPM_GPIO_HIGH
Gpio voltage level high. 
Definition: le_ulpm_interface.h:162


le_ulpm_BootOnTimer
le_result_t le_ulpm_BootOnTimer(uint32_t expiryVal)


le_ulpm_TryConnectService
le_result_t le_ulpm_TryConnectService(void)