#include "legato.h"

Macros
#define	LE_FWUPDATE_MAX_VERS_LEN 256

#define	LE_FWUPDATE_STATUS_LABEL_LENGTH_MAX 32

Typedefs
typedef void(*	le_fwupdate_DisconnectHandler_t) (void *)

Enumerations
enum	le_fwupdate_UpdateStatus_t { LE_FWUPDATE_UPDATE_STATUS_OK = 0, LE_FWUPDATE_UPDATE_STATUS_PARTITION_ERROR = 1, LE_FWUPDATE_UPDATE_STATUS_DWL_ONGOING = 2, LE_FWUPDATE_UPDATE_STATUS_DWL_FAILED = 3, LE_FWUPDATE_UPDATE_STATUS_DWL_TIMEOUT = 4, LE_FWUPDATE_UPDATE_STATUS_UNKNOWN = 5 }

Functions
void	le_fwupdate_ConnectService (void)

le_result_t	le_fwupdate_TryConnectService (void)

void	le_fwupdate_SetServerDisconnectHandler (le_fwupdate_DisconnectHandler_t disconnectHandler, void *contextPtr)

void	le_fwupdate_DisconnectService (void)

le_result_t	le_fwupdate_Download (int fd)

le_result_t	le_fwupdate_InitDownload (void)

le_result_t	le_fwupdate_GetResumePosition (size_t *positionPtr)

le_result_t	le_fwupdate_GetUpdateStatus (le_fwupdate_UpdateStatus_t statusPtr, char statusLabel, size_t statusLabelSize)

le_result_t	le_fwupdate_GetFirmwareVersion (char *version, size_t versionSize)

le_result_t	le_fwupdate_GetBootloaderVersion (char *version, size_t versionSize)

le_result_t	le_fwupdate_IsSystemMarkedGood (bool *isSystemGoodPtr)

le_result_t	le_fwupdate_Install (void)

le_result_t	le_fwupdate_MarkGood (void)

le_result_t	le_fwupdate_InstallAndMarkGood (void)

Detailed Description

Legato Modem Firmware Update include file.

Copyright (C) Sierra Wireless Inc.

Macro Definition Documentation

#define LE_FWUPDATE_MAX_VERS_LEN 256

Maximum length of a version string, excluding any termination character.

#define LE_FWUPDATE_STATUS_LABEL_LENGTH_MAX 32

Maximum length of the update status label

Typedef Documentation

