le_updateCtrl_interface.h

Go to the documentation of this file.
1 /*
2  * ====================== WARNING ======================
3  *
4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
5  * DO NOT MODIFY IN ANY WAY.
6  *
7  * ====================== WARNING ======================
8  */
9 
10 /**
11  * @page c_updateCtrl Update Control API
12  *
13  * @ref le_updateCtrl_interface.h "API Reference"
14  *
15  * <HR>
16  *
17  * This API is used by privileged apps to control the software update process. It can be used to:
18  * - prevent updates from happening or
19  * - control the marking of a system update as "good" or "bad".
20  *
21  * Note that this is not part of the Update API (le_update) because the
22  * Update API can be used by less trusted apps to feed signed/encrypted updates to the
23  * Update Daemon, and we may not trust those same apps to have the ability to prevent someone
24  * else from updating or rolling-back the system.
25  *
26  *
27  * @section le_updateCtrl_prevention Preventing Updates During Critical Operations
28  *
29  * To protect against updates during critical periods of operation (such as when performing an
30  * emergency call in response to a vehicle collision), the following functions are provided:
31  *
32  * - le_updateCtrl_Defer() - prevent all updates until further notice.
33  * - le_updateCtrl_Allow() - allow updates to go ahead.
34  *
35  * Updates will not be allowed to go ahead until no clients are deferring updates. So, if client A
36  * and client B both call le_updateCtrl_Defer(), updates will be deferred until both client A and
37  * client B have called le_updateCtrl_Allow().
38  *
39  * le_updateCtrl_Defer() will also prevent rollbacks unless a fault triggers the Supervisor to
40  * restart the framework or reboot the target. See below for more information on rollbacks.
41  *
42  *
43  * @section le_updateCtrl_probation Controlling the Probation Period
44  *
45  * Whenever a new system is started, a probation period begins. If the system stays running for
46  * the entire probation period, the system is marked "good". But, during the probation period,
47  * if an app faults enough times in a short enough period for the Supervisor to give up on trying
48  * to start it, the system update is marked "bad" and the system is rolled-back to the last known
49  * "good" system.
50  *
51  * In some cases, a customer may want to extend the probation period of their new system for a
52  * non-deterministic amount of time, until it has had a chance to perform some action in the
53  * real world (such as successfully "phoning home" at least once).
54  *
55  * To support this, the functions le_updateCtrl_LockProbation() and le_updateCtrl_UnlockProbation()
56  * are provided, where each call to "Lock" must be matched with a call to "Unlock".
57  *
58  * For those who want to mark "good" at some point of their own determination, regardless
59  * of how long the system has been up, le_updateCtrl_MarkGood() is provided.
60  *
61  * And for those who want to mark the system "bad" and trigger a rollback at some point of
62  * their own choosing, le_updateCtrl_FailProbation() is provided.
63  *
64  * Calls to any of the functions that affect the probation period are ignored if the probation
65  * period is already over (if the system is already marked "good"). Once it is "good", it stays
66  * "good".
67  *
68  * If someone tries to update the system while it is still in its probation period, the update
69  * will be refused. To override this, call le_updateCtrl_FailProbation() or
70  * le_updateCtrl_MarkGood() to end the probation period before trying to apply the new
71  * system update.
72  *
73  * @note If a reboot occurs during the probation period, the probation period will start over.
74  * But, if the system reboots more than a few times without reaching the end of its probation
75  * period first, then the system will be rolled-back to the last known "good" system.
76  *
77  * <HR>
78  *
79  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
80  */
81 /**
82  * @file le_updateCtrl_interface.h
83  *
84  * Legato @ref c_updateCtrl include file.
85  *
86  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
87  */
88 
89 #ifndef LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
90 #define LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
91 
92 
93 #include "legato.h"
94 
95 //--------------------------------------------------------------------------------------------------
96 /**
97  *
98  * Connect the current client thread to the service providing this API. Block until the service is
99  * available.
100  *
101  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
102  * called before any other functions in this API. Normally, ConnectService is automatically called
103  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
104  *
105  * This function is created automatically.
106  */
107 //--------------------------------------------------------------------------------------------------
109 (
110  void
111 );
112 
113 //--------------------------------------------------------------------------------------------------
114 /**
115  *
116  * Try to connect the current client thread to the service providing this API. Return with an error
117  * if the service is not available.
118  *
119  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
120  * called before any other functions in this API. Normally, ConnectService is automatically called
121  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
122  *
123  * This function is created automatically.
124  *
125  * @return
126  * - LE_OK if the client connected successfully to the service.
127  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
128  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
129  * - LE_COMM_ERROR if the Service Directory cannot be reached.
130  */
131 //--------------------------------------------------------------------------------------------------
133 (
134  void
135 );
136 
137 //--------------------------------------------------------------------------------------------------
138 /**
139  *
140  * Disconnect the current client thread from the service providing this API.
141  *
142  * Normally, this function doesn't need to be called. After this function is called, there's no
143  * longer a connection to the service, and the functions in this API can't be used. For details, see
144  * @ref apiFilesC_client.
145  *
146  * This function is created automatically.
147  */
148 //--------------------------------------------------------------------------------------------------
150 (
151  void
152 );
153 
154 //--------------------------------------------------------------------------------------------------
155 /**
156  * Prevent all updates (and roll-backs) until further notice.
157  */
158 //--------------------------------------------------------------------------------------------------
160 (
161  void
162 );
163 
164 //--------------------------------------------------------------------------------------------------
165 /**
166  * Allow updates to go ahead.
167  */
168 //--------------------------------------------------------------------------------------------------
170 (
171  void
172 );
173 
174 //--------------------------------------------------------------------------------------------------
175 /**
176  * Prevent the probation period from ending.
177  *
178  * @note Ignored if the probation period has already ended.
179  */
180 //--------------------------------------------------------------------------------------------------
182 (
183  void
184 );
185 
186 //--------------------------------------------------------------------------------------------------
187 /**
188  * Cancels a call to LockProbation(), allow the probation period to end.
189  *
190  * @note Ignored if the probation period has already ended.
191  */
192 //--------------------------------------------------------------------------------------------------
194 (
195  void
196 );
197 
198 //--------------------------------------------------------------------------------------------------
199 /**
200  * Marks the system "good", ending the probation period.
201  *
202  * @return
203  * - LE_OK The system was marked Good
204  * - LE_BUSY Someone holds a probation lock
205  * - LE_DUPLICATE Probation has expired - the system has already been marked
206  */
207 //--------------------------------------------------------------------------------------------------
209 (
210  bool force
211  ///< [IN] True to set system Good even if someone holds a probation lock
212 );
213 
214 //--------------------------------------------------------------------------------------------------
215 /**
216  * Marks the system "bad" and triggers a roll-back to a "good" system.
217  *
218  * @note Ignored if the probation period has already ended. Also, the roll-back may be delayed if
219  * someone is deferring updates using le_updateCtrl_Defer().
220  */
221 //--------------------------------------------------------------------------------------------------
223 (
224  void
225 );
226 
227 
228 #endif // LE_UPDATECTRL_INTERFACE_H_INCLUDE_GUARD
229 
void le_updateCtrl_FailProbation(void)
le_result_t
Definition: le_basics.h:35
void le_updateCtrl_DisconnectService(void)
void le_updateCtrl_ConnectService(void)
void le_updateCtrl_UnlockProbation(void)
le_result_t le_updateCtrl_TryConnectService(void)
void le_updateCtrl_Defer(void)
le_result_t le_updateCtrl_MarkGood(bool force)
void le_updateCtrl_LockProbation(void)
void le_updateCtrl_Allow(void)