le_updateCtrl_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_updateCtrl Update Control API
   14  *
   15  * @ref le_updateCtrl_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * This API is used by privileged apps to control the software update process.  It can be used to:
   20  * - prevent updates from happening or
   21  * - control the marking of a system update as "good" or "bad".
   22  *
   23  * Note that this is not part of the Update API (le_update) because the
   24  * Update API can be used by less trusted apps to feed signed/encrypted updates to the
   25  * Update Daemon, and we may not trust those same apps to have the ability to prevent someone
   26  * else from updating or rolling-back the system.
   27  *
   28  *
   29  * @section le_updateCtrl_prevention Preventing Updates During Critical Operations
   30  *
   31  * To protect against updates during critical periods of operation (such as when performing an
   32  * emergency call in response to a vehicle collision), the following functions are provided:
   33  *
   34  * - le_updateCtrl_Defer() - prevent all updates until further notice.
   35  * - le_updateCtrl_Allow() - allow updates to go ahead.
   36  *
   37  * Updates will not be allowed to go ahead until no clients are deferring updates. So, if client A
   38  * and client B both call le_updateCtrl_Defer(), updates will be deferred until both client A and
   39  * client B have called le_updateCtrl_Allow().
   40  *
   41  * le_updateCtrl_Defer() will also prevent rollbacks unless a fault triggers the Supervisor to
   42  * restart the framework or reboot the target.  See below for more information on rollbacks.
   43  *
   44  *
   45  * @section le_updateCtrl_probation Controlling the Probation Period
   46  *
   47  * Whenever a new system is started, a probation period begins.  If the system stays running for
   48  * the entire probation period, the system is marked "good".  But, during the probation period,
   49  * if an app faults enough times in a short enough period for the Supervisor to give up on trying
   50  * to start it, the system update is marked "bad" and the system is rolled-back to the last known
   51  * "good" system.
   52  *
   53  * In some cases, a customer may want to extend the probation period of their new system for a
   54  * non-deterministic amount of time, until it has had a chance to perform some action in the
   55  * real world (such as successfully "phoning home" at least once).
   56  *
   57  * To support this, the functions le_updateCtrl_LockProbation() and le_updateCtrl_UnlockProbation()
   58  * are provided, where each call to "Lock" must be matched with a call to "Unlock".
   59  *
   60  * For those who want to mark "good" at some point of their own determination, regardless
   61  * of how long the system has been up, le_updateCtrl_MarkGood() is provided.
   62  *
   63  * And for those who want to mark the system "bad" and trigger a rollback at some point of
   64  * their own choosing, le_updateCtrl_FailProbation() is provided.
   65  *
   66  * Calls to any of the functions that affect the probation period are ignored if the probation
   67  * period is already over (if the system is already marked "good"). Once it is "good", it stays
   68  * "good".
   69  *
   70  * If someone tries to update the system while it is still in its probation period, the update
   71  * will be refused.  To override this, call le_updateCtrl_FailProbation() or
   72  * le_updateCtrl_MarkGood() to end the probation period before trying to apply the new
   73  * system update.
   74  *
   75  * @note If a reboot occurs during the probation period, the probation period will start over.
   76  * But, if the system reboots more than a few times without reaching the end of its probation
   77  * period first, then the system will be rolled-back to the last known "good" system.
   78  *
   79  * <HR>
   80  *
   81  * Copyright (C) Sierra Wireless Inc.
   82  */
   83 /**
   84  * @file le_updateCtrl_interface.h
   85  *
   86  * Legato @ref c_updateCtrl include file.
   87  *
   88  * Copyright (C) Sierra Wireless Inc.
   89  */
   90 
   91 #ifndef LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
   92 #define LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
   93 
   94 
   95 #include "legato.h"
   96 
   97 // Internal includes for this interface
   98 #include "le_updateCtrl_common.h"
   99 /** @addtogroup le_updateCtrl le_updateCtrl API Reference
  100  * @{
  101  * @file le_updateCtrl_common.h
  102  * @file le_updateCtrl_interface.h **/
  103 //--------------------------------------------------------------------------------------------------
  104 /**
  105  * Type for handler called when a server disconnects.
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 typedef void (*le_updateCtrl_DisconnectHandler_t)(void *);
  109 
  110 //--------------------------------------------------------------------------------------------------
  111 /**
  112  *
  113  * Connect the current client thread to the service providing this API. Block until the service is
  114  * available.
  115  *
  116  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  117  * called before any other functions in this API.  Normally, ConnectService is automatically called
  118  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  119  *
  120  * This function is created automatically.
  121  */
  122 //--------------------------------------------------------------------------------------------------
  123 void le_updateCtrl_ConnectService
  124 (
  125     void
  126 );
  127 
  128 //--------------------------------------------------------------------------------------------------
  129 /**
  130  *
  131  * Try to connect the current client thread to the service providing this API. Return with an error
  132  * if the service is not available.
  133  *
  134  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  135  * called before any other functions in this API.  Normally, ConnectService is automatically called
  136  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  137  *
  138  * This function is created automatically.
  139  *
  140  * @return
  141  *  - LE_OK if the client connected successfully to the service.
  142  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  143  *    bound.
  144  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  145  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  146  */
  147 //--------------------------------------------------------------------------------------------------
  148 le_result_t le_updateCtrl_TryConnectService
  149 (
  150     void
  151 );
  152 
  153 //--------------------------------------------------------------------------------------------------
  154 /**
  155  * Set handler called when server disconnection is detected.
  156  *
  157  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  158  * to continue without exiting, it should call longjmp() from inside the handler.
  159  */
  160 //--------------------------------------------------------------------------------------------------
  161 LE_FULL_API void le_updateCtrl_SetServerDisconnectHandler
  162 (
  163     le_updateCtrl_DisconnectHandler_t disconnectHandler,
  164     void *contextPtr
  165 );
  166 
  167 //--------------------------------------------------------------------------------------------------
  168 /**
  169  *
  170  * Disconnect the current client thread from the service providing this API.
  171  *
  172  * Normally, this function doesn't need to be called. After this function is called, there's no
  173  * longer a connection to the service, and the functions in this API can't be used. For details, see
  174  * @ref apiFilesC_client.
  175  *
  176  * This function is created automatically.
  177  */
  178 //--------------------------------------------------------------------------------------------------
  179 void le_updateCtrl_DisconnectService
  180 (
  181     void
  182 );
  183 
  184 
  185 //--------------------------------------------------------------------------------------------------
  186 /**
  187  * State of the system.
  188  */
  189 //--------------------------------------------------------------------------------------------------
  190 
  191 
  192 //--------------------------------------------------------------------------------------------------
  193 /**
  194  * Prevent all updates (and roll-backs) until further notice.
  195  */
  196 //--------------------------------------------------------------------------------------------------
  197 void le_updateCtrl_Defer
  198 (
  199     void
  200 );
  201 
  202 //--------------------------------------------------------------------------------------------------
  203 /**
  204  * Allow updates to go ahead.
  205  */
  206 //--------------------------------------------------------------------------------------------------
  207 void le_updateCtrl_Allow
  208 (
  209     void
  210 );
  211 
  212 //--------------------------------------------------------------------------------------------------
  213 /**
  214  * Prevent the probation period from ending.
  215  *
  216  * @return false if lock failed (for example if not in a probation period).
  217  */
  218 //--------------------------------------------------------------------------------------------------
  219 bool le_updateCtrl_LockProbation
  220 (
  221     void
  222 );
  223 
  224 //--------------------------------------------------------------------------------------------------
  225 /**
  226  * Cancels a call to LockProbation(), allow the probation period to end.
  227  *
  228  * @note Must match previous successful call to LockProbation().
  229  */
  230 //--------------------------------------------------------------------------------------------------
  231 void le_updateCtrl_UnlockProbation
  232 (
  233     void
  234 );
  235 
  236 //--------------------------------------------------------------------------------------------------
  237 /**
  238  * Marks the system "good", ending the probation period.
  239  *
  240  * @return
  241  *      - LE_OK         The system was marked Good
  242  *      - LE_BUSY       Someone holds a probation lock
  243  *      - LE_DUPLICATE  Probation has expired - the system has already been marked
  244  */
  245 //--------------------------------------------------------------------------------------------------
  246 le_result_t le_updateCtrl_MarkGood
  247 (
  248     bool force
  249         ///< [IN] True to set system Good even if someone holds a probation lock
  250 );
  251 
  252 //--------------------------------------------------------------------------------------------------
  253 /**
  254  * Marks the system "bad" and triggers a roll-back to a "good" system.
  255  *
  256  * @note Ignored if the probation period has already ended.  Also, the roll-back may be delayed if
  257  * someone is deferring updates using le_updateCtrl_Defer().
  258  */
  259 //--------------------------------------------------------------------------------------------------
  260 void le_updateCtrl_FailProbation
  261 (
  262     void
  263 );
  264 
  265 //--------------------------------------------------------------------------------------------------
  266 /**
  267  * Get the current system state.
  268  *
  269  * @note Can only be called if updates have been deferred or if a probation lock is held.
  270  * Otherwise the system state could change between the time this function is called and when
  271  * the return value is checked.
  272  */
  273 //--------------------------------------------------------------------------------------------------
  274 le_updateCtrl_SystemState_t le_updateCtrl_GetSystemState
  275 (
  276     void
  277 );
  278 
  279 /** @} **/
  280 
  281 #endif // LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
