le_fwupdate_interface.h

    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 
   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  *      - 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 //--------------------------------------------------------------------------------------------------
  264 le_result_t le_fwupdate_InitDownload
  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 //--------------------------------------------------------------------------------------------------
  279 le_result_t le_fwupdate_GetResumePosition
  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 //--------------------------------------------------------------------------------------------------
  295 le_result_t le_fwupdate_GetUpdateStatus
  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 //--------------------------------------------------------------------------------------------------
  319 le_result_t le_fwupdate_GetFirmwareVersion
  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 //--------------------------------------------------------------------------------------------------
  341 le_result_t le_fwupdate_GetBootloaderVersion
  342 (
  343     char* version,
  344         ///< [OUT] Bootloader version string
  345     size_t versionSize
  346         ///< [IN]
  347 );
  348 
  349 //--------------------------------------------------------------------------------------------------
  350 /**
  351  * Get the app bootloader version string
  352  *
  353  * @return
  354  *      - LE_OK             on success
  355  *      - LE_NOT_FOUND      if the version string is not available
  356  *      - LE_OVERFLOW       if version string to big to fit in provided buffer
  357  *      - LE_BAD_PARAMETER  bad parameter
  358  *      - LE_UNSUPPORTED    not supported
  359  *      - LE_FAULT          for any other errors
  360  *
  361  * @note If the caller passes in a bad pointer, it is a fatal error and the function won't return.
  362  */
  363 //--------------------------------------------------------------------------------------------------
  364 le_result_t le_fwupdate_GetAppBootloaderVersion
  365 (
  366     char* version,
  367         ///< [OUT] Bootloader version string
  368     size_t versionSize
  369         ///< [IN]
  370 );
  371 
  372 //--------------------------------------------------------------------------------------------------
  373 /**
  374  * Get the status of the system.
  375  *
  376  * Dual System: Indicates if Active and Update systems are synchronized
  377  * Single System: This api is not supported on single system.
  378  *
  379  * @return
  380  *      - LE_OK            On success
  381  *      - LE_UNSUPPORTED   The feature is not supported
  382  */
  383 //--------------------------------------------------------------------------------------------------
  384 le_result_t le_fwupdate_IsSystemMarkedGood
  385 (
  386     bool* isSystemGoodPtr
  387         ///< [OUT] true if the system is marked good, false otherwise
  388 );
  389 
  390 //--------------------------------------------------------------------------------------------------
  391 /**
  392  * Request to install the package. Calling this API will result in a system reset.
  393  *
  394  * Dual System: After reset, the UPDATE and ACTIVE systems will be swapped.
  395  * Single System: After reset, the image in the FOTA partition will be installed on the device.
  396  *
  397  * @note On success, a device reboot is initiated without returning any value.
  398  *
  399  *
  400  * @return
  401  *      - LE_BUSY          Download is ongoing, install is not allowed
  402  *      - LE_UNSUPPORTED   The feature is not supported
  403  *      - LE_FAULT         On failure
  404  *
  405  */
  406 //--------------------------------------------------------------------------------------------------
  407 le_result_t le_fwupdate_Install
  408 (
  409     void
  410 );
  411 
  412 //--------------------------------------------------------------------------------------------------
  413 /**
  414  * Mark the current system as good.
  415  *
  416  * Dual System: Requests a system Sync. The UPDATE system will be synchronised with the ACTIVE one.
  417  * Single System: This api is not supported on single system.
  418  *
  419  * @return
  420  *      - LE_OK            On success
  421  *      - LE_UNSUPPORTED   The feature is not supported
  422  *      - LE_UNAVAILABLE   The flash access is not granted for SW update
  423  *      - LE_FAULT         On failure
  424  *      - LE_IO_ERROR      Dual systems platforms only -- The synchronization fails due to
  425  *                         unrecoverable ECC errors
  426  *                         ECC stands for Error-Correction-Code: some errors may be corrected. If
  427  *                         this correction fails, an unrecoverable error is registered and the data
  428  *                         become corrupted.
  429  *
  430  */
  431 //--------------------------------------------------------------------------------------------------
  432 le_result_t le_fwupdate_MarkGood
  433 (
  434     void
  435 );
  436 
  437 //--------------------------------------------------------------------------------------------------
  438 /**
  439  * Request to install the package and marks the system as good. Calling this API will result in a
  440  * system reset.
  441  *
  442  * Dual System: Request a full system reset with a systems SWAP and systems SYNC. After the reset,
  443  * the UPDATE and ACTIVE systems will be swapped and synchronized.
  444  * Single System: Installs the package from the FOTA partition.
  445  *
  446  *
  447  * @note On success, a device reboot is initiated without returning any value.
  448  *
  449  * @return
  450  *      - LE_FAULT         On failure
  451  *
  452  */
  453 //--------------------------------------------------------------------------------------------------
  454 le_result_t le_fwupdate_InstallAndMarkGood
  455 (
  456     void
  457 );
  458 
  459 #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)
legato.h
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_GetAppBootloaderVersion
le_result_t le_fwupdate_GetAppBootloaderVersion(char *version, size_t versionSize)
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)