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


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


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_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
void le_pm_SetServerDisconnectHandler(le_pm_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_pm_WakeupSourceRef_t
struct le_pm_WakeupSource * le_pm_WakeupSourceRef_t
Definition: le_pm_interface.h:201