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