arm_uc_control_center.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_UPDATE_CONTROL_CENTER_H
00020 #define ARM_UPDATE_CONTROL_CENTER_H
00021 
00022 #include "update-client-monitor/arm_uc_monitor.h"
00023 #include "update-client-common/arm_uc_types.h"
00024 #include "update-client-common/arm_uc_error.h"
00025 #include "update-client-common/arm_uc_public.h"
00026 #include "update-client-common/arm_uc_scheduler.h"
00027 
00028 #include <stdint.h>
00029 
00030 typedef enum {
00031     ARM_UCCC_EVENT_AUTHORIZE_DOWNLOAD,
00032     ARM_UCCC_EVENT_AUTHORIZE_INSTALL,
00033     ARM_UCCC_EVENT_MONITOR_SEND_DONE,
00034 } arm_uc_contro_center_event_t;
00035 
00036 /**
00037  * @brief Initialize Control Center.
00038  *
00039  * @param callback Event handler to signal authorizations.
00040  * @return Error code.
00041  */
00042 arm_uc_error_t ARM_UC_ControlCenter_Initialize(void (*callback)(uintptr_t));
00043 
00044 /**
00045  * @brief Add monitor struct for sending status and results remotely.
00046  * @details Update Client call for adding remote monitor.
00047  *
00048  * @param monitor Pointer to an ARM_UPDATE_MONITOR struct.
00049  * @return Error code.
00050  */
00051 arm_uc_error_t ARM_UC_ControlCenter_AddMonitor(const ARM_UPDATE_MONITOR *monitor);
00052 
00053 /**
00054  * @brief Set callback for receiving download progress.
00055  * @details User application call for setting callback handler.
00056  *          The callback function takes the progreess in percent as argument.
00057  *
00058  * @param callback Function pointer to the progress function.
00059  * @return Error code.
00060  */
00061 arm_uc_error_t ARM_UC_ControlCenter_SetProgressHandler(void (*callback)(uint32_t progress, uint32_t total));
00062 
00063 /**
00064  * @brief Set callback function for authorizing requests.
00065  * @details User application call for setting callback handler.
00066  *          The callback function takes an enum request and an authorization
00067  *          function pointer. To authorize the given request, the caller
00068  *          invokes the authorization function.
00069  *
00070  * @param callback Function pointer to the authorization function.
00071  * @return Error code.
00072  */
00073 arm_uc_error_t ARM_UC_ControlCenter_SetAuthorityHandler(void (*callback)(int32_t));
00074 
00075 /**
00076  * @brief Request authorization from Control Center.
00077  * @details Update Client call for asking user application for permission.
00078  *
00079  * @param type Request type.
00080  * @return Error code.
00081  */
00082 arm_uc_error_t ARM_UC_ControlCenter_GetAuthorization(arm_uc_request_t request);
00083 
00084 /**
00085  * @brief Authorize request.
00086  * @details User application call for authorizing request.
00087  *
00088  * @param request Request type. Must match the type in callback function.
00089  */
00090 arm_uc_error_t ARM_UC_ControlCenter_Authorize(arm_uc_request_t request);
00091 
00092 /**
00093  * @brief Override update authorization handler.
00094  * @details Force download and update to progress regardless of authorization
00095  *          handler. This function is used for unblocking an update in a buggy
00096  *          application.
00097  */
00098 void ARM_UC_ControlCenter_OverrideAuthorization(void);
00099 
00100 /**
00101  * @brief Report download progress.
00102  * @details Update Client call for informing the Control Center about the
00103  *          current download progress. The Control Center will send this to the
00104  *          appication handler and the monitor if either/both are attached.
00105  *
00106  * @param progress Bytes already downloaded.
00107  * @param total Total bytes in download.
00108  * @return Error code.
00109  */
00110 arm_uc_error_t ARM_UC_ControlCenter_ReportProgress(uint32_t progress, uint32_t total);
00111 
00112 /**
00113  * @brief Send Update Client state.
00114  * @details Update Client call for informing the Control Center about the
00115  *          current state. The Control Center will send this to the monitor.
00116  *
00117  * @param state Valid states: Any of type arm_uc_monitor_state_t.
00118  * @return Error code.
00119  */
00120 arm_uc_error_t ARM_UC_ControlCenter_ReportState(arm_uc_monitor_state_t state);
00121 
00122 /**
00123  * @brief Set update result.
00124  * @details Update Client call for informing the Control Center about the
00125  *          latest update result. The Control Center will send this to the monitor.
00126  *
00127  * @param result Valid results: Any of type arm_uc_monitor_result_t
00128  * @return Error code.
00129  */
00130 arm_uc_error_t ARM_UC_ControlCenter_ReportUpdateResult(arm_uc_monitor_result_t updateResult);
00131 
00132 /**
00133  * @brief Set current firmware name.
00134  * @details Update Client call for informing the Control Center about the
00135  *          current firmware name. The Control Center will send this to the
00136  *          monitor. The firmware name is the SHA256 hash.
00137  *
00138  * @param name Pointer to buffer struct. Hash is stored as byte array.
00139  * @return Error code.
00140  */
00141 arm_uc_error_t ARM_UC_ControlCenter_ReportName(arm_uc_buffer_t *name);
00142 
00143 /**
00144  * @brief Set current firmware version.
00145  * @details Update Client call for informing the Control Center about the
00146  *          current firmware version. The Control Center will send this to the
00147  *          monitor. The firmware version is the manifest timestamp that
00148  *          authorized the installation.
00149  *
00150  * @param version Timestamp, 64 bit unsigned integer.
00151  * @return Error code.
00152  */
00153 arm_uc_error_t ARM_UC_ControlCenter_ReportVersion(uint64_t version);
00154 
00155 /**
00156  * @brief Send bootloader hash to monitor.
00157  * @details The bootloader hash is a hash of the bootloader. This is
00158  *          used for tracking the version of the bootloader used.
00159  *
00160  * @param name Pointer to buffer struct. Hash is stored as byte array.
00161  * @return Error code.
00162  */
00163 arm_uc_error_t ARM_UC_ControlCenter_ReportBootloaderHash(arm_uc_buffer_t *hash);
00164 
00165 /**
00166  * @brief Send the OEM bootloader hash to monitor.
00167  * @details If the end-user has modified the bootloader the hash of the
00168  *          modified bootloader can be set here.
00169  *
00170  * @param name Pointer to buffer struct. Hash is stored as byte array.
00171  * @return Error code.
00172  */
00173 arm_uc_error_t ARM_UC_ControlCenter_ReportOEMBootloaderHash(arm_uc_buffer_t *hash);
00174 
00175 #endif // __ARM_UPDATE_CONTROL_CENTER_H__