le_pm_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_pm Power Manager
   14  *
   15  * @ref le_pm_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * Components need access to the Power Manager to control the system's wake-up state.
   20  * Operations that need fast response times (e.g., maintaining call state or playing/recording a
   21  * media stream) result in high interrupt rates; keeping the system awake results in better performance
   22  * and power efficiency.
   23  *
   24  * Power Manager uses kernel wakeup sources to keep the system awake when at least one of the
   25  * registered components requests a wakeup source to be held. When all wakeup sources are
   26  * released, the system may enter a suspend state depending on the status of other (unrelated) wakeup
   27  * sources.
   28  *
   29  * @section le_pm_binding IPC interfaces binding
   30  *
   31  * All the functions of this API are provided by the @b powerMgr service.
   32  *
   33  * Here's a code sample binding to Power Manager services:
   34  * @verbatim
   35    bindings:
   36    {
   37       clientExe.clientComponent.le_pm -> powerMgr.le_pm
   38    }
   39    @endverbatim
   40  *
   41  * @section le_pm_request Requesting and releasing a wakeup source
   42  *
   43  * The Power Manager service provides basic API for requesting and releasing a wakeup source.
   44  * Power Manager's clients call @c le_pm_NewWakeupSource() to create a wakeup source. This function
   45  * returns a @ref le_pm_WakeupSourceRef_t type that can later be used to acquire and release a
   46  * wakeup source through @c le_pm_StayAwake() and le_pm_Relax(), respectively. Wakeup sources
   47  * are not reference-counted, which means multiple calls to le_pm_StayAwake() can be canceled
   48  * by a single call to le_pm_Relax().
   49  *
   50  * To have a reference-counted wakeup-source, set the LE_PM_REF_COUNT bit in the opts argument.
   51  * When this bit is set, each le_pm_StayAwake() increments a counter, and multiple calls to
   52  * le_pm_Relax() is necessary to release the wakeup source.
   53  *
   54  * Power Manager service will automatically release and delete all wakeup sources held on behalf
   55  * of an exiting or disconnecting client.
   56  *
   57  * The service le_pm_ForceRelaxAndDestroyAllWakeupSource() will return LE_NOT_PERMITTED until a
   58  * call to le_pm_StayAwake() fails with LE_NO_MEMORY. This should be considered as an ultime
   59  * defense if no more wakeup sources may be acquired or relased. This service will kill all
   60  * clients and release and destroy all wakeup source currently managed.
   61  *
   62  * At startup, the Power Manager will release all wakeup sources matching the pattern for Legato
   63  * apps and will keep the others untouched.
   64  *
   65  * For deterministic behaviour, clients requesting services of Power Manager should have
   66  * CAP_EPOLLWAKEUP (or CAP_BLOCK_SUSPEND) capability assigned.
   67  *
   68  * The maximum number of wakeup sources managed at same time is fixed by the kernel configuration
   69  * option CONFIG_PM_WAKELOCKS_LIMIT.
   70  *
   71  * <HR>
   72  *
   73  * Copyright (C) Sierra Wireless Inc.
   74  */
   75 /**
   76  * @file le_pm_interface.h
   77  *
   78  * Legato @ref c_pm include file.
   79  *
   80  * Copyright (C) Sierra Wireless Inc.
   81  */
   82 /**
   83  * Some useful constants
   84  */
   85 
   86 #ifndef LE_PM_INTERFACE_H_INCLUDE_GUARD
   87 #define LE_PM_INTERFACE_H_INCLUDE_GUARD
   88 
   89 
   90 #include "legato.h"
   91 
   92 // Internal includes for this interface
   93 #include "le_pm_common.h"
   94 /** @addtogroup le_pm le_pm API Reference
   95  * @{
   96  * @file le_pm_common.h
   97  * @file le_pm_interface.h **/
   98 //--------------------------------------------------------------------------------------------------
   99 /**
  100  * Type for handler called when a server disconnects.
  101  */
  102 //--------------------------------------------------------------------------------------------------
  103 typedef void (*le_pm_DisconnectHandler_t)(void *);
  104 
  105 //--------------------------------------------------------------------------------------------------
  106 /**
  107  *
  108  * Connect the current client thread to the service providing this API. Block until the service is
  109  * available.
  110  *
  111  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  112  * called before any other functions in this API.  Normally, ConnectService is automatically called
  113  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  114  *
  115  * This function is created automatically.
  116  */
  117 //--------------------------------------------------------------------------------------------------
  118 void le_pm_ConnectService
  119 (
  120     void
  121 );
  122 
  123 //--------------------------------------------------------------------------------------------------
  124 /**
  125  *
  126  * Try to connect the current client thread to the service providing this API. Return with an error
  127  * if the service is not available.
  128  *
  129  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  130  * called before any other functions in this API.  Normally, ConnectService is automatically called
  131  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  132  *
  133  * This function is created automatically.
  134  *
  135  * @return
  136  *  - LE_OK if the client connected successfully to the service.
  137  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  138  *    bound.
  139  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  140  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  141  */
  142 //--------------------------------------------------------------------------------------------------
  143 le_result_t le_pm_TryConnectService
  144 (
  145     void
  146 );
  147 
  148 //--------------------------------------------------------------------------------------------------
  149 /**
  150  * Set handler called when server disconnection is detected.
  151  *
  152  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  153  * to continue without exiting, it should call longjmp() from inside the handler.
  154  */
  155 //--------------------------------------------------------------------------------------------------
  156 LE_FULL_API void le_pm_SetServerDisconnectHandler
  157 (
  158     le_pm_DisconnectHandler_t disconnectHandler,
  159     void *contextPtr
  160 );
  161 
  162 //--------------------------------------------------------------------------------------------------
  163 /**
  164  *
  165  * Disconnect the current client thread from the service providing this API.
  166  *
  167  * Normally, this function doesn't need to be called. After this function is called, there's no
  168  * longer a connection to the service, and the functions in this API can't be used. For details, see
  169  * @ref apiFilesC_client.
  170  *
  171  * This function is created automatically.
  172  */
  173 //--------------------------------------------------------------------------------------------------
  174 void le_pm_DisconnectService
  175 (
  176     void
  177 );
  178 
  179 
  180 //--------------------------------------------------------------------------------------------------
  181 /**
  182  * Reference to wakeup source used by StayAwake and Relax function
  183  */
  184 //--------------------------------------------------------------------------------------------------
  185 
  186 
  187 //--------------------------------------------------------------------------------------------------
  188 /**
  189  * Create a wakeup source
  190  *
  191  * @return
  192  *      - Reference to wakeup source (to be used later for acquiring/releasing)
  193  *
  194  * @note The process exits if an invalid or existing tag is passed
  195  */
  196 //--------------------------------------------------------------------------------------------------
  197 le_pm_WakeupSourceRef_t le_pm_NewWakeupSource
  198 (
  199     uint32_t createOpts,
  200         ///< [IN] Wakeup source options
  201     const char* LE_NONNULL wsTag
  202         ///< [IN] Context-specific wakeup source tag
  203 );
  204 
  205 //--------------------------------------------------------------------------------------------------
  206 /**
  207  * Acquire a wakeup source
  208  *
  209  * @return
  210  *     - LE_OK          if the wakeup source is acquired
  211  *     - LE_NO_MEMORY   if the wakeup sources limit is reached
  212  *     - LE_FAULT       for other errors
  213  *
  214  * @note The process exits if an invalid reference is passed
  215  * @note The wakeup sources limit is fixed by the kernel CONFIG_PM_WAKELOCKS_LIMIT configuration
  216  *       variable
  217  */
  218 //--------------------------------------------------------------------------------------------------
  219 le_result_t le_pm_StayAwake
  220 (
  221     le_pm_WakeupSourceRef_t wsRef
  222         ///< [IN] Reference to a created wakeup source
  223 );
  224 
  225 //--------------------------------------------------------------------------------------------------
  226 /**
  227  * Release a previously acquired wakeup source
  228  *
  229  * @return
  230  *     - LE_OK          if the wakeup source is acquired
  231  *     - LE_NOT_FOUND   if the wakeup source was not currently acquired
  232  *     - LE_FAULT       for other errors
  233  *
  234  * @note The process exits if an invalid reference is passed
  235  */
  236 //--------------------------------------------------------------------------------------------------
  237 le_result_t le_pm_Relax
  238 (
  239     le_pm_WakeupSourceRef_t wsRef
  240         ///< [IN] Reference to a created wakeup source
  241 );
  242 
  243 //--------------------------------------------------------------------------------------------------
  244 /**
  245  * Release and destroy all acquired wakeup source, kill all clients
  246  *
  247  * @return
  248  *     - LE_OK              if the wakeup source is acquired
  249  *     - LE_NOT_PERMITTED   if the le_pm_StayAwake() has not failed with LE_NO_MEMORY
  250  *     - LE_FAULT           for other errors
  251  *
  252  * @note The service is available only if le_pm_StayAwake() has returned LE_NO_MEMORY. It should be
  253  *       used in the way to release and destroy all wakeup sources.
  254  */
  255 //--------------------------------------------------------------------------------------------------
  256 le_result_t le_pm_ForceRelaxAndDestroyAllWakeupSource
  257 (
  258     void
  259 );
  260 
  261 /** @} **/
  262 
  263 #endif // LE_PM_INTERFACE_H_INCLUDE_GUARD
