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 //--------------------------------------------------------------------------------------------------
  118 void le_fwupdate_ConnectService
  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 //--------------------------------------------------------------------------------------------------
  143 le_result_t le_fwupdate_TryConnectService
  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 //--------------------------------------------------------------------------------------------------
  156 void le_fwupdate_SetServerDisconnectHandler
  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 //--------------------------------------------------------------------------------------------------
  174 void le_fwupdate_DisconnectService
  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 {
  202     LE_FWUPDATE_UPDATE_STATUS_OK = 0,
  203         ///< Last update succeeded
  204     LE_FWUPDATE_UPDATE_STATUS_PARTITION_ERROR = 1,
  205         ///< At least, a partition is corrupted
  206     LE_FWUPDATE_UPDATE_STATUS_DWL_ONGOING = 2,
  207         ///< Downloading in progress
  208     LE_FWUPDATE_UPDATE_STATUS_DWL_FAILED = 3,
  209         ///< Last downloading failed
  210     LE_FWUPDATE_UPDATE_STATUS_DWL_TIMEOUT = 4,
  211         ///< Last downloading ended with timeout
  212     LE_FWUPDATE_UPDATE_STATUS_UNKNOWN = 5
  213         ///< Unknown status. It has to be the last one.
  214 }
  215 le_fwupdate_UpdateStatus_t;
  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 //--------------------------------------------------------------------------------------------------
  236 le_result_t le_fwupdate_Download
  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  */
  256 //--------------------------------------------------------------------------------------------------
  257 le_result_t le_fwupdate_InitDownload
  258 (
  259     void
  260 );
  261 
  262 //--------------------------------------------------------------------------------------------------
  263 /**
  264  * Return the downloaded update package write position.
  265  *
  266  * @return
  267  *      - LE_OK              On success
  268  *      - LE_BAD_PARAMETER   The given parameter is invalid.
  269  *      - LE_FAULT           On failure
  270  */
  271 //--------------------------------------------------------------------------------------------------
  272 le_result_t le_fwupdate_GetResumePosition
  273 (
  274     size_t* positionPtr
  275         ///< [OUT] Update package read position
  276 );
  277 
  278 //--------------------------------------------------------------------------------------------------
  279 /**
  280  * Return the update status.
  281  *
  282  * @return
  283  *      - LE_OK on success
  284  *      - LE_BAD_PARAMETER Invalid parameter
  285  *      - LE_FAULT on failure
  286  */
  287 //--------------------------------------------------------------------------------------------------
  288 le_result_t le_fwupdate_GetUpdateStatus
  289 (
  290     le_fwupdate_UpdateStatus_t* statusPtr,
  291         ///< [OUT] Returned update status
  292     char* statusLabel,
  293         ///< [OUT] Description of the status
  294     size_t statusLabelSize
  295         ///< [IN]
  296 );
  297 
  298 //--------------------------------------------------------------------------------------------------
  299 /**
  300  * Get the firmware version string
  301  *
  302  * @return
  303  *      - LE_OK          on success
  304  *      - LE_NOT_FOUND   if the version string is not available
  305  *      - LE_OVERFLOW    if version string to big to fit in provided buffer
  306  *      - LE_FAULT       for any other errors
  307  *
  308  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  309  *       function will not return.
  310  */
  311 //--------------------------------------------------------------------------------------------------
  312 le_result_t le_fwupdate_GetFirmwareVersion
  313 (
  314     char* version,
  315         ///< [OUT] Firmware version string
  316     size_t versionSize
  317         ///< [IN]
  318 );
  319 
  320 //--------------------------------------------------------------------------------------------------
  321 /**
  322  * Get the bootloader version string
  323  *
  324  * @return
  325  *      - LE_OK          on success
  326  *      - LE_NOT_FOUND   if the version string is not available
  327  *      - LE_OVERFLOW    if version string to big to fit in provided buffer
  328  *      - LE_FAULT       for any other errors
  329  *
  330  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  331  *       function will not return.
  332  */
  333 //--------------------------------------------------------------------------------------------------
  334 le_result_t le_fwupdate_GetBootloaderVersion
  335 (
  336     char* version,
  337         ///< [OUT] Bootloader version string
  338     size_t versionSize
  339         ///< [IN]
  340 );
  341 
  342 //--------------------------------------------------------------------------------------------------
  343 /**
  344  * Get the status of the system.
  345  *
  346  * Dual System: Indicates if Active and Update systems are synchronized
  347  * Single System: This api is not supported on single system.
  348  *
  349  * @return
  350  *      - LE_OK            On success
  351  *      - LE_UNSUPPORTED   The feature is not supported
  352  */
  353 //--------------------------------------------------------------------------------------------------
  354 le_result_t le_fwupdate_IsSystemMarkedGood
  355 (
  356     bool* isSystemGoodPtr
  357         ///< [OUT] true if the system is marked good, false otherwise
  358 );
  359 
  360 //--------------------------------------------------------------------------------------------------
  361 /**
  362  * Request to install the package. Calling this API will result in a system reset.
  363  *
  364  * Dual System: After reset, the UPDATE and ACTIVE systems will be swapped.
  365  * Single System: After reset, the image in the FOTA partition will be installed on the device.
  366  *
  367  * @note On success, a device reboot is initiated without returning any value.
  368  *
  369  *
  370  * @return
  371  *      - LE_BUSY          Download is ongoing, install is not allowed
  372  *      - LE_UNSUPPORTED   The feature is not supported
  373  *      - LE_FAULT         On failure
  374  *
  375  */
  376 //--------------------------------------------------------------------------------------------------
  377 le_result_t le_fwupdate_Install
  378 (
  379     void
  380 );
  381 
  382 //--------------------------------------------------------------------------------------------------
  383 /**
  384  * Mark the current system as good.
  385  *
  386  * Dual System: Requests a system Sync. The UPDATE system will be synchronised with the ACTIVE one.
  387  * Single System: This api is not supported on single system.
  388  *
  389  * @return
  390  *      - LE_OK            On success
  391  *      - LE_UNSUPPORTED   The feature is not supported
  392  *      - LE_UNAVAILABLE   The flash access is not granted for SW update
  393  *      - LE_FAULT         On failure
  394  *
  395  */
  396 //--------------------------------------------------------------------------------------------------
  397 le_result_t le_fwupdate_MarkGood
  398 (
  399     void
  400 );
  401 
  402 //--------------------------------------------------------------------------------------------------
  403 /**
  404  * Request to install the package and marks the system as good. Calling this API will result in a
  405  * system reset.
  406  *
  407  * Dual System: Request a full system reset with a systems SWAP and systems SYNC. After the reset,
  408  * the UPDATE and ACTIVE systems will be swapped and synchronized.
  409  * Single System: Installs the package from the FOTA partition.
  410  *
  411  *
  412  * @note On success, a device reboot is initiated without returning any value.
  413  *
  414  * @return
  415  *      - LE_FAULT         On failure
  416  *
  417  */
  418 //--------------------------------------------------------------------------------------------------
  419 le_result_t le_fwupdate_InstallAndMarkGood
  420 (
  421     void
  422 );
  423 
  424 #endif // LE_FWUPDATE_INTERFACE_H_INCLUDE_GUARD