typedef void(* le_fwupdate_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

Enumeration Type Documentation

enum le_fwupdate_UpdateStatus_t

Update status Indicates either a success or the defective image partition.

Enumerator
LE_FWUPDATE_UPDATE_STATUS_OK	Last update succeeded.
LE_FWUPDATE_UPDATE_STATUS_PARTITION_ERROR	At least, a partition is corrupted.
LE_FWUPDATE_UPDATE_STATUS_DWL_ONGOING	Downloading in progress.
LE_FWUPDATE_UPDATE_STATUS_DWL_FAILED	Last downloading failed.
LE_FWUPDATE_UPDATE_STATUS_DWL_TIMEOUT	Last downloading ended with timeout.
LE_FWUPDATE_UPDATE_STATUS_UNKNOWN	Unknown status. It has to be the last one.

Function Documentation

void le_fwupdate_ConnectService ( void )

Connect the current client thread to the service providing this API. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

void le_fwupdate_DisconnectService ( void )

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client-specific Functions.

This function is created automatically.

le_result_t le_fwupdate_Download ( int fd )

Download the firmware image file. The function can also be used to resume the download if the le_fwupdate_InitDownload() function is not called before.

Returns

LE_OK On success
LE_BAD_PARAMETER If an input parameter is not valid
LE_TIMEOUT After 900 seconds without data received
LE_NOT_POSSIBLE The systems are not synced
LE_UNAVAILABLE The flash access is not granted for SW update
LE_CLOSED File descriptor has been closed before all data have been received
LE_FAULT On failure

Note: The process exits, if an invalid file descriptor (e.g. negative) is given.

Parameters

[in] fd File descriptor of the image, opened to the start of the image.

le_result_t le_fwupdate_GetBootloaderVersion	(	char *	version,
		size_t	versionSize
	)

Get the bootloader version string

Returns

LE_OK on success
LE_NOT_FOUND if the version string is not available
LE_OVERFLOW if version string to big to fit in provided buffer
LE_FAULT for any other errors

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[out]	version	Bootloader version string
[in]	versionSize

le_result_t le_fwupdate_GetFirmwareVersion	(	char *	version,
		size_t	versionSize
	)

Get the firmware version string

Returns

LE_OK on success
LE_NOT_FOUND if the version string is not available
LE_OVERFLOW if version string to big to fit in provided buffer
LE_FAULT for any other errors

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[out]	version	Firmware version string
[in]	versionSize

le_result_t le_fwupdate_GetResumePosition ( size_t * positionPtr )

Return the downloaded update package write position.

Returns

LE_OK On success
LE_BAD_PARAMETER The given parameter is invalid.
LE_FAULT On failure

Parameters

[out] positionPtr Update package read position

le_result_t le_fwupdate_GetUpdateStatus	(	le_fwupdate_UpdateStatus_t *	statusPtr,
		char *	statusLabel,
		size_t	statusLabelSize
	)

Return the update status.

Returns

LE_OK on success
LE_BAD_PARAMETER Invalid parameter
LE_FAULT on failure

Parameters

[out]	statusPtr	Returned update status
[out]	statusLabel	Description of the status
[in]	statusLabelSize

le_result_t le_fwupdate_InitDownload ( void )

Download initialization:

for single and dual systems, it resets resume position,
for dual systems, it synchronizes the systems if needed.

Note: When invoked, resuming a previous download is not possible, a full update package has to be downloaded.

Returns

LE_OK On success
LE_FAULT On failure
LE_IO_ERROR Dual systems platforms only -- The synchronization fails due to unrecoverable ECC errors. In this case, the update without synchronization is forced, but the whole system must be updated to ensure that the new update system will be workable ECC stands for Error-Correction-Code: some errors may be corrected. If this correction fails, a unrecoverable error is registered and the data become corrupted.

le_result_t le_fwupdate_Install ( void )

Request to install the package. Calling this API will result in a system reset.

Dual System: After reset, the UPDATE and ACTIVE systems will be swapped. Single System: After reset, the image in the FOTA partition will be installed on the device.

Note: On success, a device reboot is initiated without returning any value.

Returns

LE_BUSY Download is ongoing, install is not allowed
LE_UNSUPPORTED The feature is not supported
LE_FAULT On failure

le_result_t le_fwupdate_InstallAndMarkGood ( void )

Request to install the package and marks the system as good. Calling this API will result in a system reset.

Dual System: Request a full system reset with a systems SWAP and systems SYNC. After the reset, the UPDATE and ACTIVE systems will be swapped and synchronized. Single System: Installs the package from the FOTA partition.

Note: On success, a device reboot is initiated without returning any value.

Returns

LE_FAULT On failure

le_result_t le_fwupdate_IsSystemMarkedGood ( bool * isSystemGoodPtr )

Get the status of the system.

Dual System: Indicates if Active and Update systems are synchronized Single System: This api is not supported on single system.

Returns

LE_OK On success
LE_UNSUPPORTED The feature is not supported

Parameters

[out] isSystemGoodPtr true if the system is marked good, false otherwise

le_result_t le_fwupdate_MarkGood ( void )

Mark the current system as good.

Dual System: Requests a system Sync. The UPDATE system will be synchronised with the ACTIVE one. Single System: This api is not supported on single system.

Returns

LE_OK On success
LE_UNSUPPORTED The feature is not supported
LE_UNAVAILABLE The flash access is not granted for SW update
LE_FAULT On failure
LE_IO_ERROR Dual systems platforms only -- The synchronization fails due to unrecoverable ECC errors ECC stands for Error-Correction-Code: some errors may be corrected. If this correction fails, an unrecoverable error is registered and the data become corrupted.

void le_fwupdate_SetServerDisconnectHandler	(	le_fwupdate_DisconnectHandler_t	disconnectHandler,
		void *	contextPtr
	)

Set handler called when server disconnection is detected.

When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants to continue without exiting, it should call longjmp() from inside the handler.

le_result_t le_fwupdate_TryConnectService ( void )

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

Returns

LE_OK if the client connected successfully to the service.
LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
LE_COMM_ERROR if the Service Directory cannot be reached.

/ Build Apps

le_fwupdate_interface.h File Reference

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation