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  * Possible ULPS (Ultra Low Power State) configurations to select before shutdown.
  180  *
  181  * Value 3 is skipped as it should not be used according to swimcu_pm documentation.
  182  */
  183 //--------------------------------------------------------------------------------------------------
  184 
  185 
  186 //--------------------------------------------------------------------------------------------------
  187 /**
  188  * Configure the system to boot based on a state change of a given GPIO.
  189  *
  190  * @return
  191  *      - LE_OK if specified gpio is configured as boot source.
  192  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to configure the GPIO as a
  193  *        boot source.
  194  *      - LE_UNSUPPORTED if the device lacks the ability to boot based on the given GPIO.
  195  *      - LE_BAD_PARAMETER if the state parameter was rejected.
  196  *      - LE_FAULT if there is a non-specific failure.
  197  */
  198 //--------------------------------------------------------------------------------------------------
  199 le_result_t le_ulpm_BootOnGpio
  200 (
  201     uint32_t gpioNum,
  202         ///< [IN] Gpio number to boot.
  203     le_ulpm_GpioState_t state
  204         ///< [IN] State which should cause boot.
  205 );
  206 
  207 //--------------------------------------------------------------------------------------------------
  208 /**
  209  * Boot after expiration of timer interval.
  210  *
  211  * @return
  212  *      - LE_OK if timer is configured as boot source.
  213  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to configure the timer as a
  214  *        boot source.
  215  *      - LE_UNSUPPORTED if the device lacks the ability to boot based on a timer.
  216  *      - LE_BAD_PARAMETER if the state parameter was rejected.
  217  *      - LE_FAULT if there is a non-specific failure.
  218  */
  219 //--------------------------------------------------------------------------------------------------
  220 le_result_t le_ulpm_BootOnTimer
  221 (
  222     uint32_t expiryVal
  223         ///< [IN] Expiration time(in second) to boot. This is relative time from
  224         ///< modem/app processor shutdown.
  225 );
  226 
  227 //--------------------------------------------------------------------------------------------------
  228 /**
  229  * Configure and enable an ADC as a boot source.
  230  *
  231  * It is possible to specify a single range of operation or two ranges of operation with a
  232  * non-operational range in between.  When bootAboveAdcReading is less than bootBelowAdcReading,
  233  * then a single range bootAboveReading to bootBelowReading is the configured operational range.
  234  * However if bootAboveAdcReading is greater than bootBelowAdcReading, then there are two
  235  * operational ranges.  The first is any reading less than bootBelowAdcReading and the second is any
  236  * reading greater than bootAboveAdcReading.
  237  *
  238  * @return
  239  *      - LE_OK on success
  240  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to configure the adc as a
  241  *        boot source.
  242  *      - LE_OVERFLOW if the provided bootAboveAdcReading or bootBelowAdcReading are too large to
  243  *        convert to fit in the internal string buffer.
  244  *      - LE_BAD_PARAMETER if the pollIntervalInMs, bootAboveAdcReading or bootBelowAdcReading
  245  *        parameter were rejected.
  246  *      - LE_UNSUPPORTED if the device does not support using the given adc as a boot source.
  247  *      - LE_FAULT if there is a non-specific failure.
  248  */
  249 //--------------------------------------------------------------------------------------------------
  250 le_result_t le_ulpm_BootOnAdc
  251 (
  252     uint32_t adcNum,
  253         ///< [IN] Number of the ADC to configure
  254     uint32_t pollIntervalInMs,
  255         ///< [IN] How frequently to poll the ADC while sleeping
  256     double bootAboveAdcReading,
  257         ///< [IN] Reading above which the system should boot
  258     double bootBelowAdcReading
  259         ///< [IN] Reading below which the system should boot
  260 );
  261 
  262 //--------------------------------------------------------------------------------------------------
  263 /**
  264  * Get the ultra low power manager firmware version.
  265  *
  266  * @return
  267  *      - LE_OK on success
  268  *      - LE_OVERFLOW if version string to big to fit in provided buffer
  269  *      - LE_FAULT for any other errors
  270  */
  271 //--------------------------------------------------------------------------------------------------
  272 le_result_t le_ulpm_GetFirmwareVersion
  273 (
  274     char* version,
  275         ///< [OUT] Firmware version string
  276     size_t versionSize
  277         ///< [IN]
  278 );
  279 
  280 //--------------------------------------------------------------------------------------------------
  281 /**
  282  * Initiate shutting down of app processor/modem etc.
  283  *
  284  * @return
  285  *      - LE_OK if entry to ultra low power mode initiates properly.
  286  *      - LE_NOT_POSSIBLE if shutting is not possible now. Try again.
  287  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to perform a shutdown.
  288  *      - LE_UNSUPPORTED if the device lacks the ability to shutdown via ULPM.
  289  *      - LE_FAULT if there is a non-specific failure.
  290  */
  291 //--------------------------------------------------------------------------------------------------
  292 le_result_t le_ulpm_ShutDown
  293 (
  294     void
  295 );
  296 
  297 //--------------------------------------------------------------------------------------------------
  298 /**
  299  * Initiate reboot of app processor/modem etc.
  300  *
  301  * @return
  302  *      - LE_OK if reboot initiates properly.
  303  *      - LE_NOT_POSSIBLE if rebooting is not possible now. Try again.
  304  *      - LE_NOT_PERMITTED if the process lacks sufficient permissions to perform a reboot.
  305  *      - LE_UNSUPPORTED if the device lacks the ability to reboot via ULPM.
  306  *      - LE_FAULT if there is a non-specific failure.
  307  */
  308 //--------------------------------------------------------------------------------------------------
  309 le_result_t le_ulpm_Reboot
  310 (
  311     void
  312 );
  313 
  314 //--------------------------------------------------------------------------------------------------
  315 /**
  316  * Set the Low Power Mode configuration to apply when le_ulpm_ShutDown is called.
  317  *
  318  * @return
  319  *      - LE_OK on success
  320  *      - LE_BAD_PARAMETER if the value of a parameter is invalid
  321  *      - LE_UNSUPPORTED if not supported
  322  *      - LE_FAULT for any other errors
  323  */
  324 //--------------------------------------------------------------------------------------------------
  325 le_result_t le_ulpm_SetShutDownStrategy
  326 (
  327     le_ulpm_ULPSConfiguration_t ulpsConfig
  328         ///< [IN] Value used to configure ULPS.
  329 );
  330 
  331 #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:45
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_Reboot
le_result_t le_ulpm_Reboot(void)
le_ulpm_BootOnTimer
le_result_t le_ulpm_BootOnTimer(uint32_t expiryVal)
le_ulpm_TryConnectService
le_result_t le_ulpm_TryConnectService(void)
le_ulpm_SetShutDownStrategy
le_result_t le_ulpm_SetShutDownStrategy(le_ulpm_ULPSConfiguration_t ulpsConfig)