le_pm_StayAwake
le_result_t le_pm_StayAwake(le_pm_WakeupSourceRef_t wsRef)


le_pm_ForceRelaxAndDestroyAllWakeupSource
le_result_t le_pm_ForceRelaxAndDestroyAllWakeupSource(void)


le_pm_TryConnectService
le_result_t le_pm_TryConnectService(void)


le_pm_SetServerDisconnectHandler
LE_FULL_API void le_pm_SetServerDisconnectHandler(le_pm_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_result_t
le_result_t
Definition: le_basics.h:46


le_pm_common.h


le_pm_WakeupSourceRef_t
struct le_pm_WakeupSource * le_pm_WakeupSourceRef_t
Definition: le_pm_common.h:54


le_pm_ConnectService
void le_pm_ConnectService(void)


le_pm_NewWakeupSource
le_pm_WakeupSourceRef_t le_pm_NewWakeupSource(uint32_t createOpts, const char *LE_NONNULL wsTag)


le_pm_DisconnectHandler_t
void(* le_pm_DisconnectHandler_t)(void *)
Definition: le_pm_interface.h:103


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40


le_pm_DisconnectService
void le_pm_DisconnectService(void)



le_pm_Relax
le_result_t le_pm_Relax(le_pm_WakeupSourceRef_t wsRef)