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


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


le_ulpm_BootOnTimer
le_result_t le_ulpm_BootOnTimer(uint32_t expiryVal)


le_result_t
le_result_t
Definition: le_basics.h:46


le_ulpm_SetShutDownStrategy
le_result_t le_ulpm_SetShutDownStrategy(le_ulpm_ULPSConfiguration_t ulpsConfig)


le_ulpm_ConnectService
void le_ulpm_ConnectService(void)


le_ulpm_ShutDown
le_result_t le_ulpm_ShutDown(void)


le_ulpm_GpioState_t
le_ulpm_GpioState_t
Definition: le_ulpm_common.h:40


le_ulpm_BootOnGpio
le_result_t le_ulpm_BootOnGpio(uint32_t gpioNum, le_ulpm_GpioState_t state)


le_ulpm_BootOnAdc
le_result_t le_ulpm_BootOnAdc(uint32_t adcNum, uint32_t pollIntervalInMs, double bootAboveAdcReading, double bootBelowAdcReading)


le_ulpm_Reboot
le_result_t le_ulpm_Reboot(void)


le_ulpm_GetFirmwareVersion
le_result_t le_ulpm_GetFirmwareVersion(char *version, size_t versionSize)


le_ulpm_common.h


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40



le_ulpm_ULPSConfiguration_t
le_ulpm_ULPSConfiguration_t
Definition: le_ulpm_common.h:65


le_ulpm_SetServerDisconnectHandler
LE_FULL_API void le_ulpm_SetServerDisconnectHandler(le_ulpm_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_ulpm_TryConnectService
le_result_t le_ulpm_TryConnectService(void)