arm_uc_firmware_manager.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_FIRMWARE_MANAGER_H
00020 #define ARM_UC_FIRMWARE_MANAGER_H
00021 
00022 #include "update-client-paal/arm_uc_paal_update_api.h"
00023 #include "update-client-common/arm_uc_common.h"
00024 
00025 typedef void (*ARM_UCFM_SignalEvent_t)(uintptr_t event);
00026 
00027 #define UCFM_MAX_BLOCK_SIZE 16
00028 
00029 typedef enum {
00030     UCFM_EVENT_INITIALIZE_DONE                   = ARM_UC_PAAL_EVENT_INITIALIZE_DONE,
00031     UCFM_EVENT_PREPARE_DONE                      = ARM_UC_PAAL_EVENT_PREPARE_DONE,
00032     UCFM_EVENT_WRITE_DONE                        = ARM_UC_PAAL_EVENT_WRITE_DONE,
00033     UCFM_EVENT_FINALIZE_DONE                     = ARM_UC_PAAL_EVENT_FINALIZE_DONE,
00034     UCFM_EVENT_ACTIVATE_DONE                     = ARM_UC_PAAL_EVENT_ACTIVATE_DONE,
00035     UCFM_EVENT_GET_ACTIVE_FIRMWARE_DETAILS_DONE  = ARM_UC_PAAL_EVENT_GET_ACTIVE_FIRMWARE_DETAILS_DONE,
00036     UCFM_EVENT_GET_FIRMWARE_DETAILS_DONE         = ARM_UC_PAAL_EVENT_GET_FIRMWARE_DETAILS_DONE,
00037     UCFM_EVENT_GET_INSTALLER_DETAILS_DONE        = ARM_UC_PAAL_EVENT_GET_INSTALLER_DETAILS_DONE,
00038     UCFM_EVENT_INITIALIZE_ERROR                  = ARM_UC_PAAL_EVENT_INITIALIZE_ERROR,
00039     UCFM_EVENT_PREPARE_ERROR                     = ARM_UC_PAAL_EVENT_PREPARE_ERROR,
00040     UCFM_EVENT_FIRMWARE_TOO_LARGE_ERROR          = ARM_UC_PAAL_EVENT_FIRMWARE_TOO_LARGE_ERROR,
00041     UCFM_EVENT_WRITE_ERROR                       = ARM_UC_PAAL_EVENT_WRITE_ERROR,
00042     UCFM_EVENT_FINALIZE_ERROR                    = ARM_UC_PAAL_EVENT_FINALIZE_ERROR,
00043     UCFM_EVENT_ACTIVATE_ERROR                    = ARM_UC_PAAL_EVENT_ACTIVATE_ERROR,
00044     UCFM_EVENT_GET_ACTIVE_FIRMWARE_DETAILS_ERROR = ARM_UC_PAAL_EVENT_GET_ACTIVE_FIRMWARE_DETAILS_ERROR,
00045     UCFM_EVENT_GET_FIRMWARE_DETAILS_ERROR        = ARM_UC_PAAL_EVENT_GET_FIRMWARE_DETAILS_ERROR,
00046     UCFM_EVENT_GET_INSTALLER_DETAILS_ERROR       = ARM_UC_PAAL_EVENT_GET_INSTALLER_DETAILS_ERROR,
00047     UCFM_EVENT_FINALIZE_INVALID_HASH_ERROR
00048 } ARM_UCFM_Event_t;
00049 
00050 typedef enum {
00051     UCFM_MODE_UNINIT,
00052     UCFM_MODE_NONE_SHA_256,
00053     UCFM_MODE_AES_CTR_128_SHA_256,
00054     UCFM_MODE_AES_CTR_256_SHA_256
00055 } ARM_UCFM_mode_t;
00056 
00057 typedef struct _ARM_UCFM_Setup {
00058     ARM_UCFM_mode_t mode;
00059     arm_uc_buffer_t *key;
00060     arm_uc_buffer_t *iv;
00061     arm_uc_buffer_t *hash;
00062     uint32_t package_id;
00063     uint32_t package_size;
00064 } ARM_UCFM_Setup_t;
00065 
00066 typedef struct _ARM_UC_FIRMWARE_MANAGER {
00067     /**
00068      * @brief Initialization function.
00069      * @param handler Function pointer to the event handler.
00070      * @return Error code.
00071      */
00072     arm_uc_error_t (*Initialize)(ARM_UCFM_SignalEvent_t handler);
00073 
00074     /**
00075      * @brief Setup new package to be processed.
00076      * @details Generates UCFM_EVENT_PREPARE_DONE event if call is accepted.
00077      * @param configuration Struct containing configuration data.
00078      * @param buffer Scratch pad for temporary storage.
00079      * @return Error code.
00080      */
00081     arm_uc_error_t (*Prepare)(ARM_UCFM_Setup_t *configuration,
00082                               const arm_uc_firmware_details_t *details,
00083                               arm_uc_buffer_t *buffer);
00084 
00085     /**
00086      * @brief Function for adding a package fragment.
00087      * @details Generates either UCFM_EVENT_WRITE_DONE or UCFM_EVENT_WRITE_ERROR.
00088      * @details Fragments are processed based on the mode set in the configure
00089      *          struct. This can include decryption, validation, and storage.
00090      * @param input Buffer struct.
00091      * @return Error code.
00092      */
00093     arm_uc_error_t (*Write)(const arm_uc_buffer_t *input);
00094 
00095     /**
00096      * @brief Function for finalizing the current package.
00097      * @details Flushes all write buffers and initiates the hash validation.
00098      *          Generates UCFM_EVENT_FINALIZE_DONE, UCFM_EVENT_FINALIZE_ERROR
00099      *          or UCFM_EVENT_FINALIZE_INVALID_HASH_ERROR.
00100      *          To speed up hash computation, this function accepts two buffer
00101      *          arguments ('front' and 'back):
00102      *          - if both 'front' and 'back' are NULL, a small internal buffer is
00103      *            used. Note that this can have an adverse impact on performance.
00104      *          - if only 'front' isn't NULL, 'front' will be used instead of the
00105      *            internal buffer. If 'front' is a large buffer, a performance
00106      *            improvement is likely to be observed.
00107      *          - if both 'front' and 'back' are not NULL, the code will initiate
00108      *            a read in the back buffer, hash the data in the front buffer,
00109      *            then swap the buffers. This configuration should provide the
00110      *            best performance (but also uses the most memory).
00111      *          It is an error to call this function with 'front' equal to NULL
00112      *          and a non-null value for 'back'.
00113      *          NOTE: the buffer size must be a multiple of ARM_UC_SHA256_SIZE.
00114      * @return Error code.
00115      */
00116     arm_uc_error_t (*Finalize)(arm_uc_buffer_t *front, arm_uc_buffer_t *back);
00117 
00118     /**
00119      * @brief Function for activating or installing the current package.
00120      * @details Activates or installs the current package.
00121      *          In the future this function might take the image ID as
00122      *          paramter.
00123      * @param location ID of slot to be activated.
00124      * @return Error code.
00125      */
00126     arm_uc_error_t (*Activate)(uint32_t location);
00127 
00128     /**
00129      * @brief Get the firmware details for the currently active image.
00130      *
00131      * @param details Pointer to firmware details struct.
00132      * @return Error code.
00133      */
00134     arm_uc_error_t (*GetActiveFirmwareDetails)(arm_uc_firmware_details_t *details);
00135 
00136     /**
00137      * @brief Get the firmware details for the specified location.
00138      *
00139      * @param location Location ID to get details for.
00140      * @param details Pointer to firmware details struct.
00141      * @return Error code.
00142      */
00143     arm_uc_error_t (*GetFirmwareDetails)(uint32_t location,
00144                                          arm_uc_firmware_details_t *details);
00145 
00146     /**
00147      * @brief Get the installer details.
00148      * @details Installer is responsible for applying the firmware image.
00149      *
00150      * @param details Pointer to installer details struct.
00151      * @return Error code.
00152      */
00153     arm_uc_error_t (*GetInstallerDetails)(arm_uc_installer_details_t *details);
00154 
00155 } ARM_UC_FIRMWARE_MANAGER_t;
00156 
00157 extern ARM_UC_FIRMWARE_MANAGER_t ARM_UC_FirmwareManager;
00158 
00159 #endif // ARM_UC_FIRMWARE_MANAGER_H