le_updateCtrl_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_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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
175 (
176  void
177 );
178 
179 
180 //--------------------------------------------------------------------------------------------------
181 /**
182  * State of the system.
183  */
184 //--------------------------------------------------------------------------------------------------
185 typedef enum
186 {
188  ///< "good"
190  ///< "bad"
192  ///< "tried N" or untried.
193 }
195 
196 
197 //--------------------------------------------------------------------------------------------------
198 /**
199  * Prevent all updates (and roll-backs) until further notice.
200  */
201 //--------------------------------------------------------------------------------------------------
203 (
204  void
205 );
206 
207 //--------------------------------------------------------------------------------------------------
208 /**
209  * Allow updates to go ahead.
210  */
211 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
280 (
281  void
282 );
283 
284 #endif // LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
"bad"
Definition: le_updateCtrl_interface.h:189
void le_updateCtrl_FailProbation(void)
"good"
Definition: le_updateCtrl_interface.h:187
le_result_t
Definition: le_basics.h:35
void le_updateCtrl_DisconnectService(void)
bool le_updateCtrl_LockProbation(void)
void le_updateCtrl_SetServerDisconnectHandler(le_updateCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_updateCtrl_ConnectService(void)
le_updateCtrl_SystemState_t
Definition: le_updateCtrl_interface.h:185
void le_updateCtrl_UnlockProbation(void)
le_result_t le_updateCtrl_TryConnectService(void)
void le_updateCtrl_Defer(void)
void(* le_updateCtrl_DisconnectHandler_t)(void *)
Definition: le_updateCtrl_interface.h:103
le_result_t le_updateCtrl_MarkGood(bool force)
le_updateCtrl_SystemState_t le_updateCtrl_GetSystemState(void)
void le_updateCtrl_Allow(void)
"tried N" or untried.
Definition: le_updateCtrl_interface.h:191