le_fwupdate_common.h

Go to the documentation of this file.
    1 
    2 /*
    3  * ====================== WARNING ======================
    4  *
    5  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    6  * DO NOT MODIFY IN ANY WAY.
    7  *
    8  * ====================== WARNING ======================
    9  */
   10 /**
   11  * @file le_fwupdate_common.h
   12  *
   13  * Type definitions for le_fwupdate.
   14  *
   15  */
   16 #ifndef LE_FWUPDATE_COMMON_H_INCLUDE_GUARD
   17 #define LE_FWUPDATE_COMMON_H_INCLUDE_GUARD
   18 
   19 
   20 #include "legato.h"
   21 
   22 #define IFGEN_LE_FWUPDATE_PROTOCOL_ID "a7900f0401e4a7e540d9e07f28957f54"
   23 #define IFGEN_LE_FWUPDATE_MSG_SIZE 340
   24 /** @addtogroup le_fwupdate
   25  *  @{ **/
   26 
   27 
   28 //--------------------------------------------------------------------------------------------------
   29 /**
   30  * Maximum number of system versions allowed
   31  */
   32 //--------------------------------------------------------------------------------------------------
   33 #define LE_FWUPDATE_MAX_NUM_VERSIONS 32
   34 
   35 //--------------------------------------------------------------------------------------------------
   36 /**
   37  * Maximum length of a version name string, excluding any termination character.
   38  */
   39 //--------------------------------------------------------------------------------------------------
   40 #define LE_FWUPDATE_MAX_VERS_NAME_LEN 64
   41 
   42 //--------------------------------------------------------------------------------------------------
   43 /**
   44  * Maximum length of a version string, excluding any termination character.
   45  */
   46 //--------------------------------------------------------------------------------------------------
   47 #define LE_FWUPDATE_MAX_VERS_LEN 256
   48 
   49 //--------------------------------------------------------------------------------------------------
   50 /**
   51  * Maximum length of the update status label
   52  */
   53 //--------------------------------------------------------------------------------------------------
   54 #define LE_FWUPDATE_STATUS_LABEL_LENGTH_MAX 32
   55 
   56 //--------------------------------------------------------------------------------------------------
   57 /**
   58  * Update status
   59  * Indicates either a success or the defective image partition.
   60  */
   61 //--------------------------------------------------------------------------------------------------
   62 typedef enum
   63 {
   64     LE_FWUPDATE_UPDATE_STATUS_OK = 0,
   65         ///< Last update succeeded
   66     LE_FWUPDATE_UPDATE_STATUS_PARTITION_ERROR = 1,
   67         ///< At least, a partition is corrupted
   68     LE_FWUPDATE_UPDATE_STATUS_DWL_ONGOING = 2,
   69         ///< Downloading in progress
   70     LE_FWUPDATE_UPDATE_STATUS_DWL_FAILED = 3,
   71         ///< Last downloading failed
   72     LE_FWUPDATE_UPDATE_STATUS_DWL_TIMEOUT = 4,
   73         ///< Last downloading ended with timeout
   74     LE_FWUPDATE_UPDATE_STATUS_UNKNOWN = 5
   75         ///< Unknown status. It has to be the last one.
   76 }
   77 le_fwupdate_UpdateStatus_t;
   78 
   79 
   80 
   81 //--------------------------------------------------------------------------------------------------
   82 /**
   83  * Get if this client bound locally.
   84  */
   85 //--------------------------------------------------------------------------------------------------
   86 LE_SHARED bool ifgen_le_fwupdate_HasLocalBinding
   87 (
   88     void
   89 );
   90 
   91 
   92 //--------------------------------------------------------------------------------------------------
   93 /**
   94  * Init data that is common across all threads
   95  */
   96 //--------------------------------------------------------------------------------------------------
   97 LE_SHARED void ifgen_le_fwupdate_InitCommonData
   98 (
   99     void
  100 );
  101 
  102 
  103 //--------------------------------------------------------------------------------------------------
  104 /**
  105  * Perform common initialization and open a session
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 LE_SHARED le_result_t ifgen_le_fwupdate_OpenSession
  109 (
  110     le_msg_SessionRef_t _ifgen_sessionRef,
  111     bool isBlocking
  112 );
  113 
  114 //--------------------------------------------------------------------------------------------------
  115 /**
  116  * Download the firmware image file. The function can also be used to resume the download if the
  117  * le_fwupdate_InitDownload() function is not called before.
  118  *
  119  * @return
  120  *      - LE_OK              On success
  121  *      - LE_BAD_PARAMETER   If an input parameter is not valid
  122  *      - LE_TIMEOUT         After 900 seconds without data received
  123  *      - LE_NOT_PERMITTED   The systems are not synced
  124  *      - LE_UNAVAILABLE     The flash access is not granted for SW update
  125  *      - LE_CLOSED          File descriptor has been closed before all data have been received
  126  *      - LE_OUT_OF_RANGE    Storage is too small
  127  *      - LE_FAULT           On failure
  128  *
  129  * @note
  130  *      The process exits, if an invalid file descriptor (e.g. negative) is given.
  131  */
  132 //--------------------------------------------------------------------------------------------------
  133 LE_SHARED le_result_t ifgen_le_fwupdate_Download
  134 (
  135     le_msg_SessionRef_t _ifgen_sessionRef,
  136         int fd
  137         ///< [IN] File descriptor of the image, opened to the start of the image.
  138 );
  139 
  140 //--------------------------------------------------------------------------------------------------
  141 /**
  142  * Download initialization:
  143  *  - for single and dual systems, it resets resume position,
  144  *  - for dual systems, it synchronizes the systems if needed.
  145  *
  146  * @note
  147  *      When invoked, resuming a previous download is not possible, a full update package has to be
  148  *      downloaded.
  149  *
  150  * @return
  151  *      - LE_OK         On success
  152  *      - LE_FAULT      On failure
  153  *      - LE_IO_ERROR   Dual systems platforms only -- The synchronization fails due to
  154  *                      unrecoverable ECC errors. In this case, the update without synchronization
  155  *                      is forced, but the whole system must be updated to ensure that the new
  156  *                      update system will be workable
  157  *                      ECC stands for Error-Correction-Code: some errors may be corrected. If this
  158  *                      correction fails, a unrecoverable error is registered and the data become
  159  *                      corrupted.
  160  *      - LE_NO_MEMORY  On memory allocation failure
  161  */
  162 //--------------------------------------------------------------------------------------------------
  163 LE_SHARED le_result_t ifgen_le_fwupdate_InitDownload
  164 (
  165     le_msg_SessionRef_t _ifgen_sessionRef
  166 );
  167 
  168 //--------------------------------------------------------------------------------------------------
  169 /**
  170  * Return the downloaded update package write position.
  171  *
  172  * @return
  173  *      - LE_OK              On success
  174  *      - LE_BAD_PARAMETER   The given parameter is invalid.
  175  *      - LE_FAULT           On failure
  176  */
  177 //--------------------------------------------------------------------------------------------------
  178 LE_SHARED le_result_t ifgen_le_fwupdate_GetResumePosition
  179 (
  180     le_msg_SessionRef_t _ifgen_sessionRef,
  181         size_t* positionPtr
  182         ///< [OUT] Update package read position
  183 );
  184 
  185 //--------------------------------------------------------------------------------------------------
  186 /**
  187  * Return the update status.
  188  *
  189  * @return
  190  *      - LE_OK on success
  191  *      - LE_BAD_PARAMETER Invalid parameter
  192  *      - LE_FAULT on failure
  193  */
  194 //--------------------------------------------------------------------------------------------------
  195 LE_SHARED le_result_t ifgen_le_fwupdate_GetUpdateStatus
  196 (
  197     le_msg_SessionRef_t _ifgen_sessionRef,
  198         le_fwupdate_UpdateStatus_t* statusPtr,
  199         ///< [OUT] Returned update status
  200         char* statusLabel,
  201         ///< [OUT] Description of the status
  202         size_t statusLabelSize
  203         ///< [IN]
  204 );
  205 
  206 //--------------------------------------------------------------------------------------------------
  207 /**
  208  * Get the firmware version string
  209  *
  210  * @return
  211  *      - LE_OK          on success
  212  *      - LE_NOT_FOUND   if the version string is not available
  213  *      - LE_OVERFLOW    if version string to big to fit in provided buffer
  214  *      - LE_FAULT       for any other errors
  215  *
  216  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  217  *       function will not return.
  218  */
  219 //--------------------------------------------------------------------------------------------------
  220 LE_SHARED le_result_t ifgen_le_fwupdate_GetFirmwareVersion
  221 (
  222     le_msg_SessionRef_t _ifgen_sessionRef,
  223         char* version,
  224         ///< [OUT] Firmware version string
  225         size_t versionSize
  226         ///< [IN]
  227 );
  228 
  229 //--------------------------------------------------------------------------------------------------
  230 /**
  231  * Get the bootloader version string
  232  *
  233  * @return
  234  *      - LE_OK          on success
  235  *      - LE_NOT_FOUND   if the version string is not available
  236  *      - LE_OVERFLOW    if version string to big to fit in provided buffer
  237  *      - LE_FAULT       for any other errors
  238  *
  239  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  240  *       function will not return.
  241  */
  242 //--------------------------------------------------------------------------------------------------
  243 LE_SHARED le_result_t ifgen_le_fwupdate_GetBootloaderVersion
  244 (
  245     le_msg_SessionRef_t _ifgen_sessionRef,
  246         char* version,
  247         ///< [OUT] Bootloader version string
  248         size_t versionSize
  249         ///< [IN]
  250 );
  251 
  252 //--------------------------------------------------------------------------------------------------
  253 /**
  254  * Get the custom system version string at the specified index
  255  *
  256  * @return
  257  *      - LE_OK on success
  258  *      - LE_OUT_OF_RANGE if the index specified is greater than the number of versions available,
  259  *                        or greater than the number of versions allowed to be returned.
  260  *      - LE_OVERFLOW if the version string cannot fit in provided buffer
  261  *      - LE_NOT_FOUND if opening a version containing file fails
  262  *      - LE_FAULT if reading a version containing file fails
  263  *      - LE_UNAVAILABLE if the configTree is unavailable
  264  */
  265 //--------------------------------------------------------------------------------------------------
  266 LE_SHARED le_result_t ifgen_le_fwupdate_GetSystemVersion
  267 (
  268     le_msg_SessionRef_t _ifgen_sessionRef,
  269         uint8_t index,
  270         ///< [IN] Index to retrieve
  271         char* versionName,
  272         ///< [OUT] System version name string
  273         size_t versionNameSize,
  274         ///< [IN]
  275         char* version,
  276         ///< [OUT] System version string
  277         size_t versionSize
  278         ///< [IN]
  279 );
  280 
  281 //--------------------------------------------------------------------------------------------------
  282 /**
  283  * Get the app bootloader version string
  284  *
  285  * @return
  286  *      - LE_OK             on success
  287  *      - LE_NOT_FOUND      if the version string is not available
  288  *      - LE_OVERFLOW       if version string to big to fit in provided buffer
  289  *      - LE_BAD_PARAMETER  bad parameter
  290  *      - LE_UNSUPPORTED    not supported
  291  *      - LE_FAULT          for any other errors
  292  *
  293  * @note If the caller passes in a bad pointer, it is a fatal error and the function won't return.
  294  */
  295 //--------------------------------------------------------------------------------------------------
  296 LE_SHARED le_result_t ifgen_le_fwupdate_GetAppBootloaderVersion
  297 (
  298     le_msg_SessionRef_t _ifgen_sessionRef,
  299         char* version,
  300         ///< [OUT] Bootloader version string
  301         size_t versionSize
  302         ///< [IN]
  303 );
  304 
  305 //--------------------------------------------------------------------------------------------------
  306 /**
  307  * Get the status of the system.
  308  *
  309  * Dual System: Indicates if Active and Update systems are synchronized
  310  * Single System: This api is not supported on single system.
  311  *
  312  * @return
  313  *      - LE_OK            On success
  314  *      - LE_UNSUPPORTED   The feature is not supported
  315  */
  316 //--------------------------------------------------------------------------------------------------
  317 LE_SHARED le_result_t ifgen_le_fwupdate_IsSystemMarkedGood
  318 (
  319     le_msg_SessionRef_t _ifgen_sessionRef,
  320         bool* isSystemGoodPtr
  321         ///< [OUT] true if the system is marked good, false otherwise
  322 );
  323 
  324 //--------------------------------------------------------------------------------------------------
  325 /**
  326  * Request to install the package. Calling this API will result in a system reset.
  327  *
  328  * Dual System: After reset, the UPDATE and ACTIVE systems will be swapped.
  329  * Single System: After reset, the image in the FOTA partition will be installed on the device.
  330  *
  331  * @note On success, a device reboot is initiated without returning any value.
  332  *
  333  *
  334  * @return
  335  *      - LE_BUSY          Download is ongoing, install is not allowed
  336  *      - LE_UNSUPPORTED   The feature is not supported
  337  *      - LE_FAULT         On failure
  338  *
  339  */
  340 //--------------------------------------------------------------------------------------------------
  341 LE_SHARED le_result_t ifgen_le_fwupdate_Install
  342 (
  343     le_msg_SessionRef_t _ifgen_sessionRef
  344 );
  345 
  346 //--------------------------------------------------------------------------------------------------
  347 /**
  348  * Mark the current system as good.
  349  *
  350  * Dual System: Requests a system Sync. The UPDATE system will be synchronised with the ACTIVE one.
  351  * Single System: This api is not supported on single system.
  352  *
  353  * @return
  354  *      - LE_OK            On success
  355  *      - LE_UNSUPPORTED   The feature is not supported
  356  *      - LE_UNAVAILABLE   The flash access is not granted for SW update
  357  *      - LE_FAULT         On failure
  358  *      - LE_IO_ERROR      Dual systems platforms only -- The synchronization fails due to
  359  *                         unrecoverable ECC errors
  360  *                         ECC stands for Error-Correction-Code: some errors may be corrected. If
  361  *                         this correction fails, an unrecoverable error is registered and the data
  362  *                         become corrupted.
  363  *
  364  */
  365 //--------------------------------------------------------------------------------------------------
  366 LE_SHARED le_result_t ifgen_le_fwupdate_MarkGood
  367 (
  368     le_msg_SessionRef_t _ifgen_sessionRef
  369 );
  370 
  371 //--------------------------------------------------------------------------------------------------
  372 /**
  373  * Request to install the package and marks the system as good. Calling this API will result in a
  374  * system reset.
  375  *
  376  * Dual System: Request a full system reset with a systems SWAP and systems SYNC. After the reset,
  377  * the UPDATE and ACTIVE systems will be swapped and synchronized.
  378  * Single System: Installs the package from the FOTA partition.
  379  *
  380  *
  381  * @note On success, a device reboot is initiated without returning any value.
  382  *
  383  * @return
  384  *      - LE_FAULT         On failure
  385  *
  386  */
  387 //--------------------------------------------------------------------------------------------------
  388 LE_SHARED le_result_t ifgen_le_fwupdate_InstallAndMarkGood
  389 (
  390     le_msg_SessionRef_t _ifgen_sessionRef
  391 );
  392 /** @} **/
  393 #endif // LE_FWUPDATE_COMMON_H_INCLUDE_GUARD
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:287


LE_FWUPDATE_UPDATE_STATUS_OK
Last update succeeded. 
Definition: le_fwupdate_common.h:64


le_result_t
le_result_t
Definition: le_basics.h:46


LE_FWUPDATE_UPDATE_STATUS_DWL_TIMEOUT
Last downloading ended with timeout. 
Definition: le_fwupdate_common.h:72


LE_FWUPDATE_UPDATE_STATUS_DWL_FAILED
Last downloading failed. 
Definition: le_fwupdate_common.h:70


le_fwupdate_UpdateStatus_t
le_fwupdate_UpdateStatus_t
Definition: le_fwupdate_common.h:62


LE_FWUPDATE_UPDATE_STATUS_UNKNOWN
Unknown status. It has to be the last one. 
Definition: le_fwupdate_common.h:74


LE_FWUPDATE_UPDATE_STATUS_DWL_ONGOING
Downloading in progress. 
Definition: le_fwupdate_common.h:68


le_msg_SessionRef_t
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860



LE_FWUPDATE_UPDATE_STATUS_PARTITION_ERROR
At least, a partition is corrupted. 
Definition: le_fwupdate_common.h:66