LE_FWUPDATE_UPDATE_STATUS_PARTITION_ERROR
At least, a partition is corrupted. 
Definition: le_fwupdate_interface.h:204


le_fwupdate_GetBootloaderVersion
le_result_t le_fwupdate_GetBootloaderVersion(char *version, size_t versionSize)


le_fwupdate_GetResumePosition
le_result_t le_fwupdate_GetResumePosition(size_t *positionPtr)


le_fwupdate_ConnectService
void le_fwupdate_ConnectService(void)


le_result_t
le_result_t
Definition: le_basics.h:35


le_fwupdate_SetServerDisconnectHandler
void le_fwupdate_SetServerDisconnectHandler(le_fwupdate_DisconnectHandler_t disconnectHandler, void *contextPtr)


LE_FWUPDATE_UPDATE_STATUS_DWL_FAILED
Last downloading failed. 
Definition: le_fwupdate_interface.h:208


LE_FWUPDATE_UPDATE_STATUS_DWL_TIMEOUT
Last downloading ended with timeout. 
Definition: le_fwupdate_interface.h:210


le_fwupdate_Download
le_result_t le_fwupdate_Download(int fd)


LE_FWUPDATE_UPDATE_STATUS_UNKNOWN
Unknown status. It has to be the last one. 
Definition: le_fwupdate_interface.h:212


le_fwupdate_TryConnectService
le_result_t le_fwupdate_TryConnectService(void)


LE_FWUPDATE_UPDATE_STATUS_OK
Last update succeeded. 
Definition: le_fwupdate_interface.h:202


le_fwupdate_MarkGood
le_result_t le_fwupdate_MarkGood(void)


le_fwupdate_IsSystemMarkedGood
le_result_t le_fwupdate_IsSystemMarkedGood(bool *isSystemGoodPtr)


le_fwupdate_InitDownload
le_result_t le_fwupdate_InitDownload(void)



le_fwupdate_GetFirmwareVersion
le_result_t le_fwupdate_GetFirmwareVersion(char *version, size_t versionSize)


le_fwupdate_DisconnectHandler_t
void(* le_fwupdate_DisconnectHandler_t)(void *)
Definition: le_fwupdate_interface.h:103


le_fwupdate_DisconnectService
void le_fwupdate_DisconnectService(void)


LE_FWUPDATE_UPDATE_STATUS_DWL_ONGOING
Downloading in progress. 
Definition: le_fwupdate_interface.h:206


le_fwupdate_UpdateStatus_t
le_fwupdate_UpdateStatus_t
Definition: le_fwupdate_interface.h:200


le_fwupdate_Install
le_result_t le_fwupdate_Install(void)


le_fwupdate_InstallAndMarkGood
le_result_t le_fwupdate_InstallAndMarkGood(void)


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