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


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


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:58


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


le_fwupdate_UpdateStatus_t
le_fwupdate_UpdateStatus_t
Definition: le_fwupdate_common.h:48


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


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


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:52