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