Macros | Typedefs | Enumerations | Functions

le_fwupdate_interface.h File Reference

#include "legato.h"

Go to the source code of this file.

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_GetAppBootloaderVersion (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 Firmware Update API 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]fdFile descriptor of the image, opened to the start of the image.
le_result_t le_fwupdate_GetAppBootloaderVersion ( char *  version,
size_t  versionSize 
)

Get the app 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_BAD_PARAMETER bad parameter
  • LE_UNSUPPORTED not supported
  • LE_FAULT for any other errors
Note
If the caller passes in a bad pointer, it is a fatal error and the function won't return.
Parameters
[out]versionBootloader version string
[in]versionSize
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]versionBootloader 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]versionFirmware 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]positionPtrUpdate 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]statusPtrReturned update status
[out]statusLabelDescription 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]isSystemGoodPtrtrue 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.