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 // Internal includes for this interface
   98 #include "le_fwupdate_common.h"
   99 //--------------------------------------------------------------------------------------------------
  100 /**
  101  * Type for handler called when a server disconnects.
  102  */
  103 //--------------------------------------------------------------------------------------------------
  104 typedef void (*le_fwupdate_DisconnectHandler_t)(void *);
  105 
  106 //--------------------------------------------------------------------------------------------------
  107 /**
  108  *
  109  * Connect the current client thread to the service providing this API. Block until the service is
  110  * available.
  111  *
  112  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  113  * called before any other functions in this API.  Normally, ConnectService is automatically called
  114  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  115  *
  116  * This function is created automatically.
  117  */
  118 //--------------------------------------------------------------------------------------------------
  119 void le_fwupdate_ConnectService
  120 (
  121     void
  122 );
  123 
  124 //--------------------------------------------------------------------------------------------------
  125 /**
  126  *
  127  * Try to connect the current client thread to the service providing this API. Return with an error
  128  * if the service is not available.
  129  *
  130  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  131  * called before any other functions in this API.  Normally, ConnectService is automatically called
  132  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  133  *
  134  * This function is created automatically.
  135  *
  136  * @return
  137  *  - LE_OK if the client connected successfully to the service.
  138  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  139  *    bound.
  140  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  141  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  142  */
  143 //--------------------------------------------------------------------------------------------------
  144 le_result_t le_fwupdate_TryConnectService
  145 (
  146     void
  147 );
  148 
  149 //--------------------------------------------------------------------------------------------------
  150 /**
  151  * Set handler called when server disconnection is detected.
  152  *
  153  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  154  * to continue without exiting, it should call longjmp() from inside the handler.
  155  */
  156 //--------------------------------------------------------------------------------------------------
  157 LE_FULL_API void le_fwupdate_SetServerDisconnectHandler
  158 (
  159     le_fwupdate_DisconnectHandler_t disconnectHandler,
  160     void *contextPtr
  161 );
  162 
  163 //--------------------------------------------------------------------------------------------------
  164 /**
  165  *
  166  * Disconnect the current client thread from the service providing this API.
  167  *
  168  * Normally, this function doesn't need to be called. After this function is called, there's no
  169  * longer a connection to the service, and the functions in this API can't be used. For details, see
  170  * @ref apiFilesC_client.
  171  *
  172  * This function is created automatically.
  173  */
  174 //--------------------------------------------------------------------------------------------------
  175 void le_fwupdate_DisconnectService
  176 (
  177     void
  178 );
  179 
  180 
  181 //--------------------------------------------------------------------------------------------------
  182 /**
  183  * Update status
  184  * Indicates either a success or the defective image partition.
  185  */
  186 //--------------------------------------------------------------------------------------------------
  187 
  188 
  189 //--------------------------------------------------------------------------------------------------
  190 /**
  191  * Download the firmware image file. The function can also be used to resume the download if the
  192  * le_fwupdate_InitDownload() function is not called before.
  193  *
  194  * @return
  195  *      - LE_OK              On success
  196  *      - LE_BAD_PARAMETER   If an input parameter is not valid
  197  *      - LE_TIMEOUT         After 900 seconds without data received
  198  *      - LE_NOT_POSSIBLE    The systems are not synced
  199  *      - LE_UNAVAILABLE     The flash access is not granted for SW update
  200  *      - LE_CLOSED          File descriptor has been closed before all data have been received
  201  *      - LE_OUT_OF_RANGE    Storage is too small
  202  *      - LE_FAULT           On failure
  203  *
  204  * @note
  205  *      The process exits, if an invalid file descriptor (e.g. negative) is given.
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 le_result_t le_fwupdate_Download
  209 (
  210     int fd
  211         ///< [IN] File descriptor of the image, opened to the start of the image.
  212 );
  213 
  214 //--------------------------------------------------------------------------------------------------
  215 /**
  216  * Download initialization:
  217  *  - for single and dual systems, it resets resume position,
  218  *  - for dual systems, it synchronizes the systems if needed.
  219  *
  220  * @note
  221  *      When invoked, resuming a previous download is not possible, a full update package has to be
  222  *      downloaded.
  223  *
  224  * @return
  225  *      - LE_OK         On success
  226  *      - LE_FAULT      On failure
  227  *      - LE_IO_ERROR   Dual systems platforms only -- The synchronization fails due to
  228  *                      unrecoverable ECC errors. In this case, the update without synchronization
  229  *                      is forced, but the whole system must be updated to ensure that the new
  230  *                      update system will be workable
  231  *                      ECC stands for Error-Correction-Code: some errors may be corrected. If this
  232  *                      correction fails, a unrecoverable error is registered and the data become
  233  *                      corrupted.
  234  *      - LE_NO_MEMORY  On memory allocation failure
  235  */
  236 //--------------------------------------------------------------------------------------------------
  237 le_result_t le_fwupdate_InitDownload
  238 (
  239     void
  240 );
  241 
  242 //--------------------------------------------------------------------------------------------------
  243 /**
  244  * Return the downloaded update package write position.
  245  *
  246  * @return
  247  *      - LE_OK              On success
  248  *      - LE_BAD_PARAMETER   The given parameter is invalid.
  249  *      - LE_FAULT           On failure
  250  */
  251 //--------------------------------------------------------------------------------------------------
  252 le_result_t le_fwupdate_GetResumePosition
  253 (
  254     size_t* positionPtr
  255         ///< [OUT] Update package read position
  256 );
  257 
  258 //--------------------------------------------------------------------------------------------------
  259 /**
  260  * Return the update status.
  261  *
  262  * @return
  263  *      - LE_OK on success
  264  *      - LE_BAD_PARAMETER Invalid parameter
  265  *      - LE_FAULT on failure
  266  */
  267 //--------------------------------------------------------------------------------------------------
  268 le_result_t le_fwupdate_GetUpdateStatus
  269 (
  270     le_fwupdate_UpdateStatus_t* statusPtr,
  271         ///< [OUT] Returned update status
  272     char* statusLabel,
  273         ///< [OUT] Description of the status
  274     size_t statusLabelSize
  275         ///< [IN]
  276 );
  277 
  278 //--------------------------------------------------------------------------------------------------
  279 /**
  280  * Get the firmware version string
  281  *
  282  * @return
  283  *      - LE_OK          on success
  284  *      - LE_NOT_FOUND   if the version string is not available
  285  *      - LE_OVERFLOW    if version string to big to fit in provided buffer
  286  *      - LE_FAULT       for any other errors
  287  *
  288  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  289  *       function will not return.
  290  */
  291 //--------------------------------------------------------------------------------------------------
  292 le_result_t le_fwupdate_GetFirmwareVersion
  293 (
  294     char* version,
  295         ///< [OUT] Firmware version string
  296     size_t versionSize
  297         ///< [IN]
  298 );
  299 
  300 //--------------------------------------------------------------------------------------------------
  301 /**
  302  * Get the bootloader version string
  303  *
  304  * @return
  305  *      - LE_OK          on success
  306  *      - LE_NOT_FOUND   if the version string is not available
  307  *      - LE_OVERFLOW    if version string to big to fit in provided buffer
  308  *      - LE_FAULT       for any other errors
  309  *
  310  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  311  *       function will not return.
  312  */
  313 //--------------------------------------------------------------------------------------------------
  314 le_result_t le_fwupdate_GetBootloaderVersion
  315 (
  316     char* version,
  317         ///< [OUT] Bootloader version string
  318     size_t versionSize
  319         ///< [IN]
  320 );
  321 
  322 //--------------------------------------------------------------------------------------------------
  323 /**
  324  * Get the app bootloader version string
  325  *
  326  * @return
  327  *      - LE_OK             on success
  328  *      - LE_NOT_FOUND      if the version string is not available
  329  *      - LE_OVERFLOW       if version string to big to fit in provided buffer
  330  *      - LE_BAD_PARAMETER  bad parameter
  331  *      - LE_UNSUPPORTED    not supported
  332  *      - LE_FAULT          for any other errors
  333  *
  334  * @note If the caller passes in a bad pointer, it is a fatal error and the function won't return.
  335  */
  336 //--------------------------------------------------------------------------------------------------
  337 le_result_t le_fwupdate_GetAppBootloaderVersion
  338 (
  339     char* version,
  340         ///< [OUT] Bootloader version string
  341     size_t versionSize
  342         ///< [IN]
  343 );
  344 
  345 //--------------------------------------------------------------------------------------------------
  346 /**
  347  * Get the status of the system.
  348  *
  349  * Dual System: Indicates if Active and Update systems are synchronized
  350  * Single System: This api is not supported on single system.
  351  *
  352  * @return
  353  *      - LE_OK            On success
  354  *      - LE_UNSUPPORTED   The feature is not supported
  355  */
  356 //--------------------------------------------------------------------------------------------------
  357 le_result_t le_fwupdate_IsSystemMarkedGood
  358 (
  359     bool* isSystemGoodPtr
  360         ///< [OUT] true if the system is marked good, false otherwise
  361 );
  362 
  363 //--------------------------------------------------------------------------------------------------
  364 /**
  365  * Request to install the package. Calling this API will result in a system reset.
  366  *
  367  * Dual System: After reset, the UPDATE and ACTIVE systems will be swapped.
  368  * Single System: After reset, the image in the FOTA partition will be installed on the device.
  369  *
  370  * @note On success, a device reboot is initiated without returning any value.
  371  *
  372  *
  373  * @return
  374  *      - LE_BUSY          Download is ongoing, install is not allowed
  375  *      - LE_UNSUPPORTED   The feature is not supported
  376  *      - LE_FAULT         On failure
  377  *
  378  */
  379 //--------------------------------------------------------------------------------------------------
  380 le_result_t le_fwupdate_Install
  381 (
  382     void
  383 );
  384 
  385 //--------------------------------------------------------------------------------------------------
  386 /**
  387  * Mark the current system as good.
  388  *
  389  * Dual System: Requests a system Sync. The UPDATE system will be synchronised with the ACTIVE one.
  390  * Single System: This api is not supported on single system.
  391  *
  392  * @return
  393  *      - LE_OK            On success
  394  *      - LE_UNSUPPORTED   The feature is not supported
  395  *      - LE_UNAVAILABLE   The flash access is not granted for SW update
  396  *      - LE_FAULT         On failure
  397  *      - LE_IO_ERROR      Dual systems platforms only -- The synchronization fails due to
  398  *                         unrecoverable ECC errors
  399  *                         ECC stands for Error-Correction-Code: some errors may be corrected. If
  400  *                         this correction fails, an unrecoverable error is registered and the data
  401  *                         become corrupted.
  402  *
  403  */
  404 //--------------------------------------------------------------------------------------------------
  405 le_result_t le_fwupdate_MarkGood
  406 (
  407     void
  408 );
  409 
  410 //--------------------------------------------------------------------------------------------------
  411 /**
  412  * Request to install the package and marks the system as good. Calling this API will result in a
  413  * system reset.
  414  *
  415  * Dual System: Request a full system reset with a systems SWAP and systems SYNC. After the reset,
  416  * the UPDATE and ACTIVE systems will be swapped and synchronized.
  417  * Single System: Installs the package from the FOTA partition.
  418  *
  419  *
  420  * @note On success, a device reboot is initiated without returning any value.
  421  *
  422  * @return
  423  *      - LE_FAULT         On failure
  424  *
  425  */
  426 //--------------------------------------------------------------------------------------------------
  427 le_result_t le_fwupdate_InstallAndMarkGood
  428 (
  429     void
  430 );
  431 
  432 #endif // LE_FWUPDATE_INTERFACE_H_INCLUDE_GUARD
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
LE_FULL_API void le_fwupdate_SetServerDisconnectHandler(le_fwupdate_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_fwupdate_Download
le_result_t le_fwupdate_Download(int fd)
le_fwupdate_TryConnectService
le_result_t le_fwupdate_TryConnectService(void)
le_fwupdate_MarkGood
le_result_t le_fwupdate_MarkGood(void)
le_fwupdate_IsSystemMarkedGood
le_result_t le_fwupdate_IsSystemMarkedGood(bool *isSystemGoodPtr)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
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:104
le_fwupdate_GetAppBootloaderVersion
le_result_t le_fwupdate_GetAppBootloaderVersion(char *version, size_t versionSize)
le_fwupdate_DisconnectService
void le_fwupdate_DisconnectService(void)
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)