arm_uc_paal_update.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 #include "update-client-paal/arm_uc_paal_update_api.h"
00020 
00021 #include <stddef.h>
00022 
00023 #ifdef __cplusplus
00024 extern "C" {
00025 #endif
00026 
00027 /**
00028  * @brief Set PAAL Update implementation.
00029  *
00030  * @param implementation Function pointer struct to implementation.
00031  * @return Returns ERR_NONE on accept and ERR_INVALID_PARAMETER otherwise.
00032  */
00033 arm_uc_error_t ARM_UCP_SetPAALUpdate(const ARM_UC_PAAL_UPDATE *implementation);
00034 
00035 /**
00036  * @brief Initialize the underlying storage and set the callback handler.
00037  *
00038  * @param callback Function pointer to event handler.
00039  * @return Returns ERR_NONE on accept, and signals the event handler with
00040  *         either DONE or ERROR when complete.
00041  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00042  */
00043 arm_uc_error_t ARM_UCP_Initialize(ARM_UC_PAAL_UPDATE_SignalEvent_t callback);
00044 
00045 /**
00046  * @brief Get a bitmap indicating supported features.
00047  * @details The bitmap is used in conjunction with the firmware and
00048  *          installer details struct to indicate what fields are supported
00049  *          and which values are valid.
00050  *
00051  * @return Capability bitmap.
00052  */
00053 ARM_UC_PAAL_UPDATE_CAPABILITIES ARM_UCP_GetCapabilities(void);
00054 
00055 /**
00056  * @brief Get maximum number of supported storage locations.
00057  *
00058  * @return Number of storage locations.
00059  */
00060 uint32_t ARM_UCP_GetMaxID(void);
00061 
00062 /**
00063  * @brief Prepare the storage layer for a new firmware image.
00064  * @details The storage location is set up to receive an image with
00065  *          the details passed in the details struct.
00066  *
00067  * @param location Storage location ID.
00068  * @param details Pointer to a struct with firmware details.
00069  * @param buffer Temporary buffer for formatting and storing metadata.
00070  * @return Returns ERR_NONE on accept, and signals the event handler with
00071  *         either DONE or ERROR when complete.
00072  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00073  */
00074 arm_uc_error_t ARM_UCP_Prepare(uint32_t location,
00075                                const arm_uc_firmware_details_t *details,
00076                                arm_uc_buffer_t *buffer);
00077 
00078 /**
00079  * @brief Write a fragment to the indicated storage location.
00080  * @details The storage location must have been allocated using the Prepare
00081  *          call. The call is expected to write the entire fragment before
00082  *          signaling completion.
00083  *
00084  * @param location Storage location ID.
00085  * @param offset Offset in bytes to where the fragment should be written.
00086  * @param buffer Pointer to buffer struct with fragment.
00087  * @return Returns ERR_NONE on accept, and signals the event handler with
00088  *         either DONE or ERROR when complete.
00089  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00090  */
00091 arm_uc_error_t ARM_UCP_Write(uint32_t location,
00092                              uint32_t offset,
00093                              const arm_uc_buffer_t *buffer);
00094 
00095 /**
00096  * @brief Close storage location for writing and flush pending data.
00097  *
00098  * @param location Storage location ID.
00099  * @return Returns ERR_NONE on accept, and signals the event handler with
00100  *         either DONE or ERROR when complete.
00101  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00102  */
00103 arm_uc_error_t ARM_UCP_Finalize(uint32_t location);
00104 
00105 /**
00106  * @brief Read a fragment from the indicated storage location.
00107  * @details The function will read until the buffer is full or the end of
00108  *          the storage location has been reached. The actual amount of
00109  *          bytes read is set in the buffer struct.
00110  *
00111  * @param location Storage location ID.
00112  * @param offset Offset in bytes to read from.
00113  * @param buffer Pointer to buffer struct to store fragment. buffer->size
00114  *        contains the intended read size.
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  *         buffer->size contains actual bytes read on return.
00119  */
00120 arm_uc_error_t ARM_UCP_Read(uint32_t location,
00121                             uint32_t offset,
00122                             arm_uc_buffer_t *buffer);
00123 
00124 /**
00125  * @brief Set the firmware image in the slot to be the new active image.
00126  * @details This call is responsible for initiating the process for
00127  *          applying a new/different image. Depending on the platform this
00128  *          could be:
00129  *           * An empty call, if the installer can deduce which slot to
00130  *             choose from based on the firmware details.
00131  *           * Setting a flag to indicate which slot to use next.
00132  *           * Decompressing/decrypting/installing the firmware image on
00133  *             top of another.
00134  *
00135  * @param location Storage location ID.
00136  * @return Returns ERR_NONE on accept, and signals the event handler with
00137  *         either DONE or ERROR when complete.
00138  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00139  */
00140 arm_uc_error_t ARM_UCP_Activate(uint32_t location);
00141 
00142 /**
00143  * @brief Get firmware details for the actively running firmware.
00144  * @details This call populates the passed details struct with information
00145  *          about the currently active firmware image. Only the fields
00146  *          marked as supported in the capabilities bitmap will have valid
00147  *          values.
00148  *
00149  * @param details Pointer to firmware details struct to be populated.
00150  * @return Returns ERR_NONE on accept, and signals the event handler with
00151  *         either DONE or ERROR when complete.
00152  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00153  */
00154 arm_uc_error_t ARM_UCP_GetActiveFirmwareDetails(arm_uc_firmware_details_t *details);
00155 
00156 /**
00157  * @brief Get firmware details for the firmware image in the slot passed.
00158  * @details This call populates the passed details struct with information
00159  *          about the firmware image in the slot passed. Only the fields
00160  *          marked as supported in the capabilities bitmap will have valid
00161  *          values.
00162  *
00163  * @param details Pointer to firmware details struct to be populated.
00164  * @return Returns ERR_NONE on accept, and signals the event handler with
00165  *         either DONE or ERROR when complete.
00166  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00167  */
00168 arm_uc_error_t ARM_UCP_GetFirmwareDetails(uint32_t location,
00169                                           arm_uc_firmware_details_t *details);
00170 
00171 /**
00172  * @brief Get details for the component responsible for installation.
00173  * @details This call populates the passed details struct with information
00174  *          about the local installer. Only the fields marked as supported
00175  *          in the capabilities bitmap will have valid values. The
00176  *          installer could be the bootloader, a recovery image, or some
00177  *          other component responsible for applying the new firmware
00178  *          image.
00179  *
00180  * @param details Pointer to installer details struct to be populated.
00181  * @return Returns ERR_NONE on accept, and signals the event handler with
00182  *         either DONE or ERROR when complete.
00183  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00184  */
00185 arm_uc_error_t ARM_UCP_GetInstallerDetails(arm_uc_installer_details_t *details);
00186 
00187 #ifdef __cplusplus
00188 }
00189 #endif