le_updateCtrl_FailProbation
void le_updateCtrl_FailProbation(void)
le_result_t
le_result_t
Definition: le_basics.h:46
le_updateCtrl_MarkGood
le_result_t le_updateCtrl_MarkGood(bool force)
le_updateCtrl_LockProbation
bool le_updateCtrl_LockProbation(void)
le_updateCtrl_TryConnectService
le_result_t le_updateCtrl_TryConnectService(void)
le_updateCtrl_ConnectService
void le_updateCtrl_ConnectService(void)
le_updateCtrl_DisconnectHandler_t
void(* le_updateCtrl_DisconnectHandler_t)(void *)
Definition: le_updateCtrl_interface.h:108
le_updateCtrl_Allow
void le_updateCtrl_Allow(void)
le_updateCtrl_DisconnectService
void le_updateCtrl_DisconnectService(void)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_updateCtrl_SetServerDisconnectHandler
LE_FULL_API void le_updateCtrl_SetServerDisconnectHandler(le_updateCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
legato.h
le_updateCtrl_common.h
le_updateCtrl_UnlockProbation
void le_updateCtrl_UnlockProbation(void)
le_updateCtrl_Defer
void le_updateCtrl_Defer(void)
le_updateCtrl_SystemState_t
le_updateCtrl_SystemState_t
Definition: le_updateCtrl_common.h:33
le_updateCtrl_GetSystemState
le_updateCtrl_SystemState_t le_updateCtrl_GetSystemState(void)