arm_uc_paal_update_api.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_PAAL_UPDATE_API_H
00020 #define ARM_UC_PAAL_UPDATE_API_H
00021 
00022 #include "update-client-common/arm_uc_error.h"
00023 #include "update-client-common/arm_uc_types.h"
00024 
00025 #ifndef __STDC_FORMAT_MACROS
00026 #define __STDC_FORMAT_MACROS
00027 #endif
00028 
00029 #include <inttypes.h>
00030 #include <string.h>
00031 #include <stdint.h>
00032 
00033 #define __FILENAME__ (strrchr(__FILE__, '/') ? strrchr(__FILE__, '/') + 1 : __FILE__)
00034 
00035 #if defined(MBED_CONF_MBED_TRACE_ENABLE) && MBED_CONF_MBED_TRACE_ENABLE == 1
00036 
00037 #include "mbed-trace/mbed_trace.h"
00038 
00039 #define ARM_UC_TRACE_DEBUG_PRINTF(module, fmt, ...) tr_debug("[%-4s] %s:%d: " fmt, module, __FILENAME__, __LINE__, ##__VA_ARGS__)
00040 #define ARM_UC_TRACE_ERROR_PRINTF(module, fmt, ...) tr_error("[%-4s] %s:%d: " fmt, module, __FILENAME__, __LINE__, ##__VA_ARGS__)
00041 
00042 #else // if defined(MBED_CONF_MBED_TRACE_ENABLE) && MBED_CONF_MBED_TRACE_ENABLE == 1
00043 
00044 #include <stdio.h>
00045 
00046 #define ARM_UC_TRACE_DEBUG_PRINTF(module, fmt, ...) printf("[TRACE][%-4s] %s:%d: " fmt "\r\n", module, __FILENAME__, __LINE__, ##__VA_ARGS__)
00047 #define ARM_UC_TRACE_ERROR_PRINTF(module, fmt, ...) printf("[ERROR][%-4s] %s:%d: " fmt "\r\n", module, __FILENAME__, __LINE__, ##__VA_ARGS__)
00048 
00049 #endif // if defined(MBED_CONF_MBED_TRACE_ENABLE) && MBED_CONF_MBED_TRACE_ENABLE == 1
00050 
00051 #if ARM_UC_PAAL_TRACE_ENABLE
00052 #define UC_PAAL_TRACE(fmt, ...)   ARM_UC_TRACE_DEBUG_PRINTF("PAAL", fmt, ##__VA_ARGS__)
00053 #define UC_PAAL_ERR_MSG(fmt, ...) ARM_UC_TRACE_ERROR_PRINTF("PAAL", fmt, ##__VA_ARGS__)
00054 #else
00055 #define UC_PAAL_TRACE(fmt, ...)
00056 #define UC_PAAL_ERR_MSG(fmt, ...)
00057 #endif // if ARM_UC_PAAL_TRACE_ENABLE
00058 
00059 /**
00060  * @brief Prototype for event handler.
00061  */
00062 typedef void (*ARM_UC_PAAL_UPDATE_SignalEvent_t)(uintptr_t event);
00063 
00064 /**
00065  * @brief Asynchronous events.
00066  */
00067 enum {
00068     ARM_UC_PAAL_EVENT_INITIALIZE_DONE,
00069     ARM_UC_PAAL_EVENT_PREPARE_DONE,
00070     ARM_UC_PAAL_EVENT_WRITE_DONE,
00071     ARM_UC_PAAL_EVENT_FINALIZE_DONE,
00072     ARM_UC_PAAL_EVENT_READ_DONE,
00073     ARM_UC_PAAL_EVENT_ACTIVATE_DONE,
00074     ARM_UC_PAAL_EVENT_GET_ACTIVE_FIRMWARE_DETAILS_DONE,
00075     ARM_UC_PAAL_EVENT_GET_FIRMWARE_DETAILS_DONE,
00076     ARM_UC_PAAL_EVENT_GET_INSTALLER_DETAILS_DONE,
00077     ARM_UC_PAAL_EVENT_INITIALIZE_ERROR,
00078     ARM_UC_PAAL_EVENT_PREPARE_ERROR,
00079     ARM_UC_PAAL_EVENT_FIRMWARE_TOO_LARGE_ERROR,
00080     ARM_UC_PAAL_EVENT_WRITE_ERROR,
00081     ARM_UC_PAAL_EVENT_FINALIZE_ERROR,
00082     ARM_UC_PAAL_EVENT_READ_ERROR,
00083     ARM_UC_PAAL_EVENT_ACTIVATE_ERROR,
00084     ARM_UC_PAAL_EVENT_GET_ACTIVE_FIRMWARE_DETAILS_ERROR,
00085     ARM_UC_PAAL_EVENT_GET_FIRMWARE_DETAILS_ERROR,
00086     ARM_UC_PAAL_EVENT_GET_INSTALLER_DETAILS_ERROR,
00087 };
00088 
00089 /**
00090  * @brief Bitmap with supported header features.
00091  * @details The PAAL Update implementation indicates what features are
00092  *          supported. This can be used after a call to one of the GetDetails
00093  *          to see which fields have valid values and what fields should be set
00094  *          in the call to Prepare.
00095  */
00096 typedef struct _ARM_UC_PAAL_UPDATE_CAPABILITIES {
00097     uint32_t installer_arm_hash: 1;
00098     uint32_t installer_oem_hash: 1;
00099     uint32_t installer_layout: 1;
00100     uint32_t firmware_hash: 1;
00101     uint32_t firmware_hmac: 1;
00102     uint32_t firmware_campaign: 1;
00103     uint32_t firmware_version: 1;
00104     uint32_t firmware_size: 1;
00105     uint32_t reserved: 24;
00106 } ARM_UC_PAAL_UPDATE_CAPABILITIES;
00107 
00108 /**
00109  * @brief Structure definition holding API function pointers.
00110  */
00111 typedef struct _ARM_UC_PAAL_UPDATE {
00112 
00113     /**
00114      * @brief Initialize the underlying storage and set the callback handler.
00115      *
00116      * @param callback Function pointer to event handler.
00117      * @return Returns ERR_NONE on accept, and signals the event handler with
00118      *         either DONE or ERROR when complete.
00119      *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00120      */
00121     arm_uc_error_t (*Initialize)(ARM_UC_PAAL_UPDATE_SignalEvent_t callback);
00122 
00123     /**
00124      * @brief Get a bitmap indicating supported features.
00125      * @details The bitmap is used in conjunction with the firmware and
00126      *          installer details struct to indicate what fields are supported
00127      *          and which values are valid.
00128      *
00129      * @return Capability bitmap.
00130      */
00131     ARM_UC_PAAL_UPDATE_CAPABILITIES(*GetCapabilities)(void);
00132 
00133     /**
00134      * @brief Get maximum number of supported storage locations.
00135      *
00136      * @return Number of storage locations.
00137      */
00138     uint32_t (*GetMaxID)(void);
00139 
00140     /**
00141      * @brief Prepare the storage layer for a new firmware image.
00142      * @details The storage location is set up to receive an image with
00143      *          the details passed in the details struct.
00144      *
00145      * @param location Storage location ID.
00146      * @param details Pointer to a struct with firmware details.
00147      * @param buffer Temporary buffer for formatting and storing metadata.
00148      * @return Returns ERR_NONE on accept, and signals the event handler with
00149      *         either DONE or ERROR when complete.
00150      *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00151      */
00152     arm_uc_error_t (*Prepare)(uint32_t location,
00153                               const arm_uc_firmware_details_t *details,
00154                               arm_uc_buffer_t *buffer);
00155 
00156     /**
00157      * @brief Write a fragment to the indicated storage location.
00158      * @details The storage location must have been allocated using the Prepare
00159      *          call. The call is expected to write the entire fragment before
00160      *          signaling completion.
00161      *
00162      * @param location Storage location ID.
00163      * @param offset Offset in bytes to where the fragment should be written.
00164      * @param buffer Pointer to buffer struct with fragment.
00165      * @return Returns ERR_NONE on accept, and signals the event handler with
00166      *         either DONE or ERROR when complete.
00167      *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00168      */
00169     arm_uc_error_t (*Write)(uint32_t location,
00170                             uint32_t offset,
00171                             const arm_uc_buffer_t *buffer);
00172 
00173     /**
00174      * @brief Close storage location for writing and flush pending data.
00175      *
00176      * @param location Storage location ID.
00177      * @return Returns ERR_NONE on accept, and signals the event handler with
00178      *         either DONE or ERROR when complete.
00179      *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00180      */
00181     arm_uc_error_t (*Finalize)(uint32_t location);
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 (*Read)(uint32_t location,
00199                            uint32_t offset,
00200                            arm_uc_buffer_t *buffer);
00201 
00202     /**
00203      * @brief Set the firmware image in the slot to be the new active image.
00204      * @details This call is responsible for initiating the process for
00205      *          applying a new/different image. Depending on the platform this
00206      *          could be:
00207      *           * An empty call, if the installer can deduce which slot to
00208      *             choose from based on the firmware details.
00209      *           * Setting a flag to indicate which slot to use next.
00210      *           * Decompressing/decrypting/installing the firmware image on
00211      *             top of another.
00212      *
00213      * @param location Storage location ID.
00214      * @return Returns ERR_NONE on accept, and signals the event handler with
00215      *         either DONE or ERROR when complete.
00216      *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00217      */
00218     arm_uc_error_t (*Activate)(uint32_t location);
00219 
00220     /**
00221      * @brief Get firmware details for the actively running firmware.
00222      * @details This call populates the passed details struct with information
00223      *          about the currently active firmware image. Only the fields
00224      *          marked as supported in the capabilities bitmap will have valid
00225      *          values.
00226      *
00227      * @param details Pointer to firmware details struct to be populated.
00228      * @return Returns ERR_NONE on accept, and signals the event handler with
00229      *         either DONE or ERROR when complete.
00230      *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00231      */
00232     arm_uc_error_t (*GetActiveFirmwareDetails)(arm_uc_firmware_details_t *details);
00233 
00234     /**
00235      * @brief Get firmware details for the firmware image in the slot passed.
00236      * @details This call populates the passed details struct with information
00237      *          about the firmware image in the slot passed. Only the fields
00238      *          marked as supported in the capabilities bitmap will have valid
00239      *          values.
00240      *
00241      * @param details Pointer to firmware details struct to be populated.
00242      * @return Returns ERR_NONE on accept, and signals the event handler with
00243      *         either DONE or ERROR when complete.
00244      *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00245      */
00246     arm_uc_error_t (*GetFirmwareDetails)(uint32_t location,
00247                                          arm_uc_firmware_details_t *details);
00248 
00249     /**
00250      * @brief Get details for the component responsible for installation.
00251      * @details This call populates the passed details struct with information
00252      *          about the local installer. Only the fields marked as supported
00253      *          in the capabilities bitmap will have valid values. The
00254      *          installer could be the bootloader, a recovery image, or some
00255      *          other component responsible for applying the new firmware
00256      *          image.
00257      *
00258      * @param details Pointer to installer details struct to be populated.
00259      * @return Returns ERR_NONE on accept, and signals the event handler with
00260      *         either DONE or ERROR when complete.
00261      *         Returns ERR_INVALID_PARAMETER on reject, and no signal is sent.
00262      */
00263     arm_uc_error_t (*GetInstallerDetails)(arm_uc_installer_details_t *details);
00264 
00265 } ARM_UC_PAAL_UPDATE;
00266 
00267 #endif /* ARM_UC_PAAL_UPDATE_API_H */