le_ulpm_interface.h

Go to the documentation of this file.
    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 
   87 //--------------------------------------------------------------------------------------------------
   88 /**
   89  * Type for handler called when a server disconnects.
   90  */
   91 //--------------------------------------------------------------------------------------------------
   92 typedef void (*le_ulpm_DisconnectHandler_t)(void *);
   93 
   94 //--------------------------------------------------------------------------------------------------
   95 /**
   96  *
   97  * Connect the current client thread to the service providing this API. Block until the service is
   98  * available.
   99  *
  100  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  101  * called before any other functions in this API.  Normally, ConnectService is automatically called
  102  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  103  *
  104  * This function is created automatically.
  105  */
  106 //--------------------------------------------------------------------------------------------------
  107 void le_ulpm_ConnectService
  108 (
  109     void
  110 );
  111 
  112 //--------------------------------------------------------------------------------------------------
  113 /**
  114  *
  115  * Try to connect the current client thread to the service providing this API. Return with an error
  116  * if the service is not available.
  117  *
  118  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  119  * called before any other functions in this API.  Normally, ConnectService is automatically called
  120  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  121  *
  122  * This function is created automatically.
  123  *
  124  * @return
  125  *  - LE_OK if the client connected successfully to the service.
  126  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  127  *    bound.
  128  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  129  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  130  */
  131 //--------------------------------------------------------------------------------------------------
  132 le_result_t le_ulpm_TryConnectService
  133 (
  134     void
  135 );
  136 
  137 //--------------------------------------------------------------------------------------------------
  138 /**
  139  * Set handler called when server disconnection is detected.
  140  *
  141  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  142  * to continue without exiting, it should call longjmp() from inside the handler.
  143  */
  144 //--------------------------------------------------------------------------------------------------
  145 void le_ulpm_SetServerDisconnectHandler
  146 (
  147     le_ulpm_DisconnectHandler_t disconnectHandler,
  148     void *contextPtr
  149 );
  150 
  151 //--------------------------------------------------------------------------------------------------
  152 /**
  153  *
  154  * Disconnect the current client thread from the service providing this API.
  155  *
  156  * Normally, this function doesn't need to be called. After this function is called, there's no
  157  * longer a connection to the service, and the functions in this API can't be used. For details, see
  158  * @ref apiFilesC_client.
  159  *
  160  * This function is created automatically.
  161  */
  162 //--------------------------------------------------------------------------------------------------
  163 void le_ulpm_DisconnectService
  164 (
  165     void
  166 );
  167 
  168 
  169 //--------------------------------------------------------------------------------------------------
  170 /**
  171  * Maximum version length of mcu firmware.
  172  */
  173 //--------------------------------------------------------------------------------------------------
  174 #define LE_ULPM_MAX_VERS_LEN 8
  175 
  176 //--------------------------------------------------------------------------------------------------
  177 /**
  178  * State of gpio pin. This state will be used to exit from low power state.
  179  */
  180 //--------------------------------------------------------------------------------------------------
  181 typedef enum
  182 {
  183     LE_ULPM_GPIO_LOW = 0,
  184         ///< Gpio voltage level low.
  185     LE_ULPM_GPIO_HIGH = 1,
  186         ///< Gpio voltage level high.
  187     LE_ULPM_GPIO_RISING = 2,
  188         ///< Gpio edge rising.
  189     LE_ULPM_GPIO_FALLING = 3,
  190         ///< Gpio edge falling.
  191     LE_ULPM_GPIO_BOTH = 4,
  192         ///< Gpio edge either rising or falling.
  193     LE_ULPM_GPIO_OFF = 5
  194         ///< Gpio off.
  195 }
  196 le_ulpm_GpioState_t;
  197 
  198 
  199 //--------------------------------------------------------------------------------------------------
  200 /**
  201  * Configure the system to boot based on a state change of a given GPIO.
  202  *
  203  * @return
  204  *      - LE_OK if specified gpio is configured as boot source.
  205  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to configure the GPIO as a
  206  *        boot source.
  207  *      - LE_UNSUPPORTED if the device lacks the ability to boot based on the given GPIO.
  208  *      - LE_BAD_PARAMETER if the state parameter was rejected.
  209  *      - LE_FAULT if there is a non-specific failure.
  210  */
  211 //--------------------------------------------------------------------------------------------------
  212 le_result_t le_ulpm_BootOnGpio
  213 (
  214     uint32_t gpioNum,
  215         ///< [IN] Gpio number to boot.
  216     le_ulpm_GpioState_t state
  217         ///< [IN] State which should cause boot.
  218 );
  219 
  220 //--------------------------------------------------------------------------------------------------
  221 /**
  222  * Boot after expiration of timer interval.
  223  *
  224  * @return
  225  *      - LE_OK if timer is configured as boot source.
  226  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to configure the timer as a
  227  *        boot source.
  228  *      - LE_UNSUPPORTED if the device lacks the ability to boot based on a timer.
  229  *      - LE_BAD_PARAMETER if the state parameter was rejected.
  230  *      - LE_FAULT if there is a non-specific failure.
  231  */
  232 //--------------------------------------------------------------------------------------------------
  233 le_result_t le_ulpm_BootOnTimer
  234 (
  235     uint32_t expiryVal
  236         ///< [IN] Expiration time(in second) to boot. This is relative time from
  237         ///< modem/app processor shutdown.
  238 );
  239 
  240 //--------------------------------------------------------------------------------------------------
  241 /**
  242  * Configure and enable an ADC as a boot source.
  243  *
  244  * It is possible to specify a single range of operation or two ranges of operation with a
  245  * non-operational range in between.  When bootAboveAdcReading is less than bootBelowAdcReading,
  246  * then a single range bootAboveReading to bootBelowReading is the configured operational range.
  247  * However if bootAboveAdcReading is greater than bootBelowAdcReading, then there are two
  248  * operational ranges.  The first is any reading less than bootBelowAdcReading and the second is any
  249  * reading greater than bootAboveAdcReading.
  250  *
  251  * @return
  252  *      - LE_OK on success
  253  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to configure the adc as a
  254  *        boot source.
  255  *      - LE_OVERFLOW if the provided bootAboveAdcReading or bootBelowAdcReading are too large to
  256  *        convert to fit in the internal string buffer.
  257  *      - LE_BAD_PARAMETER if the pollIntervalInMs, bootAboveAdcReading or bootBelowAdcReading
  258  *        parameter were rejected.
  259  *      - LE_UNSUPPORTED if the device does not support using the given adc as a boot source.
  260  *      - LE_FAULT if there is a non-specific failure.
  261  */
  262 //--------------------------------------------------------------------------------------------------
  263 le_result_t le_ulpm_BootOnAdc
  264 (
  265     uint32_t adcNum,
  266         ///< [IN] Number of the ADC to configure
  267     uint32_t pollIntervalInMs,
  268         ///< [IN] How frequently to poll the ADC while sleeping
  269     double bootAboveAdcReading,
  270         ///< [IN] Reading above which the system should boot
  271     double bootBelowAdcReading
  272         ///< [IN] Reading below which the system should boot
  273 );
  274 
  275 //--------------------------------------------------------------------------------------------------
  276 /**
  277  * Get the ultra low power manager firmware version.
  278  *
  279  * @return
  280  *      - LE_OK on success
  281  *      - LE_OVERFLOW if version string to big to fit in provided buffer
  282  *      - LE_FAULT for any other errors
  283  */
  284 //--------------------------------------------------------------------------------------------------
  285 le_result_t le_ulpm_GetFirmwareVersion
  286 (
  287     char* version,
  288         ///< [OUT] Firmware version string
  289     size_t versionSize
  290         ///< [IN]
  291 );
  292 
  293 //--------------------------------------------------------------------------------------------------
  294 /**
  295  * Initiate shutting down of app processor/modem etc.
  296  *
  297  * @return
  298  *      - LE_OK if entry to ultra low power mode initiates properly.
  299  *      - LE_NOT_POSSIBLE if shutting is not possible now. Try again.
  300  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to perform a shutdown.
  301  *      - LE_UNSUPPORTED if the device lacks the ability to shutdown via ULPM.
  302  *      - LE_FAULT if there is a non-specific failure.
  303  */
  304 //--------------------------------------------------------------------------------------------------
  305 le_result_t le_ulpm_ShutDown
  306 (
  307     void
  308 );
  309 
  310 #endif // LE_ULPM_INTERFACE_H_INCLUDE_GUARD
le_ulpm_GpioState_t
le_ulpm_GpioState_t
Definition: le_ulpm_interface.h:181


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_GPIO_BOTH
Gpio edge either rising or falling. 
Definition: le_ulpm_interface.h:191


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


le_ulpm_SetServerDisconnectHandler
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_GPIO_OFF
Gpio off. 
Definition: le_ulpm_interface.h:193


le_ulpm_ConnectService
void le_ulpm_ConnectService(void)


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


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


le_ulpm_DisconnectHandler_t
void(* le_ulpm_DisconnectHandler_t)(void *)
Definition: le_ulpm_interface.h:92


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:185


le_ulpm_BootOnTimer
le_result_t le_ulpm_BootOnTimer(uint32_t expiryVal)


le_ulpm_TryConnectService
le_result_t le_ulpm_TryConnectService(void)