arm_uc_paal_update.c

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 // fixup the compilation on ARMCC for PRIu32
00020 #define __STDC_FORMAT_MACROS
00021 #include <inttypes.h>
00022 
00023 #include "update-client-paal/arm_uc_paal_update.h"
00024 #include "update-client-paal/arm_uc_paal_update_api.h"
00025 
00026 #define TRACE_GROUP  "UCPI"
00027 
00028 static const ARM_UC_PAAL_UPDATE *paal_update_implementation = NULL;
00029 
00030 /**
00031  * @brief Set PAAL Update implementation.
00032  *
00033  * @param implementation Function pointer struct to implementation.
00034  * @return Returns ERR_NONE on accept and ERR_INVALID_PARAMETER otherwise.
00035  */
00036 arm_uc_error_t ARM_UCP_SetPAALUpdate(const ARM_UC_PAAL_UPDATE *implementation)
00037 {
00038     UC_PAAL_TRACE("ARM_UCP_SetPAALUpdate");
00039 
00040     paal_update_implementation = implementation;
00041 
00042     return (arm_uc_error_t) { ERR_NONE };
00043 }
00044 
00045 /**
00046  * @brief Initialize the underlying storage and set the callback handler.
00047  *
00048  * @param callback Function pointer to event handler.
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_UCP_Initialize(ARM_UC_PAAL_UPDATE_SignalEvent_t callback)
00054 {
00055     UC_PAAL_TRACE("ARM_UCP_Initialize");
00056 
00057     arm_uc_error_t result = { .code = ERR_INVALID_PARAMETER };
00058 
00059     if (paal_update_implementation) {
00060         result = paal_update_implementation->Initialize(callback);
00061     }
00062 
00063     return result;
00064 }
00065 
00066 /**
00067  * @brief Get a bitmap indicating supported features.
00068  * @details The bitmap is used in conjunction with the firmware and
00069  *          installer details struct to indicate what fields are supported
00070  *          and which values are valid.
00071  *
00072  * @return Capability bitmap.
00073  */
00074 ARM_UC_PAAL_UPDATE_CAPABILITIES ARM_UCP_GetCapabilities(void)
00075 {
00076     UC_PAAL_TRACE("ARM_UCP_GetCapabilities");
00077 
00078     ARM_UC_PAAL_UPDATE_CAPABILITIES result = { 0 };
00079 
00080     if (paal_update_implementation) {
00081         result = paal_update_implementation->GetCapabilities();
00082     }
00083 
00084     return result;
00085 }
00086 
00087 /**
00088  * @brief Get maximum number of supported storage locations.
00089  *
00090  * @return Number of storage locations.
00091  */
00092 uint32_t ARM_UCP_GetMaxID(void)
00093 {
00094     UC_PAAL_TRACE("ARM_UCP_GetMaxID");
00095 
00096     uint32_t result = 0;
00097 
00098     if (paal_update_implementation) {
00099         result = paal_update_implementation->GetMaxID();
00100     }
00101 
00102     return result;
00103 }
00104 
00105 /**
00106  * @brief Prepare the storage layer for a new firmware image.
00107  * @details The storage location is set up to receive an image with
00108  *          the details passed in the details struct.
00109  *
00110  * @param location Storage location ID.
00111  * @param details Pointer to a struct with firmware details.
00112  * @param buffer Temporary buffer for formatting and storing metadata.
00113  * @return Returns ERR_NONE on accept, and signals the event handler with
00114  *         either DONE or ERROR when complete.
00115  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00116  */
00117 arm_uc_error_t ARM_UCP_Prepare(uint32_t location,
00118                                const arm_uc_firmware_details_t *details,
00119                                arm_uc_buffer_t *buffer)
00120 {
00121     UC_PAAL_TRACE("ARM_UCP_Prepare");
00122 
00123     arm_uc_error_t result = { .code = ERR_INVALID_PARAMETER };
00124 
00125     if (paal_update_implementation && details && buffer) {
00126         result = paal_update_implementation->Prepare(location,
00127                                                      details,
00128                                                      buffer);
00129     }
00130 
00131     return result;
00132 }
00133 
00134 /**
00135  * @brief Write a fragment to the indicated storage location.
00136  * @details The storage location must have been allocated using the Prepare
00137  *          call. The call is expected to write the entire fragment before
00138  *          signaling completion.
00139  *
00140  * @param location Storage location ID.
00141  * @param offset Offset in bytes to where the fragment should be written.
00142  * @param buffer Pointer to buffer struct with fragment.
00143  * @return Returns ERR_NONE on accept, and signals the event handler with
00144  *         either DONE or ERROR when complete.
00145  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00146  */
00147 arm_uc_error_t ARM_UCP_Write(uint32_t location,
00148                              uint32_t offset,
00149                              const arm_uc_buffer_t *buffer)
00150 {
00151     UC_PAAL_TRACE("ARM_UCP_Write: %p %p", paal_update_implementation, buffer);
00152 
00153     arm_uc_error_t result = { .code = ERR_INVALID_PARAMETER };
00154 
00155     if (paal_update_implementation && buffer) {
00156         result = paal_update_implementation->Write(location, offset, buffer);
00157     }
00158 
00159     return result;
00160 }
00161 
00162 /**
00163  * @brief Close storage location for writing and flush pending data.
00164  *
00165  * @param location Storage location ID.
00166  * @return Returns ERR_NONE on accept, and signals the event handler with
00167  *         either DONE or ERROR when complete.
00168  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00169  */
00170 arm_uc_error_t ARM_UCP_Finalize(uint32_t location)
00171 {
00172     UC_PAAL_TRACE("ARM_UCP_Finalize");
00173 
00174     arm_uc_error_t result = { .code = ERR_INVALID_PARAMETER };
00175 
00176     if (paal_update_implementation) {
00177         result = paal_update_implementation->Finalize(location);
00178     }
00179 
00180     return result;
00181 }
00182 
00183 /**
00184  * @brief Read a fragment from the indicated storage location.
00185  * @details The function will read until the buffer is full or the end of
00186  *          the storage location has been reached. The actual amount of
00187  *          bytes read is set in the buffer struct.
00188  *
00189  * @param location Storage location ID.
00190  * @param offset Offset in bytes to read from.
00191  * @param buffer Pointer to buffer struct to store fragment. buffer->size
00192  *        contains the intended read size.
00193  * @return Returns ERR_NONE on accept, and signals the event handler with
00194  *         either DONE or ERROR when complete.
00195  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00196  *         buffer->size contains actual bytes read on return.
00197  */
00198 arm_uc_error_t ARM_UCP_Read(uint32_t location,
00199                             uint32_t offset,
00200                             arm_uc_buffer_t *buffer)
00201 {
00202     UC_PAAL_TRACE("ARM_UCP_Read: %" PRIX32 " %p", offset, buffer);
00203 
00204     arm_uc_error_t result = { .code = ERR_INVALID_PARAMETER };
00205 
00206     if (paal_update_implementation && buffer) {
00207         result = paal_update_implementation->Read(location, offset, buffer);
00208     }
00209 
00210     return result;
00211 }
00212 
00213 /**
00214  * @brief Set the firmware image in the slot to be the new active image.
00215  * @details This call is responsible for initiating the process for
00216  *          applying a new/different image. Depending on the platform this
00217  *          could be:
00218  *           * An empty call, if the installer can deduce which slot to
00219  *             choose from based on the firmware details.
00220  *           * Setting a flag to indicate which slot to use next.
00221  *           * Decompressing/decrypting/installing the firmware image on
00222  *             top of another.
00223  *
00224  * @param location Storage location ID.
00225  * @return Returns ERR_NONE on accept, and signals the event handler with
00226  *         either DONE or ERROR when complete.
00227  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00228  */
00229 arm_uc_error_t ARM_UCP_Activate(uint32_t location)
00230 {
00231     UC_PAAL_TRACE("ARM_UCP_Activate");
00232 
00233     arm_uc_error_t result = { .code = ERR_INVALID_PARAMETER };
00234 
00235     if (paal_update_implementation) {
00236         result = paal_update_implementation->Activate(location);
00237     }
00238 
00239     return result;
00240 }
00241 
00242 /**
00243  * @brief Get firmware details for the actively running firmware.
00244  * @details This call populates the passed details struct with information
00245  *          about the currently active firmware image. Only the fields
00246  *          marked as supported in the capabilities bitmap will have valid
00247  *          values.
00248  *
00249  * @param details Pointer to firmware details struct to be populated.
00250  * @return Returns ERR_NONE on accept, and signals the event handler with
00251  *         either DONE or ERROR when complete.
00252  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00253  */
00254 arm_uc_error_t ARM_UCP_GetActiveFirmwareDetails(arm_uc_firmware_details_t *details)
00255 {
00256     UC_PAAL_TRACE("ARM_UCP_GetActiveFirmwareDetails");
00257 
00258     arm_uc_error_t result = { .code = ERR_INVALID_PARAMETER };
00259 
00260     if (paal_update_implementation && details) {
00261         result = paal_update_implementation->GetActiveFirmwareDetails(details);
00262     }
00263 
00264     return result;
00265 }
00266 
00267 /**
00268  * @brief Get firmware details for the firmware image in the slot passed.
00269  * @details This call populates the passed details struct with information
00270  *          about the firmware image in the slot passed. Only the fields
00271  *          marked as supported in the capabilities bitmap will have valid
00272  *          values.
00273  *
00274  * @param details Pointer to firmware details struct to be populated.
00275  * @return Returns ERR_NONE on accept, and signals the event handler with
00276  *         either DONE or ERROR when complete.
00277  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00278  */
00279 arm_uc_error_t ARM_UCP_GetFirmwareDetails(uint32_t location,
00280                                           arm_uc_firmware_details_t *details)
00281 {
00282     UC_PAAL_TRACE("ARM_UCP_GetFirmwareDetails");
00283 
00284     arm_uc_error_t result = { .code = ERR_INVALID_PARAMETER };
00285 
00286     if (paal_update_implementation && details) {
00287         result = paal_update_implementation->GetFirmwareDetails(location,
00288                                                                 details);
00289     }
00290 
00291     return result;
00292 }
00293 
00294 /**
00295  * @brief Get details for the component responsible for installation.
00296  * @details This call populates the passed details struct with information
00297  *          about the local installer. Only the fields marked as supported
00298  *          in the capabilities bitmap will have valid values. The
00299  *          installer could be the bootloader, a recovery image, or some
00300  *          other component responsible for applying the new firmware
00301  *          image.
00302  *
00303  * @param details Pointer to installer details struct to be populated.
00304  * @return Returns ERR_NONE on accept, and signals the event handler with
00305  *         either DONE or ERROR when complete.
00306  *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00307  */
00308 arm_uc_error_t ARM_UCP_GetInstallerDetails(arm_uc_installer_details_t *details)
00309 {
00310     UC_PAAL_TRACE("ARM_UCP_GetInstallerDetails");
00311 
00312     arm_uc_error_t result = { .code = ERR_INVALID_PARAMETER };
00313 
00314     if (paal_update_implementation && details) {
00315         result = paal_update_implementation->GetInstallerDetails(details);
00316     }
00317 
00318     return result;
00319 }