arm_uc_monitor.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_MONITOR_H__
00020 #define __ARM_UPDATE_MONITOR_H__
00021 
00022 #include "update-client-common/arm_uc_types.h"
00023 #include "update-client-common/arm_uc_public.h"
00024 #include "update-client-common/arm_uc_error.h"
00025 
00026 #include <stdint.h>
00027 
00028 /**
00029  * @brief Struct containing the Monitor's capabilities.
00030  * @details state: Monitor can report the device's state.
00031  *          result: Monitor can report the update result.
00032  *          version: Monitor can report the current version.
00033  */
00034 typedef struct _ARM_MONITOR_CAPABILITIES {
00035     uint32_t state: 1;
00036     uint32_t result: 1;
00037     uint32_t version: 1;
00038     uint32_t reserved: 30;
00039 } ARM_MONITOR_CAPABILITIES;
00040 
00041 // New enums based on http://www.openmobilealliance.org/tech/profiles/lwm2m/10252.xml
00042 typedef arm_uc_update_state_t arm_uc_monitor_state_t;
00043 typedef arm_uc_update_result_t arm_uc_monitor_result_t;
00044 
00045 /**
00046  * @brief Structure definition holding API function pointers.
00047  */
00048 typedef struct _ARM_UPDATE_MONITOR {
00049 
00050     /**
00051      * @brief Get driver version.
00052      * @return Driver version.
00053      */
00054     uint32_t (*GetVersion)(void);
00055 
00056     /**
00057      * @brief Get Source capabilities.
00058      * @return Struct containing capabilites. See definition above.
00059      */
00060     ARM_MONITOR_CAPABILITIES(*GetCapabilities)(void);
00061 
00062     /**
00063      * @brief Initialize Monitor.
00064      * @return Error code.
00065      */
00066     arm_uc_error_t (*Initialize)(void (*notification_handler)(void));
00067 
00068     /**
00069      * @brief Uninitialized Monitor.
00070      * @return Error code.
00071      */
00072     arm_uc_error_t (*Uninitialize)(void);
00073 
00074     /**
00075      * @brief Send Update Client state.
00076      * @details From the OMA LWM2M Technical Specification:
00077      *
00078      *          If writing the firmware package to Package Resource is done,
00079      *          or, if the device has downloaded the firmware package from the
00080      *          Package URI the state changes to Downloaded.
00081      *
00082      *          If writing an empty string to Package Resource is done or
00083      *          writing an empty string to Package URI is done, the state
00084      *          changes to Idle.
00085      *
00086      *          When in Downloaded state, and the executable Resource Update is
00087      *          triggered, the state changes to Updating.
00088      *          If the Update Resource failed, the state returns at Downloaded.
00089      *          If performing the Update Resource was successful, the state
00090      *          changes from Updating to Idle.
00091      *
00092      * @param state Any member element of arm_uc_monitor_state_t
00093      * @return Error code.
00094      */
00095     arm_uc_error_t (*SendState)(arm_uc_monitor_state_t state);
00096 
00097     /**
00098      * @brief Send update result.
00099      * @details From the OMA LWM2M Technical Specification:
00100      *          This Resource MAY be reported by sending Observe operation.
00101      * @param result Valid results: Any member element of arm_uc_monitor_result_t.
00102      * @return Error code.
00103      */
00104     arm_uc_error_t (*SendUpdateResult)(arm_uc_monitor_result_t updateResult);
00105 
00106     /**
00107      * @brief Send current firmware name.
00108      * @details The firmware name is the SHA256 hash.
00109      *
00110      * @param name Pointer to buffer struct. Hash is stored as byte array.
00111      * @return Error code.
00112      */
00113     arm_uc_error_t (*SendName)(arm_uc_buffer_t *name);
00114 
00115     /**
00116      * @brief Send current firmware version.
00117      * @details The firmware version is the timestamp from the manifest that
00118      *          authorized the firmware.
00119      *
00120      * @param version Timestamp, 64 bit unsigned integer.
00121      * @return Error code.
00122      */
00123     arm_uc_error_t (*SendVersion)(uint64_t version);
00124 
00125     /**
00126      * @brief Set the bootloader hash.
00127      * @details The bootloader hash is a hash of the bootloader. This is
00128      *          used for tracking the version of the bootloader used.
00129      *
00130      * @param name Pointer to buffer struct. Hash is stored as byte array.
00131      * @return Error code.
00132      */
00133     arm_uc_error_t (*SetBootloaderHash)(arm_uc_buffer_t *hash);
00134 
00135     /**
00136      * @brief Set the OEM bootloader hash.
00137      * @details If the end-user has modified the bootloader the hash of the
00138      *          modified bootloader can be set here.
00139      *
00140      * @param name Pointer to buffer struct. Hash is stored as byte array.
00141      * @return Error code.
00142      */
00143     arm_uc_error_t (*SetOEMBootloaderHash)(arm_uc_buffer_t *hash);
00144 } ARM_UPDATE_MONITOR;
00145 
00146 #endif /* __ARM_UPDATE_MONITOR_H__ */