arm_uc_pal_blockdevice_implementation.h

00001 //----------------------------------------------------------------------------
00002 //   The confidential and proprietary information contained in this file may
00003 //   only be used by a person authorised under and to the extent permitted
00004 //   by a subsisting licensing agreement from ARM Limited or its affiliates.
00005 //
00006 //          (C) COPYRIGHT 2017 ARM Limited or its affiliates.
00007 //              ALL RIGHTS RESERVED
00008 //
00009 //   This entire notice must be reproduced on all copies of this file
00010 //   and copies of this file may only be made by a person if such person is
00011 //   permitted to do so under the terms of a subsisting license agreement
00012 //   from ARM Limited or its affiliates.
00013 //----------------------------------------------------------------------------
00014 
00015 #ifndef ARM_UC_PAL_BLOCKDEVICE_IMPLEMENTATION_H
00016 #define ARM_UC_PAL_BLOCKDEVICE_IMPLEMENTATION_H
00017 
00018 #include "update-client-paal/arm_uc_paal_update_api.h"
00019 
00020 #ifdef __cplusplus
00021 extern "C" {
00022 #endif
00023 
00024 /**
00025  * @brief Initialize the underlying storage and set the callback handler.
00026  *
00027  * @param callback Function pointer to event handler.
00028  * @return Returns ERR_NONE on accept, and signals the event handler with
00029  *         either DONE or ERROR when complete.
00030  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00031  */
00032 arm_uc_error_t ARM_UC_PAL_BlockDevice_Initialize(ARM_UC_PAAL_UPDATE_SignalEvent_t callback);
00033 
00034 /**
00035  * @brief Get maximum number of supported storage IDs.
00036  *
00037  * @return Number of storage locations.
00038  */
00039 uint32_t ARM_UC_PAL_BlockDevice_GetMaxID(void);
00040 
00041 /**
00042  * @brief Prepare the storage layer for a new firmware image.
00043  * @details The storage location is set up to receive an image with
00044  *          the details passed in the details struct.
00045  *
00046  * @param slot_id Storage location ID.
00047  * @param details Pointer to a struct with firmware details.
00048  * @param buffer Temporary buffer for formatting and storing metadata.
00049  * @return Returns ERR_NONE on accept, and signals the event handler with
00050  *         either DONE or ERROR when complete.
00051  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00052  */
00053 arm_uc_error_t ARM_UC_PAL_BlockDevice_Prepare(uint32_t slot_id,
00054                                               const arm_uc_firmware_details_t* details,
00055                                               arm_uc_buffer_t* buffer);
00056 
00057 /**
00058  * @brief Write a fragment to the indicated storage location.
00059  * @details The storage location must have been allocated using the Prepare
00060  *          call. The call is expected to write the entire fragment before
00061  *          signaling completion.
00062  *
00063  * @param slot_id Storage location ID.
00064  * @param offset Offset in bytes to where the fragment should be written.
00065  * @param buffer Pointer to buffer struct with fragment.
00066  * @return Returns ERR_NONE on accept, and signals the event handler with
00067  *         either DONE or ERROR when complete.
00068  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00069  */
00070 arm_uc_error_t ARM_UC_PAL_BlockDevice_Write(uint32_t slot_id,
00071                                             uint32_t offset,
00072                                             const arm_uc_buffer_t* buffer);
00073 
00074 /**
00075  * @brief Close storage location for writing and flush pending data.
00076  *
00077  * @param slot_id Storage location ID.
00078  * @return Returns ERR_NONE on accept, and signals the event handler with
00079  *         either DONE or ERROR when complete.
00080  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00081  */
00082 arm_uc_error_t ARM_UC_PAL_BlockDevice_Finalize(uint32_t slot_id);
00083 
00084 /**
00085  * @brief Read a fragment from the indicated storage location.
00086  * @details The function will read until the buffer is full or the end of
00087  *          the storage location has been reached. The actual amount of
00088  *          bytes read is set in the buffer struct.
00089  *
00090  * @param slot_id Storage location ID.
00091  * @param offset Offset in bytes to read from.
00092  * @param buffer Pointer to buffer struct to store fragment. buffer->size
00093  *        contains the intended read size.
00094  * @return Returns ERR_NONE on accept, and signals the event handler with
00095  *         either DONE or ERROR when complete.
00096  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00097  *         buffer->size contains actual bytes read on return.
00098  */
00099 arm_uc_error_t ARM_UC_PAL_BlockDevice_Read(uint32_t slot_id,
00100                                            uint32_t offset,
00101                                            arm_uc_buffer_t* buffer);
00102 
00103 /**
00104  * @brief Set the firmware image in the slot to be the new active image.
00105  * @details This call is responsible for initiating the process for
00106  *          applying a new/different image. Depending on the platform this
00107  *          could be:
00108  *           * An empty call, if the installer can deduce which slot to
00109  *             choose from based on the firmware details.
00110  *           * Setting a flag to indicate which slot to use next.
00111  *           * Decompressing/decrypting/installing the firmware image on
00112  *             top of another.
00113  *
00114  * @param slot_id Storage location ID.
00115  * @return Returns ERR_NONE on accept, and signals the event handler with
00116  *         either DONE or ERROR when complete.
00117  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00118  */
00119 arm_uc_error_t ARM_UC_PAL_BlockDevice_Activate(uint32_t slot_id);
00120 
00121 /**
00122  * @brief Get firmware details for the firmware image in the slot passed.
00123  * @details This call populates the passed details struct with information
00124  *          about the firmware image in the slot passed. Only the fields
00125  *          marked as supported in the capabilities bitmap will have valid
00126  *          values.
00127  *
00128  * @param slot_id Storage location ID.
00129  * @param details Pointer to firmware details struct to be populated.
00130  * @return Returns ERR_NONE on accept, and signals the event handler with
00131  *         either DONE or ERROR when complete.
00132  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00133  */
00134 arm_uc_error_t ARM_UC_PAL_BlockDevice_GetFirmwareDetails(
00135                                         uint32_t slot_id,
00136                                         arm_uc_firmware_details_t* details);
00137 
00138 #ifdef __cplusplus
00139 }
00140 #endif
00141 
00142 #endif /* ARM_UC_PAL_BLOCKDEVICE_H */