arm_uc_pal_flashiap_implementation.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2017 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef ARM_UC_PAL_FLASHIAP_IMPLEMENTATION_H
00020 #define ARM_UC_PAL_FLASHIAP_IMPLEMENTATION_H
00021 
00022 #include "update-client-paal/arm_uc_paal_update_api.h"
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 arm_uc_error_t ARM_UC_PAL_FlashIAP_Initialize(ARM_UC_PAAL_UPDATE_SignalEvent_t callback);
00029 
00030 /**
00031  * @brief Get maximum number of supported storage locations.
00032  *
00033  * @return Number of storage locations.
00034  */
00035 uint32_t ARM_UC_PAL_FlashIAP_GetMaxID(void);
00036 
00037 /**
00038  * @brief Prepare the storage layer for a new firmware image.
00039  * @details The storage location is set up to receive an image with
00040  *          the details passed in the details struct.
00041  *
00042  * @param location Storage location ID.
00043  * @param details Pointer to a struct with firmware details.
00044  * @param buffer Temporary buffer for formatting and storing metadata.
00045  * @return Returns ERR_NONE on accept, and signals the event handler with
00046  *         either DONE or ERROR when complete.
00047  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00048  */
00049 arm_uc_error_t ARM_UC_PAL_FlashIAP_Prepare(uint32_t location,
00050                                            const arm_uc_firmware_details_t *details,
00051                                            arm_uc_buffer_t *buffer);
00052 
00053 /**
00054  * @brief Write a fragment to the indicated storage location.
00055  * @details The storage location must have been allocated using the Prepare
00056  *          call. The call is expected to write the entire fragment before
00057  *          signaling completion.
00058  *
00059  * @param location Storage location ID.
00060  * @param offset Offset in bytes to where the fragment should be written.
00061  * @param buffer Pointer to buffer struct with fragment.
00062  * @return Returns ERR_NONE on accept, and signals the event handler with
00063  *         either DONE or ERROR when complete.
00064  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00065  */
00066 arm_uc_error_t ARM_UC_PAL_FlashIAP_Write(uint32_t location,
00067                                          uint32_t offset,
00068                                          const arm_uc_buffer_t *buffer);
00069 
00070 /**
00071  * @brief Close storage location for writing and flush pending data.
00072  *
00073  * @param location Storage location ID.
00074  * @return Returns ERR_NONE on accept, and signals the event handler with
00075  *         either DONE or ERROR when complete.
00076  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00077  */
00078 arm_uc_error_t ARM_UC_PAL_FlashIAP_Finalize(uint32_t location);
00079 
00080 /**
00081  * @brief Read a fragment from the indicated storage location.
00082  * @details The function will read until the buffer is full or the end of
00083  *          the storage location has been reached. The actual amount of
00084  *          bytes read is set in the buffer struct.
00085  *
00086  * @param location Storage location ID.
00087  * @param offset Offset in bytes to read from.
00088  * @param buffer Pointer to buffer struct to store fragment. buffer->size
00089  *        contains the intended read size.
00090  * @return Returns ERR_NONE on accept, and signals the event handler with
00091  *         either DONE or ERROR when complete.
00092  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00093  *         buffer->size contains actual bytes read on return.
00094  */
00095 arm_uc_error_t ARM_UC_PAL_FlashIAP_Read(uint32_t location,
00096                                         uint32_t offset,
00097                                         arm_uc_buffer_t *buffer);
00098 
00099 /**
00100  * @brief Set the firmware image in the slot to be the new active image.
00101  * @details This call is responsible for initiating the process for
00102  *          applying a new/different image. Depending on the platform this
00103  *          could be:
00104  *           * An empty call, if the installer can deduce which slot to
00105  *             choose from based on the firmware details.
00106  *           * Setting a flag to indicate which slot to use next.
00107  *           * Decompressing/decrypting/installing the firmware image on
00108  *             top of another.
00109  *
00110  * @param location Storage location ID.
00111  * @return Returns ERR_NONE on accept, and signals the event handler with
00112  *         either DONE or ERROR when complete.
00113  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00114  */
00115 arm_uc_error_t ARM_UC_PAL_FlashIAP_Activate(uint32_t location);
00116 
00117 /**
00118  * @brief Get firmware details for the firmware image in the slot passed.
00119  * @details This call populates the passed details struct with information
00120  *          about the firmware image in the slot passed. Only the fields
00121  *          marked as supported in the capabilities bitmap will have valid
00122  *          values.
00123  *
00124  * @param details Pointer to firmware details struct to be populated.
00125  * @return Returns ERR_NONE on accept, and signals the event handler with
00126  *         either DONE or ERROR when complete.
00127  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00128  */
00129 arm_uc_error_t ARM_UC_PAL_FlashIAP_GetFirmwareDetails(
00130     uint32_t location,
00131     arm_uc_firmware_details_t *details);
00132 
00133 /*****************************************************************************/
00134 
00135 arm_uc_error_t ARM_UC_PAL_FlashIAP_GetActiveDetails(arm_uc_firmware_details_t *details);
00136 
00137 arm_uc_error_t ARM_UC_PAL_FlashIAP_GetInstallerDetails(arm_uc_installer_details_t *details);
00138 
00139 #ifdef __cplusplus
00140 }
00141 #endif
00142 
00143 #endif // ARM_UC_PAL_FLASHIAP_IMPLEMENTATION_H