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 // Internal includes for this interface
98 #include "le_updateCtrl_common.h"
99 //--------------------------------------------------------------------------------------------------
100 /**
101  * Type for handler called when a server disconnects.
102  */
103 //--------------------------------------------------------------------------------------------------
104 typedef void (*le_updateCtrl_DisconnectHandler_t)(void *);
105 
106 //--------------------------------------------------------------------------------------------------
107 /**
108  *
109  * Connect the current client thread to the service providing this API. Block until the service is
110  * available.
111  *
112  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
113  * called before any other functions in this API. Normally, ConnectService is automatically called
114  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
115  *
116  * This function is created automatically.
117  */
118 //--------------------------------------------------------------------------------------------------
120 (
121  void
122 );
123 
124 //--------------------------------------------------------------------------------------------------
125 /**
126  *
127  * Try to connect the current client thread to the service providing this API. Return with an error
128  * if the service is not available.
129  *
130  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
131  * called before any other functions in this API. Normally, ConnectService is automatically called
132  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
133  *
134  * This function is created automatically.
135  *
136  * @return
137  * - LE_OK if the client connected successfully to the service.
138  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
139  * bound.
140  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
141  * - LE_COMM_ERROR if the Service Directory cannot be reached.
142  */
143 //--------------------------------------------------------------------------------------------------
145 (
146  void
147 );
148 
149 //--------------------------------------------------------------------------------------------------
150 /**
151  * Set handler called when server disconnection is detected.
152  *
153  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
154  * to continue without exiting, it should call longjmp() from inside the handler.
155  */
156 //--------------------------------------------------------------------------------------------------
158 (
159  le_updateCtrl_DisconnectHandler_t disconnectHandler,
160  void *contextPtr
161 );
162 
163 //--------------------------------------------------------------------------------------------------
164 /**
165  *
166  * Disconnect the current client thread from the service providing this API.
167  *
168  * Normally, this function doesn't need to be called. After this function is called, there's no
169  * longer a connection to the service, and the functions in this API can't be used. For details, see
170  * @ref apiFilesC_client.
171  *
172  * This function is created automatically.
173  */
174 //--------------------------------------------------------------------------------------------------
176 (
177  void
178 );
179 
180 
181 //--------------------------------------------------------------------------------------------------
182 /**
183  * State of the system.
184  */
185 //--------------------------------------------------------------------------------------------------
186 
187 
188 //--------------------------------------------------------------------------------------------------
189 /**
190  * Prevent all updates (and roll-backs) until further notice.
191  */
192 //--------------------------------------------------------------------------------------------------
194 (
195  void
196 );
197 
198 //--------------------------------------------------------------------------------------------------
199 /**
200  * Allow updates to go ahead.
201  */
202 //--------------------------------------------------------------------------------------------------
204 (
205  void
206 );
207 
208 //--------------------------------------------------------------------------------------------------
209 /**
210  * Prevent the probation period from ending.
211  *
212  * @return false if lock failed (for example if not in a probation period).
213  */
214 //--------------------------------------------------------------------------------------------------
216 (
217  void
218 );
219 
220 //--------------------------------------------------------------------------------------------------
221 /**
222  * Cancels a call to LockProbation(), allow the probation period to end.
223  *
224  * @note Must match previous successful call to LockProbation().
225  */
226 //--------------------------------------------------------------------------------------------------
228 (
229  void
230 );
231 
232 //--------------------------------------------------------------------------------------------------
233 /**
234  * Marks the system "good", ending the probation period.
235  *
236  * @return
237  * - LE_OK The system was marked Good
238  * - LE_BUSY Someone holds a probation lock
239  * - LE_DUPLICATE Probation has expired - the system has already been marked
240  */
241 //--------------------------------------------------------------------------------------------------
243 (
244  bool force
245  ///< [IN] True to set system Good even if someone holds a probation lock
246 );
247 
248 //--------------------------------------------------------------------------------------------------
249 /**
250  * Marks the system "bad" and triggers a roll-back to a "good" system.
251  *
252  * @note Ignored if the probation period has already ended. Also, the roll-back may be delayed if
253  * someone is deferring updates using le_updateCtrl_Defer().
254  */
255 //--------------------------------------------------------------------------------------------------
257 (
258  void
259 );
260 
261 //--------------------------------------------------------------------------------------------------
262 /**
263  * Get the current system state.
264  *
265  * @note Can only be called if updates have been deferred or if a probation lock is held.
266  * Otherwise the system state could change between the time this function is called and when
267  * the return value is checked.
268  */
269 //--------------------------------------------------------------------------------------------------
270 le_updateCtrl_SystemState_t le_updateCtrl_GetSystemState
271 (
272  void
273 );
274 
275 #endif // LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
LE_FULL_API void le_updateCtrl_SetServerDisconnectHandler(le_updateCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_updateCtrl_Allow(void)
void le_updateCtrl_Defer(void)
le_result_t
Definition: le_basics.h:35
le_updateCtrl_SystemState_t le_updateCtrl_GetSystemState(void)
le_result_t le_updateCtrl_TryConnectService(void)
le_result_t le_updateCtrl_MarkGood(bool force)
bool le_updateCtrl_LockProbation(void)
void(* le_updateCtrl_DisconnectHandler_t)(void *)
Definition: le_updateCtrl_interface.h:104
void le_updateCtrl_DisconnectService(void)
#define LE_FULL_API
Definition: le_basics.h:288
void le_updateCtrl_ConnectService(void)
void le_updateCtrl_UnlockProbation(void)
void le_updateCtrl_FailProbation(void)