le_pm_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_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 //--------------------------------------------------------------------------------------------------
   95 /**
   96  * Type for handler called when a server disconnects.
   97  */
   98 //--------------------------------------------------------------------------------------------------
   99 typedef void (*le_pm_DisconnectHandler_t)(void *);
  100 
  101 //--------------------------------------------------------------------------------------------------
  102 /**
  103  *
  104  * Connect the current client thread to the service providing this API. Block until the service is
  105  * available.
  106  *
  107  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  108  * called before any other functions in this API.  Normally, ConnectService is automatically called
  109  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  110  *
  111  * This function is created automatically.
  112  */
  113 //--------------------------------------------------------------------------------------------------
  114 void le_pm_ConnectService
  115 (
  116     void
  117 );
  118 
  119 //--------------------------------------------------------------------------------------------------
  120 /**
  121  *
  122  * Try to connect the current client thread to the service providing this API. Return with an error
  123  * if the service is not available.
  124  *
  125  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  126  * called before any other functions in this API.  Normally, ConnectService is automatically called
  127  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  128  *
  129  * This function is created automatically.
  130  *
  131  * @return
  132  *  - LE_OK if the client connected successfully to the service.
  133  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  134  *    bound.
  135  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  136  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  137  */
  138 //--------------------------------------------------------------------------------------------------
  139 le_result_t le_pm_TryConnectService
  140 (
  141     void
  142 );
  143 
  144 //--------------------------------------------------------------------------------------------------
  145 /**
  146  * Set handler called when server disconnection is detected.
  147  *
  148  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  149  * to continue without exiting, it should call longjmp() from inside the handler.
  150  */
  151 //--------------------------------------------------------------------------------------------------
  152 LE_FULL_API void le_pm_SetServerDisconnectHandler
  153 (
  154     le_pm_DisconnectHandler_t disconnectHandler,
  155     void *contextPtr
  156 );
  157 
  158 //--------------------------------------------------------------------------------------------------
  159 /**
  160  *
  161  * Disconnect the current client thread from the service providing this API.
  162  *
  163  * Normally, this function doesn't need to be called. After this function is called, there's no
  164  * longer a connection to the service, and the functions in this API can't be used. For details, see
  165  * @ref apiFilesC_client.
  166  *
  167  * This function is created automatically.
  168  */
  169 //--------------------------------------------------------------------------------------------------
  170 void le_pm_DisconnectService
  171 (
  172     void
  173 );
  174 
  175 
  176 //--------------------------------------------------------------------------------------------------
  177 /**
  178  * Reference to wakeup source used by StayAwake and Relax function
  179  */
  180 //--------------------------------------------------------------------------------------------------
  181 
  182 
  183 //--------------------------------------------------------------------------------------------------
  184 /**
  185  * Create a wakeup source
  186  *
  187  * @return
  188  *      - Reference to wakeup source (to be used later for acquiring/releasing)
  189  *
  190  * @note The process exits if an invalid or existing tag is passed
  191  */
  192 //--------------------------------------------------------------------------------------------------
  193 le_pm_WakeupSourceRef_t le_pm_NewWakeupSource
  194 (
  195     uint32_t createOpts,
  196         ///< [IN] Wakeup source options
  197     const char* LE_NONNULL wsTag
  198         ///< [IN] Context-specific wakeup source tag
  199 );
  200 
  201 //--------------------------------------------------------------------------------------------------
  202 /**
  203  * Acquire a wakeup source
  204  *
  205  * @return
  206  *     - LE_OK          if the wakeup source is acquired
  207  *     - LE_NO_MEMORY   if the wakeup sources limit is reached
  208  *     - LE_FAULT       for other errors
  209  *
  210  * @note The process exits if an invalid reference is passed
  211  * @note The wakeup sources limit is fixed by the kernel CONFIG_PM_WAKELOCKS_LIMIT configuration
  212  *       variable
  213  */
  214 //--------------------------------------------------------------------------------------------------
  215 le_result_t le_pm_StayAwake
  216 (
  217     le_pm_WakeupSourceRef_t wsRef
  218         ///< [IN] Reference to a created wakeup source
  219 );
  220 
  221 //--------------------------------------------------------------------------------------------------
  222 /**
  223  * Release a previously acquired wakeup source
  224  *
  225  * @return
  226  *     - LE_OK          if the wakeup source is acquired
  227  *     - LE_NOT_FOUND   if the wakeup source was not currently acquired
  228  *     - LE_FAULT       for other errors
  229  *
  230  * @note The process exits if an invalid reference is passed
  231  */
  232 //--------------------------------------------------------------------------------------------------
  233 le_result_t le_pm_Relax
  234 (
  235     le_pm_WakeupSourceRef_t wsRef
  236         ///< [IN] Reference to a created wakeup source
  237 );
  238 
  239 //--------------------------------------------------------------------------------------------------
  240 /**
  241  * Release and destroy all acquired wakeup source, kill all clients
  242  *
  243  * @return
  244  *     - LE_OK              if the wakeup source is acquired
  245  *     - LE_NOT_PERMITTED   if the le_pm_StayAwake() has not failed with LE_NO_MEMORY
  246  *     - LE_FAULT           for other errors
  247  *
  248  * @note The service is available only if le_pm_StayAwake() has returned LE_NO_MEMORY. It should be
  249  *       used in the way to release and destroy all wakeup sources.
  250  */
  251 //--------------------------------------------------------------------------------------------------
  252 le_result_t le_pm_ForceRelaxAndDestroyAllWakeupSource
  253 (
  254     void
  255 );
  256 
  257 #endif // LE_PM_INTERFACE_H_INCLUDE_GUARD
le_result_t
le_result_t
Definition: le_basics.h:45
le_pm_DisconnectService
void le_pm_DisconnectService(void)
le_pm_ConnectService
void le_pm_ConnectService(void)
le_pm_DisconnectHandler_t
void(* le_pm_DisconnectHandler_t)(void *)
Definition: le_pm_interface.h:99
le_pm_ForceRelaxAndDestroyAllWakeupSource
le_result_t le_pm_ForceRelaxAndDestroyAllWakeupSource(void)
le_pm_NewWakeupSource
le_pm_WakeupSourceRef_t le_pm_NewWakeupSource(uint32_t createOpts, const char *LE_NONNULL wsTag)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_pm_Relax
le_result_t le_pm_Relax(le_pm_WakeupSourceRef_t wsRef)
le_pm_StayAwake
le_result_t le_pm_StayAwake(le_pm_WakeupSourceRef_t wsRef)
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)