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 Modem Firmware Update
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 
98 //--------------------------------------------------------------------------------------------------
99 /**
100  * Type for handler called when a server disconnects.
101  */
102 //--------------------------------------------------------------------------------------------------
103 typedef void (*le_fwupdate_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_fwupdate_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  * Maximum length of a version string, excluding any termination character.
183  */
184 //--------------------------------------------------------------------------------------------------
185 #define LE_FWUPDATE_MAX_VERS_LEN 256
186 
187 //--------------------------------------------------------------------------------------------------
188 /**
189  * Maximum length of the update status label
190  */
191 //--------------------------------------------------------------------------------------------------
192 #define LE_FWUPDATE_STATUS_LABEL_LENGTH_MAX 32
193 
194 //--------------------------------------------------------------------------------------------------
195 /**
196  * Update status
197  * Indicates either a success or the defective image partition.
198  */
199 //--------------------------------------------------------------------------------------------------
200 typedef enum
201 {
203  ///< Last update succeeded
205  ///< At least, a partition is corrupted
207  ///< Downloading in progress
209  ///< Last downloading failed
211  ///< Last downloading ended with timeout
213  ///< Unknown status. It has to be the last one.
214 }
216 
217 
218 //--------------------------------------------------------------------------------------------------
219 /**
220  * Download the firmware image file. The function can also be used to resume the download if the
221  * le_fwupdate_InitDownload() function is not called before.
222  *
223  * @return
224  * - LE_OK On success
225  * - LE_BAD_PARAMETER If an input parameter is not valid
226  * - LE_TIMEOUT After 900 seconds without data received
227  * - LE_NOT_POSSIBLE The systems are not synced
228  * - LE_UNAVAILABLE The flash access is not granted for SW update
229  * - LE_CLOSED File descriptor has been closed before all data have been received
230  * - LE_FAULT On failure
231  *
232  * @note
233  * The process exits, if an invalid file descriptor (e.g. negative) is given.
234  */
235 //--------------------------------------------------------------------------------------------------
237 (
238  int fd
239  ///< [IN] File descriptor of the image, opened to the start of the image.
240 );
241 
242 //--------------------------------------------------------------------------------------------------
243 /**
244  * Download initialization:
245  * - for single and dual systems, it resets resume position,
246  * - for dual systems, it synchronizes the systems if needed.
247  *
248  * @note
249  * When invoked, resuming a previous download is not possible, a full update package has to be
250  * downloaded.
251  *
252  * @return
253  * - LE_OK On success
254  * - LE_FAULT On failure
255  * - LE_IO_ERROR Dual systems platforms only -- The synchronization fails due to
256  * unrecoverable ECC errors. In this case, the update without synchronization
257  * is forced, but the whole system must be updated to ensure that the new
258  * update system will be workable
259  * ECC stands for Error-Correction-Code: some errors may be corrected. If this
260  * correction fails, a unrecoverable error is registered and the data become
261  * corrupted.
262  */
263 //--------------------------------------------------------------------------------------------------
265 (
266  void
267 );
268 
269 //--------------------------------------------------------------------------------------------------
270 /**
271  * Return the downloaded update package write position.
272  *
273  * @return
274  * - LE_OK On success
275  * - LE_BAD_PARAMETER The given parameter is invalid.
276  * - LE_FAULT On failure
277  */
278 //--------------------------------------------------------------------------------------------------
280 (
281  size_t* positionPtr
282  ///< [OUT] Update package read position
283 );
284 
285 //--------------------------------------------------------------------------------------------------
286 /**
287  * Return the update status.
288  *
289  * @return
290  * - LE_OK on success
291  * - LE_BAD_PARAMETER Invalid parameter
292  * - LE_FAULT on failure
293  */
294 //--------------------------------------------------------------------------------------------------
296 (
297  le_fwupdate_UpdateStatus_t* statusPtr,
298  ///< [OUT] Returned update status
299  char* statusLabel,
300  ///< [OUT] Description of the status
301  size_t statusLabelSize
302  ///< [IN]
303 );
304 
305 //--------------------------------------------------------------------------------------------------
306 /**
307  * Get the firmware version string
308  *
309  * @return
310  * - LE_OK on success
311  * - LE_NOT_FOUND if the version string is not available
312  * - LE_OVERFLOW if version string to big to fit in provided buffer
313  * - LE_FAULT for any other errors
314  *
315  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
316  * function will not return.
317  */
318 //--------------------------------------------------------------------------------------------------
320 (
321  char* version,
322  ///< [OUT] Firmware version string
323  size_t versionSize
324  ///< [IN]
325 );
326 
327 //--------------------------------------------------------------------------------------------------
328 /**
329  * Get the bootloader version string
330  *
331  * @return
332  * - LE_OK on success
333  * - LE_NOT_FOUND if the version string is not available
334  * - LE_OVERFLOW if version string to big to fit in provided buffer
335  * - LE_FAULT for any other errors
336  *
337  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
338  * function will not 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 #endif // LE_FWUPDATE_INTERFACE_H_INCLUDE_GUARD
At least, a partition is corrupted.
Definition: le_fwupdate_interface.h:204
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
void le_fwupdate_SetServerDisconnectHandler(le_fwupdate_DisconnectHandler_t disconnectHandler, void *contextPtr)
Last downloading failed.
Definition: le_fwupdate_interface.h:208
Last downloading ended with timeout.
Definition: le_fwupdate_interface.h:210
le_result_t le_fwupdate_Download(int fd)
Unknown status. It has to be the last one.
Definition: le_fwupdate_interface.h:212
le_result_t le_fwupdate_TryConnectService(void)
Last update succeeded.
Definition: le_fwupdate_interface.h:202
le_result_t le_fwupdate_MarkGood(void)
le_result_t le_fwupdate_IsSystemMarkedGood(bool *isSystemGoodPtr)
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:103
void le_fwupdate_DisconnectService(void)
Downloading in progress.
Definition: le_fwupdate_interface.h:206
le_fwupdate_UpdateStatus_t
Definition: le_fwupdate_interface.h:200
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)