le_fwupdate_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_fwupdate Firmware Update API
14  *
15  * @ref le_fwupdate_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * Firmware update allows the various firmware images to be updated from the application processor.
20  * This may include the modem bootloader, modem firmware, and linux image, where the linux image
21  * consists of the linux bootloader, linux kernel, and linux rootfs.
22  *
23  * Firmware update is useful when the image comes from an alternative source, rather than as an
24  * over-the-air update through the AirVantage service.
25  *
26  * @section le_fwupdate_binding IPC interfaces binding
27  *
28  * All the functions of this API are provided by the @b le_fwupdate service.
29  *
30  * Here's a code sample binding to the le_fwupdate service:
31  * @verbatim
32  bindings:
33  {
34  clientExe.clientComponent.le_fwupdate -> fwupdateService.le_fwupdate
35  }
36  @endverbatim
37  *
38  *
39  * @warning All of these APIs are not available for all platforms. Please refer to the
40  * Product Technical specification document of your platform for further details.
41  * Please refer to @subpage platformConstraintsDualSys for details on Dual System.
42  *
43  * @section le_fwupdate_image Update Firmware Image
44  *
45  * The firmware update process is started by calling le_fwupdate_Download(). This function takes
46  * a file descriptor, rather than a file, to provide flexibility in the source of the image. In
47  * particular, this can be used to stream the image, rather than having to save it on the file
48  * system before doing the update.
49  *
50  * On platform which does not support dual system, when the image is successfully downloaded, a
51  * reset will occur in order to apply the update. This will reset all processors. After the
52  * application processor has restarted, the @ref le_info_version APIs can be used to determine
53  * whether the firmware has been updated to the new version.
54  *
55  * On platform which supports dual system, if the image is successfully downloaded, the user needs
56  * to swap the systems in order to use the updated system. This will reset all processors. After the
57  * application processor has restarted, the @ref le_info_version APIs can be used to determine
58  * whether the firmware has been updated to the new version.
59  *
60  * @section le_fwupdate_resume Update Firmware Image Download Resume
61  *
62  * During the download, the flash programming position is saved. Thanks to this position, fwupdate
63  * service is able to resume the download without downloading the update package at the beginning.
64  *
65  * By default, the fwupdate service download API is resuming the previous download: new data
66  * received through this API will be programmed at the resume position.
67  *
68  * @note
69  * A download can be resumed when:
70  * - le_fwupdate_Download() API has previously returned LE_CLOSED or LE_TIMEOUT
71  * - A reset occured during last le_fwupdate_Download() processing (Legato/full system reset)
72  * - No resume can be performed in other cases.
73  *
74  * A complete download can be forced by calling le_fwupdate_InitDownload(). Resume position
75  * is set to 0.
76  *
77  * The current resume position can be retrieved by calling le_fwupdate_GetResumePosition().
78  *
79  * <HR>
80  *
81  * Copyright (C) Sierra Wireless Inc.
82  */
83 /**
84  * @file le_fwupdate_interface.h
85  *
86  * Legato @ref c_fwupdate include file.
87  *
88  * Copyright (C) Sierra Wireless Inc.
89  */
90 
91 #ifndef LE_FWUPDATE_INTERFACE_H_INCLUDE_GUARD
92 #define LE_FWUPDATE_INTERFACE_H_INCLUDE_GUARD
93 
94 
95 #include "legato.h"
96 
97 // Internal includes for this interface
98 #include "le_fwupdate_common.h"
99 /** @addtogroup le_fwupdate le_fwupdate API Reference
100  * @{
101  * @file le_fwupdate_common.h
102  * @file le_fwupdate_interface.h **/
103 //--------------------------------------------------------------------------------------------------
104 /**
105  * Type for handler called when a server disconnects.
106  */
107 //--------------------------------------------------------------------------------------------------
108 typedef void (*le_fwupdate_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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
162 (
163  le_fwupdate_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 //--------------------------------------------------------------------------------------------------
180 (
181  void
182 );
183 
184 
185 //--------------------------------------------------------------------------------------------------
186 /**
187  * Update status
188  * Indicates either a success or the defective image partition.
189  */
190 //--------------------------------------------------------------------------------------------------
191 
192 
193 //--------------------------------------------------------------------------------------------------
194 /**
195  * Download the firmware image file. The function can also be used to resume the download if the
196  * le_fwupdate_InitDownload() function is not called before.
197  *
198  * @return
199  * - LE_OK On success
200  * - LE_BAD_PARAMETER If an input parameter is not valid
201  * - LE_TIMEOUT After 900 seconds without data received
202  * - LE_NOT_PERMITTED The systems are not synced
203  * - LE_UNAVAILABLE The flash access is not granted for SW update
204  * - LE_CLOSED File descriptor has been closed before all data have been received
205  * - LE_OUT_OF_RANGE Storage is too small
206  * - LE_FAULT On failure
207  *
208  * @note
209  * The process exits, if an invalid file descriptor (e.g. negative) is given.
210  */
211 //--------------------------------------------------------------------------------------------------
213 (
214  int fd
215  ///< [IN] File descriptor of the image, opened to the start of the image.
216 );
217 
218 //--------------------------------------------------------------------------------------------------
219 /**
220  * Download initialization:
221  * - for single and dual systems, it resets resume position,
222  * - for dual systems, it synchronizes the systems if needed.
223  *
224  * @note
225  * When invoked, resuming a previous download is not possible, a full update package has to be
226  * downloaded.
227  *
228  * @return
229  * - LE_OK On success
230  * - LE_FAULT On failure
231  * - LE_IO_ERROR Dual systems platforms only -- The synchronization fails due to
232  * unrecoverable ECC errors. In this case, the update without synchronization
233  * is forced, but the whole system must be updated to ensure that the new
234  * update system will be workable
235  * ECC stands for Error-Correction-Code: some errors may be corrected. If this
236  * correction fails, a unrecoverable error is registered and the data become
237  * corrupted.
238  * - LE_NO_MEMORY On memory allocation failure
239  */
240 //--------------------------------------------------------------------------------------------------
242 (
243  void
244 );
245 
246 //--------------------------------------------------------------------------------------------------
247 /**
248  * Return the downloaded update package write position.
249  *
250  * @return
251  * - LE_OK On success
252  * - LE_BAD_PARAMETER The given parameter is invalid.
253  * - LE_FAULT On failure
254  */
255 //--------------------------------------------------------------------------------------------------
257 (
258  size_t* positionPtr
259  ///< [OUT] Update package read position
260 );
261 
262 //--------------------------------------------------------------------------------------------------
263 /**
264  * Return the update status.
265  *
266  * @return
267  * - LE_OK on success
268  * - LE_BAD_PARAMETER Invalid parameter
269  * - LE_FAULT on failure
270  */
271 //--------------------------------------------------------------------------------------------------
273 (
274  le_fwupdate_UpdateStatus_t* statusPtr,
275  ///< [OUT] Returned update status
276  char* statusLabel,
277  ///< [OUT] Description of the status
278  size_t statusLabelSize
279  ///< [IN]
280 );
281 
282 //--------------------------------------------------------------------------------------------------
283 /**
284  * Get the firmware version string
285  *
286  * @return
287  * - LE_OK on success
288  * - LE_NOT_FOUND if the version string is not available
289  * - LE_OVERFLOW if version string to big to fit in provided buffer
290  * - LE_FAULT for any other errors
291  *
292  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
293  * function will not return.
294  */
295 //--------------------------------------------------------------------------------------------------
297 (
298  char* version,
299  ///< [OUT] Firmware version string
300  size_t versionSize
301  ///< [IN]
302 );
303 
304 //--------------------------------------------------------------------------------------------------
305 /**
306  * Get the bootloader version string
307  *
308  * @return
309  * - LE_OK on success
310  * - LE_NOT_FOUND if the version string is not available
311  * - LE_OVERFLOW if version string to big to fit in provided buffer
312  * - LE_FAULT for any other errors
313  *
314  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
315  * function will not return.
316  */
317 //--------------------------------------------------------------------------------------------------
319 (
320  char* version,
321  ///< [OUT] Bootloader version string
322  size_t versionSize
323  ///< [IN]
324 );
325 
326 //--------------------------------------------------------------------------------------------------
327 /**
328  * Get the app bootloader version string
329  *
330  * @return
331  * - LE_OK on success
332  * - LE_NOT_FOUND if the version string is not available
333  * - LE_OVERFLOW if version string to big to fit in provided buffer
334  * - LE_BAD_PARAMETER bad parameter
335  * - LE_UNSUPPORTED not supported
336  * - LE_FAULT for any other errors
337  *
338  * @note If the caller passes in a bad pointer, it is a fatal error and the function won't return.
339  */
340 //--------------------------------------------------------------------------------------------------
342 (
343  char* version,
344  ///< [OUT] Bootloader version string
345  size_t versionSize
346  ///< [IN]
347 );
348 
349 //--------------------------------------------------------------------------------------------------
350 /**
351  * Get the status of the system.
352  *
353  * Dual System: Indicates if Active and Update systems are synchronized
354  * Single System: This api is not supported on single system.
355  *
356  * @return
357  * - LE_OK On success
358  * - LE_UNSUPPORTED The feature is not supported
359  */
360 //--------------------------------------------------------------------------------------------------
362 (
363  bool* isSystemGoodPtr
364  ///< [OUT] true if the system is marked good, false otherwise
365 );
366 
367 //--------------------------------------------------------------------------------------------------
368 /**
369  * Request to install the package. Calling this API will result in a system reset.
370  *
371  * Dual System: After reset, the UPDATE and ACTIVE systems will be swapped.
372  * Single System: After reset, the image in the FOTA partition will be installed on the device.
373  *
374  * @note On success, a device reboot is initiated without returning any value.
375  *
376  *
377  * @return
378  * - LE_BUSY Download is ongoing, install is not allowed
379  * - LE_UNSUPPORTED The feature is not supported
380  * - LE_FAULT On failure
381  *
382  */
383 //--------------------------------------------------------------------------------------------------
385 (
386  void
387 );
388 
389 //--------------------------------------------------------------------------------------------------
390 /**
391  * Mark the current system as good.
392  *
393  * Dual System: Requests a system Sync. The UPDATE system will be synchronised with the ACTIVE one.
394  * Single System: This api is not supported on single system.
395  *
396  * @return
397  * - LE_OK On success
398  * - LE_UNSUPPORTED The feature is not supported
399  * - LE_UNAVAILABLE The flash access is not granted for SW update
400  * - LE_FAULT On failure
401  * - LE_IO_ERROR Dual systems platforms only -- The synchronization fails due to
402  * unrecoverable ECC errors
403  * ECC stands for Error-Correction-Code: some errors may be corrected. If
404  * this correction fails, an unrecoverable error is registered and the data
405  * become corrupted.
406  *
407  */
408 //--------------------------------------------------------------------------------------------------
410 (
411  void
412 );
413 
414 //--------------------------------------------------------------------------------------------------
415 /**
416  * Request to install the package and marks the system as good. Calling this API will result in a
417  * system reset.
418  *
419  * Dual System: Request a full system reset with a systems SWAP and systems SYNC. After the reset,
420  * the UPDATE and ACTIVE systems will be swapped and synchronized.
421  * Single System: Installs the package from the FOTA partition.
422  *
423  *
424  * @note On success, a device reboot is initiated without returning any value.
425  *
426  * @return
427  * - LE_FAULT On failure
428  *
429  */
430 //--------------------------------------------------------------------------------------------------
432 (
433  void
434 );
435 
436 /** @} **/
437 
438 #endif // LE_FWUPDATE_INTERFACE_H_INCLUDE_GUARD
le_result_t le_fwupdate_Download(int fd)
le_result_t
Definition: le_basics.h:46
LE_FULL_API void le_fwupdate_SetServerDisconnectHandler(le_fwupdate_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_fwupdate_InitDownload(void)
le_result_t le_fwupdate_IsSystemMarkedGood(bool *isSystemGoodPtr)
le_fwupdate_UpdateStatus_t
Definition: le_fwupdate_common.h:48
void le_fwupdate_ConnectService(void)
le_result_t le_fwupdate_GetAppBootloaderVersion(char *version, size_t versionSize)
le_result_t le_fwupdate_GetUpdateStatus(le_fwupdate_UpdateStatus_t *statusPtr, char *statusLabel, size_t statusLabelSize)
le_result_t le_fwupdate_Install(void)
le_result_t le_fwupdate_InstallAndMarkGood(void)
void(* le_fwupdate_DisconnectHandler_t)(void *)
Definition: le_fwupdate_interface.h:108
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_fwupdate_GetBootloaderVersion(char *version, size_t versionSize)
le_result_t le_fwupdate_MarkGood(void)
le_result_t le_fwupdate_GetResumePosition(size_t *positionPtr)
le_result_t le_fwupdate_GetFirmwareVersion(char *version, size_t versionSize)
le_result_t le_fwupdate_TryConnectService(void)
void le_fwupdate_DisconnectService(void)