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_common.h"
00023 
00024 #include <stdint.h>
00025 
00026 /**
00027  * @brief Struct containing the Monitor's capabilities.
00028  * @details state: Monitor can report the device's state.
00029  *          result: Monitor can report the update result.
00030  *          version: Monitor can report the current version.
00031  */
00032 typedef struct _ARM_MONITOR_CAPABILITIES {
00033     uint32_t state: 1;
00034     uint32_t result: 1;
00035     uint32_t version: 1;
00036     uint32_t reserved: 30;
00037 } ARM_MONITOR_CAPABILITIES;
00038 
00039 /**
00040  *
00041  */
00042 typedef enum {
00043     ARM_UC_MONITOR_STATE_FIRST       = 0,
00044     ARM_UC_MONITOR_STATE_IDLE        = ARM_UC_MONITOR_STATE_FIRST,
00045     ARM_UC_MONITOR_STATE_DOWNLOADING = 1,
00046     ARM_UC_MONITOR_STATE_DOWNLOADED  = 2,
00047     ARM_UC_MONITOR_STATE_UPDATING    = 3,
00048     ARM_UC_MONITOR_STATE_LAST        = ARM_UC_MONITOR_STATE_UPDATING
00049 } arm_uc_monitor_state_t;
00050 
00051 typedef enum {
00052     ARM_UC_MONITOR_RESULT_FIRST            = 0,
00053     ARM_UC_MONITOR_RESULT_INITIAL          = ARM_UC_MONITOR_RESULT_FIRST,
00054     ARM_UC_MONITOR_RESULT_SUCCESS          = 1,
00055     ARM_UC_MONITOR_RESULT_ERROR_STORAGE    = 2,
00056     ARM_UC_MONITOR_RESULT_ERROR_MEMORY     = 3,
00057     ARM_UC_MONITOR_RESULT_ERROR_CONNECTION = 4,
00058     ARM_UC_MONITOR_RESULT_ERROR_CRC        = 5,
00059     ARM_UC_MONITOR_RESULT_ERROR_TYPE       = 6,
00060     ARM_UC_MONITOR_RESULT_ERROR_URI        = 7,
00061     ARM_UC_MONITOR_RESULT_ERROR_UPDATE     = 8,
00062     ARM_UC_MONITOR_RESULT_ERROR_HASH       = 9,
00063     ARM_UC_MONITOR_RESULT_LAST             = ARM_UC_MONITOR_RESULT_ERROR_HASH
00064 } arm_uc_monitor_result_t;
00065 
00066 /**
00067  * @brief Structure definition holding API function pointers.
00068  */
00069 typedef struct _ARM_UPDATE_MONITOR {
00070 
00071     /**
00072      * @brief Get driver version.
00073      * @return Driver version.
00074      */
00075     uint32_t (*GetVersion)(void);
00076 
00077     /**
00078      * @brief Get Source capabilities.
00079      * @return Struct containing capabilites. See definition above.
00080      */
00081     ARM_MONITOR_CAPABILITIES (*GetCapabilities)(void);
00082 
00083     /**
00084      * @brief Initialize Monitor.
00085      * @return Error code.
00086      */
00087     arm_uc_error_t (*Initialize)(void (*notification_handler)(void));
00088 
00089     /**
00090      * @brief Uninitialized Monitor.
00091      * @return Error code.
00092      */
00093     arm_uc_error_t (*Uninitialize)(void);
00094 
00095     /**
00096      * @brief Send Update Client state.
00097      * @details From the OMA LWM2M Technical Specification:
00098      *
00099      *          Indicates current state with respect to this firmware update.
00100      *          This value is set by the LWM2M Client.
00101      *          0: Idle (before downloading or after successful updating)
00102      *          1: Downloading (The data sequence is on the way)
00103      *          2: Downloaded
00104      *          3: Updating
00105      *
00106      *          If writing the firmware package to Package Resource is done,
00107      *          or, if the device has downloaded the firmware package from the
00108      *          Package URI the state changes to Downloaded.
00109      *
00110      *          If writing an empty string to Package Resource is done or
00111      *          writing an empty string to Package URI is done, the state
00112      *          changes to Idle.
00113      *
00114      *          When in Downloaded state, and the executable Resource Update is
00115      *          triggered, the state changes to Updating.
00116      *          If the Update Resource failed, the state returns at Downloaded.
00117      *          If performing the Update Resource was successful, the state
00118      *          changes from Updating to Idle.
00119      *
00120      * @param state Valid states: ARM_UC_MONITOR_STATE_IDLE
00121      *                            ARM_UC_MONITOR_STATE_DOWNLOADING
00122      *                            ARM_UC_MONITOR_STATE_DOWNLOADED
00123      *                            ARM_UC_MONITOR_STATE_UPDATING
00124      *
00125      * @return Error code.
00126      */
00127     arm_uc_error_t (*SendState)(arm_uc_monitor_state_t state);
00128 
00129     /**
00130      * @brief Send update result.
00131      * @details From the OMA LWM2M Technical Specification:
00132      *
00133      *          Contains the result of downloading or updating the firmware
00134      *          0: Initial value. Once the updating process is initiated
00135      *             (Download /Update), this Resource MUST be reset to Initial
00136      *             value.
00137      *          1: Firmware updated successfully,
00138      *          2: Not enough storage for the new firmware package.
00139      *          3. Out of memory during downloading process.
00140      *          4: Connection lost during downloading process.
00141      *          5: CRC check failure for new downloaded package.
00142      *          6: Unsupported package type.
00143      *          7: Invalid URI
00144      *          8: Firmware update failed
00145      *
00146      *          This Resource MAY be reported by sending Observe operation.
00147      *
00148      * @param result Valid results: ARM_UC_MONITOR_RESULT_INITIAL
00149      *                              ARM_UC_MONITOR_RESULT_SUCCESS
00150      *                              ARM_UC_MONITOR_RESULT_ERROR_STORAGE
00151      *                              ARM_UC_MONITOR_RESULT_ERROR_MEMORY
00152      *                              ARM_UC_MONITOR_RESULT_ERROR_CONNECTION
00153      *                              ARM_UC_MONITOR_RESULT_ERROR_CRC
00154      *                              ARM_UC_MONITOR_RESULT_ERROR_TYPE
00155      *                              ARM_UC_MONITOR_RESULT_ERROR_URI
00156      *                              ARM_UC_MONITOR_RESULT_ERROR_UPDATE
00157      *                              ARM_UC_MONITOR_RESULT_ERROR_HASH
00158      *
00159      * @return Error code.
00160      */
00161     arm_uc_error_t (*SendUpdateResult)(arm_uc_monitor_result_t updateResult);
00162 
00163     /**
00164      * @brief Send current firmware name.
00165      * @details The firmware name is the SHA256 hash.
00166      *
00167      * @param name Pointer to buffer struct. Hash is stored as byte array.
00168      * @return Error code.
00169      */
00170     arm_uc_error_t (*SendName)(arm_uc_buffer_t* name);
00171 
00172     /**
00173      * @brief Send current firmware version.
00174      * @details The firmware version is the timestamp from the manifest that
00175      *          authorized the firmware.
00176      *
00177      * @param version Timestamp, 64 bit unsigned integer.
00178      * @return Error code.
00179      */
00180     arm_uc_error_t (*SendVersion)(uint64_t version);
00181 
00182     /**
00183      * @brief Set the bootloader hash.
00184      * @details The bootloader hash is a hash of the bootloader. This is
00185      *          used for tracking the version of the bootloader used.
00186      *
00187      * @param name Pointer to buffer struct. Hash is stored as byte array.
00188      * @return Error code.
00189      */
00190     arm_uc_error_t (*SetBootloaderHash)(arm_uc_buffer_t* hash);
00191 
00192     /**
00193      * @brief Set the OEM bootloader hash.
00194      * @details If the end-user has modified the bootloader the hash of the
00195      *          modified bootloader can be set here.
00196      *
00197      * @param name Pointer to buffer struct. Hash is stored as byte array.
00198      * @return Error code.
00199      */
00200     arm_uc_error_t (*SetOEMBootloaderHash)(arm_uc_buffer_t* hash);
00201 } ARM_UPDATE_MONITOR;
00202 
00203 #endif /* __ARM_UPDATE_MONITOR_H__ */