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 
   98 //--------------------------------------------------------------------------------------------------
   99 /**
  100  * Type for handler called when a server disconnects.
  101  */
  102 //--------------------------------------------------------------------------------------------------
  103 typedef void (*le_updateCtrl_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_updateCtrl_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_updateCtrl_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 void le_updateCtrl_SetServerDisconnectHandler
  157 (
  158     le_updateCtrl_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_updateCtrl_DisconnectService
  175 (
  176     void
  177 );
  178 
  179 
  180 //--------------------------------------------------------------------------------------------------
  181 /**
  182  * State of the system.
  183  */
  184 //--------------------------------------------------------------------------------------------------
  185 typedef enum
  186 {
  187     LE_UPDATECTRL_SYSTEMSTATE_GOOD = 0,
  188         ///< "good"
  189     LE_UPDATECTRL_SYSTEMSTATE_BAD = 1,
  190         ///< "bad"
  191     LE_UPDATECTRL_SYSTEMSTATE_PROBATION = 2
  192         ///< "tried N" or untried.
  193 }
  194 le_updateCtrl_SystemState_t;
  195 
  196 
  197 //--------------------------------------------------------------------------------------------------
  198 /**
  199  * Prevent all updates (and roll-backs) until further notice.
  200  */
  201 //--------------------------------------------------------------------------------------------------
  202 void le_updateCtrl_Defer
  203 (
  204     void
  205 );
  206 
  207 //--------------------------------------------------------------------------------------------------
  208 /**
  209  * Allow updates to go ahead.
  210  */
  211 //--------------------------------------------------------------------------------------------------
  212 void le_updateCtrl_Allow
  213 (
  214     void
  215 );
  216 
  217 //--------------------------------------------------------------------------------------------------
  218 /**
  219  * Prevent the probation period from ending.
  220  *
  221  * @return false if lock failed (for example if not in a probation period).
  222  */
  223 //--------------------------------------------------------------------------------------------------
  224 bool le_updateCtrl_LockProbation
  225 (
  226     void
  227 );
  228 
  229 //--------------------------------------------------------------------------------------------------
  230 /**
  231  * Cancels a call to LockProbation(), allow the probation period to end.
  232  *
  233  * @note Must match previous successful call to LockProbation().
  234  */
  235 //--------------------------------------------------------------------------------------------------
  236 void le_updateCtrl_UnlockProbation
  237 (
  238     void
  239 );
  240 
  241 //--------------------------------------------------------------------------------------------------
  242 /**
  243  * Marks the system "good", ending the probation period.
  244  *
  245  * @return
  246  *      - LE_OK         The system was marked Good
  247  *      - LE_BUSY       Someone holds a probation lock
  248  *      - LE_DUPLICATE  Probation has expired - the system has already been marked
  249  */
  250 //--------------------------------------------------------------------------------------------------
  251 le_result_t le_updateCtrl_MarkGood
  252 (
  253     bool force
  254         ///< [IN] True to set system Good even if someone holds a probation lock
  255 );
  256 
  257 //--------------------------------------------------------------------------------------------------
  258 /**
  259  * Marks the system "bad" and triggers a roll-back to a "good" system.
  260  *
  261  * @note Ignored if the probation period has already ended.  Also, the roll-back may be delayed if
  262  * someone is deferring updates using le_updateCtrl_Defer().
  263  */
  264 //--------------------------------------------------------------------------------------------------
  265 void le_updateCtrl_FailProbation
  266 (
  267     void
  268 );
  269 
  270 //--------------------------------------------------------------------------------------------------
  271 /**
  272  * Get the current system state.
  273  *
  274  * @note Can only be called if updates have been deferred or if a probation lock is held.
  275  * Otherwise the system state could change between the time this function is called and when
  276  * the return value is checked.
  277  */
  278 //--------------------------------------------------------------------------------------------------
  279 le_updateCtrl_SystemState_t le_updateCtrl_GetSystemState
  280 (
  281     void
  282 );
  283 
  284 #endif // LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
le_updateCtrl_Allow
void le_updateCtrl_Allow(void)
le_updateCtrl_Defer
void le_updateCtrl_Defer(void)
le_result_t
le_result_t
Definition: le_basics.h:35
le_updateCtrl_GetSystemState
le_updateCtrl_SystemState_t le_updateCtrl_GetSystemState(void)
le_updateCtrl_TryConnectService
le_result_t le_updateCtrl_TryConnectService(void)
le_updateCtrl_SystemState_t
le_updateCtrl_SystemState_t
Definition: le_updateCtrl_interface.h:185
le_updateCtrl_SetServerDisconnectHandler
void le_updateCtrl_SetServerDisconnectHandler(le_updateCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
LE_UPDATECTRL_SYSTEMSTATE_GOOD
"good" 
Definition: le_updateCtrl_interface.h:187
le_updateCtrl_MarkGood
le_result_t le_updateCtrl_MarkGood(bool force)
LE_UPDATECTRL_SYSTEMSTATE_BAD
"bad" 
Definition: le_updateCtrl_interface.h:189
le_updateCtrl_LockProbation
bool le_updateCtrl_LockProbation(void)
legato.h
le_updateCtrl_DisconnectHandler_t
void(* le_updateCtrl_DisconnectHandler_t)(void *)
Definition: le_updateCtrl_interface.h:103
le_updateCtrl_DisconnectService
void le_updateCtrl_DisconnectService(void)
le_updateCtrl_ConnectService
void le_updateCtrl_ConnectService(void)
LE_UPDATECTRL_SYSTEMSTATE_PROBATION
"tried N" or untried. 
Definition: le_updateCtrl_interface.h:191
le_updateCtrl_UnlockProbation
void le_updateCtrl_UnlockProbation(void)
le_updateCtrl_FailProbation
void le_updateCtrl_FailProbation(void)