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 //--------------------------------------------------------------------------------------------------
100 /**
101  * Type for handler called when a server disconnects.
102  */
103 //--------------------------------------------------------------------------------------------------
104 typedef void (*le_fwupdate_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_fwupdate_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  * Update status
184  * Indicates either a success or the defective image partition.
185  */
186 //--------------------------------------------------------------------------------------------------
187 
188 
189 //--------------------------------------------------------------------------------------------------
190 /**
191  * Download the firmware image file. The function can also be used to resume the download if the
192  * le_fwupdate_InitDownload() function is not called before.
193  *
194  * @return
195  * - LE_OK On success
196  * - LE_BAD_PARAMETER If an input parameter is not valid
197  * - LE_TIMEOUT After 900 seconds without data received
198  * - LE_NOT_POSSIBLE The systems are not synced
199  * - LE_UNAVAILABLE The flash access is not granted for SW update
200  * - LE_CLOSED File descriptor has been closed before all data have been received
201  * - LE_OUT_OF_RANGE Storage is too small
202  * - LE_FAULT On failure
203  *
204  * @note
205  * The process exits, if an invalid file descriptor (e.g. negative) is given.
206  */
207 //--------------------------------------------------------------------------------------------------
209 (
210  int fd
211  ///< [IN] File descriptor of the image, opened to the start of the image.
212 );
213 
214 //--------------------------------------------------------------------------------------------------
215 /**
216  * Download initialization:
217  * - for single and dual systems, it resets resume position,
218  * - for dual systems, it synchronizes the systems if needed.
219  *
220  * @note
221  * When invoked, resuming a previous download is not possible, a full update package has to be
222  * downloaded.
223  *
224  * @return
225  * - LE_OK On success
226  * - LE_FAULT On failure
227  * - LE_IO_ERROR Dual systems platforms only -- The synchronization fails due to
228  * unrecoverable ECC errors. In this case, the update without synchronization
229  * is forced, but the whole system must be updated to ensure that the new
230  * update system will be workable
231  * ECC stands for Error-Correction-Code: some errors may be corrected. If this
232  * correction fails, a unrecoverable error is registered and the data become
233  * corrupted.
234  * - LE_NO_MEMORY On memory allocation failure
235  */
236 //--------------------------------------------------------------------------------------------------
238 (
239  void
240 );
241 
242 //--------------------------------------------------------------------------------------------------
243 /**
244  * Return the downloaded update package write position.
245  *
246  * @return
247  * - LE_OK On success
248  * - LE_BAD_PARAMETER The given parameter is invalid.
249  * - LE_FAULT On failure
250  */
251 //--------------------------------------------------------------------------------------------------
253 (
254  size_t* positionPtr
255  ///< [OUT] Update package read position
256 );
257 
258 //--------------------------------------------------------------------------------------------------
259 /**
260  * Return the update status.
261  *
262  * @return
263  * - LE_OK on success
264  * - LE_BAD_PARAMETER Invalid parameter
265  * - LE_FAULT on failure
266  */
267 //--------------------------------------------------------------------------------------------------
269 (
270  le_fwupdate_UpdateStatus_t* statusPtr,
271  ///< [OUT] Returned update status
272  char* statusLabel,
273  ///< [OUT] Description of the status
274  size_t statusLabelSize
275  ///< [IN]
276 );
277 
278 //--------------------------------------------------------------------------------------------------
279 /**
280  * Get the firmware version string
281  *
282  * @return
283  * - LE_OK on success
284  * - LE_NOT_FOUND if the version string is not available
285  * - LE_OVERFLOW if version string to big to fit in provided buffer
286  * - LE_FAULT for any other errors
287  *
288  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
289  * function will not return.
290  */
291 //--------------------------------------------------------------------------------------------------
293 (
294  char* version,
295  ///< [OUT] Firmware version string
296  size_t versionSize
297  ///< [IN]
298 );
299 
300 //--------------------------------------------------------------------------------------------------
301 /**
302  * Get the bootloader version string
303  *
304  * @return
305  * - LE_OK on success
306  * - LE_NOT_FOUND if the version string is not available
307  * - LE_OVERFLOW if version string to big to fit in provided buffer
308  * - LE_FAULT for any other errors
309  *
310  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
311  * function will not return.
312  */
313 //--------------------------------------------------------------------------------------------------
315 (
316  char* version,
317  ///< [OUT] Bootloader version string
318  size_t versionSize
319  ///< [IN]
320 );
321 
322 //--------------------------------------------------------------------------------------------------
323 /**
324  * Get the app bootloader version string
325  *
326  * @return
327  * - LE_OK on success
328  * - LE_NOT_FOUND if the version string is not available
329  * - LE_OVERFLOW if version string to big to fit in provided buffer
330  * - LE_BAD_PARAMETER bad parameter
331  * - LE_UNSUPPORTED not supported
332  * - LE_FAULT for any other errors
333  *
334  * @note If the caller passes in a bad pointer, it is a fatal error and the function won't return.
335  */
336 //--------------------------------------------------------------------------------------------------
338 (
339  char* version,
340  ///< [OUT] Bootloader version string
341  size_t versionSize
342  ///< [IN]
343 );
344 
345 //--------------------------------------------------------------------------------------------------
346 /**
347  * Get the status of the system.
348  *
349  * Dual System: Indicates if Active and Update systems are synchronized
350  * Single System: This api is not supported on single system.
351  *
352  * @return
353  * - LE_OK On success
354  * - LE_UNSUPPORTED The feature is not supported
355  */
356 //--------------------------------------------------------------------------------------------------
358 (
359  bool* isSystemGoodPtr
360  ///< [OUT] true if the system is marked good, false otherwise
361 );
362 
363 //--------------------------------------------------------------------------------------------------
364 /**
365  * Request to install the package. Calling this API will result in a system reset.
366  *
367  * Dual System: After reset, the UPDATE and ACTIVE systems will be swapped.
368  * Single System: After reset, the image in the FOTA partition will be installed on the device.
369  *
370  * @note On success, a device reboot is initiated without returning any value.
371  *
372  *
373  * @return
374  * - LE_BUSY Download is ongoing, install is not allowed
375  * - LE_UNSUPPORTED The feature is not supported
376  * - LE_FAULT On failure
377  *
378  */
379 //--------------------------------------------------------------------------------------------------
381 (
382  void
383 );
384 
385 //--------------------------------------------------------------------------------------------------
386 /**
387  * Mark the current system as good.
388  *
389  * Dual System: Requests a system Sync. The UPDATE system will be synchronised with the ACTIVE one.
390  * Single System: This api is not supported on single system.
391  *
392  * @return
393  * - LE_OK On success
394  * - LE_UNSUPPORTED The feature is not supported
395  * - LE_UNAVAILABLE The flash access is not granted for SW update
396  * - LE_FAULT On failure
397  * - LE_IO_ERROR Dual systems platforms only -- The synchronization fails due to
398  * unrecoverable ECC errors
399  * ECC stands for Error-Correction-Code: some errors may be corrected. If
400  * this correction fails, an unrecoverable error is registered and the data
401  * become corrupted.
402  *
403  */
404 //--------------------------------------------------------------------------------------------------
406 (
407  void
408 );
409 
410 //--------------------------------------------------------------------------------------------------
411 /**
412  * Request to install the package and marks the system as good. Calling this API will result in a
413  * system reset.
414  *
415  * Dual System: Request a full system reset with a systems SWAP and systems SYNC. After the reset,
416  * the UPDATE and ACTIVE systems will be swapped and synchronized.
417  * Single System: Installs the package from the FOTA partition.
418  *
419  *
420  * @note On success, a device reboot is initiated without returning any value.
421  *
422  * @return
423  * - LE_FAULT On failure
424  *
425  */
426 //--------------------------------------------------------------------------------------------------
428 (
429  void
430 );
431 
432 #endif // LE_FWUPDATE_INTERFACE_H_INCLUDE_GUARD
le_result_t le_fwupdate_GetBootloaderVersion(char *version, size_t versionSize)
le_result_t le_fwupdate_GetResumePosition(size_t *positionPtr)
void le_fwupdate_ConnectService(void)
le_result_t
Definition: le_basics.h:35
LE_FULL_API void le_fwupdate_SetServerDisconnectHandler(le_fwupdate_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_fwupdate_Download(int fd)
le_result_t le_fwupdate_TryConnectService(void)
le_result_t le_fwupdate_MarkGood(void)
le_result_t le_fwupdate_IsSystemMarkedGood(bool *isSystemGoodPtr)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_fwupdate_InitDownload(void)
le_result_t le_fwupdate_GetFirmwareVersion(char *version, size_t versionSize)
void(* le_fwupdate_DisconnectHandler_t)(void *)
Definition: le_fwupdate_interface.h:104
le_result_t le_fwupdate_GetAppBootloaderVersion(char *version, size_t versionSize)
void le_fwupdate_DisconnectService(void)
le_result_t le_fwupdate_Install(void)
le_result_t le_fwupdate_InstallAndMarkGood(void)
le_result_t le_fwupdate_GetUpdateStatus(le_fwupdate_UpdateStatus_t *statusPtr, char *statusLabel, size_t statusLabelSize)