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