arm_uc_source.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_SOURCE_H__
00020 #define __ARM_UPDATE_SOURCE_H__
00021 
00022 #include "update-client-common/arm_uc_common.h"
00023 
00024 #include <stdint.h>
00025 
00026 /**
00027  * @brief Struct containing the Source's capabilities.
00028  * @details notify: Source can notify about new manifests.
00029  *          manifest_default: Source can download manifest from default location.
00030  *          manifest_url: Source can download manifest from URL.
00031  *          firmware: Source can download firmware from URL.
00032  */
00033 typedef struct _ARM_SOURCE_CAPABILITIES {
00034     uint32_t notify: 1;
00035     uint32_t manifest_default: 1;
00036     uint32_t manifest_url: 1;
00037     uint32_t firmware: 1;
00038     uint32_t keytable: 1;
00039     uint32_t reserved: 27;
00040 } ARM_SOURCE_CAPABILITIES;
00041 
00042 /**
00043  * @brief Events passed to event handler.
00044  * @details EVENT_NOTIFICATION: New manifest is available.
00045  *          EVENT_MANIFEST: Manifest retrieved.
00046  *          EVENT_FIRMWARE: Firmware fragment retrieved.
00047  */
00048 typedef enum _ARM_SOURCE_EVENT {
00049     EVENT_NOTIFICATION,
00050     EVENT_MANIFEST,
00051     EVENT_FIRMWARE,
00052     EVENT_KEYTABLE,
00053     EVENT_ERROR,
00054     EVENT_ERROR_BUFFER_SIZE
00055 } ARM_SOURCE_EVENT;
00056 
00057 /**
00058  * @brief Prototype for event handler.
00059  */
00060 typedef void (*ARM_SOURCE_SignalEvent_t)(uint32_t event);
00061 
00062 /**
00063  * @brief Structure definition holding API function pointers.
00064  */
00065 typedef struct _ARM_UPDATE_SOURCE {
00066 
00067     /**
00068      * @brief Get driver version.
00069      * @return Driver version.
00070      */
00071     uint32_t (*GetVersion)(void);
00072 
00073     /**
00074      * @brief Get Source capabilities.
00075      * @return Struct containing capabilites. See definition above.
00076      */
00077     ARM_SOURCE_CAPABILITIES (*GetCapabilities)(void);
00078 
00079     /**
00080      * @brief Initialize Source.
00081      * @details Function pointer to event handler is passed as argument.
00082      *
00083      * @param cb_event Function pointer to event handler. See events above.
00084      * @return Error code.
00085      */
00086     arm_uc_error_t (*Initialize)(ARM_SOURCE_SignalEvent_t cb_event);
00087 
00088     /**
00089      * @brief Uninitialized Source.
00090      * @return Error code.
00091      */
00092     arm_uc_error_t (*Uninitialize)(void);
00093 
00094     /**
00095      * @brief Cost estimation for retrieving manifest from the default location.
00096      * @details The estimation can vary over time and should not be cached too long.
00097      *          0x00000000 - The manifest is already downloaded.
00098      *          0xFFFFFFFF - Cannot retrieve manifest from this Source.
00099      *
00100      * @param cost Pointer to variable for the return value.
00101      * @return Error code.
00102      */
00103     arm_uc_error_t (*GetManifestDefaultCost)(uint32_t* cost);
00104 
00105     /**
00106      * @brief Cost estimation for retrieving manifest from URL.
00107      * @details The estimation can vary over time and should not be cached too long.
00108      *          0x00000000 - The manifest is already downloaded.
00109      *          0xFFFFFFFF - Cannot retrieve manifest from this Source.
00110      *
00111      * @param uri URI struct with manifest location.
00112      * @param cost Pointer to variable for the return value.
00113      * @return Error code.
00114      */
00115     arm_uc_error_t (*GetManifestURLCost)(arm_uc_uri_t* uri, uint32_t* cost);
00116 
00117     /**
00118      * @brief Cost estimation for retrieving firmware from URL.
00119      * @details The estimation can vary over time and should not be cached too long.
00120      *          0x00000000 - The firmware is already downloaded.
00121      *          0xFFFFFFFF - Cannot retrieve firmware from this Source.
00122      *
00123      * @param uri URI struct with firmware location.
00124      * @param cost Pointer to variable for the return value.
00125      * @return Error code.
00126      */
00127     arm_uc_error_t (*GetFirmwareURLCost)(arm_uc_uri_t* uri, uint32_t* cost);
00128 
00129     /**
00130      * @brief Cost estimation for retrieving key table from URL.
00131      * @details The estimation can vary over time and should not be cached too long.
00132      *          0x00000000 - The firmware is already downloaded.
00133      *          0xFFFFFFFF - Cannot retrieve firmware from this Source.
00134      *
00135      * @param uri URI struct with keytable location.
00136      * @param cost Pointer to variable for the return value.
00137      * @return Error code.
00138      */
00139     arm_uc_error_t (*GetKeytableURLCost)(arm_uc_uri_t* uri, uint32_t* cost);
00140 
00141     /**
00142      * @brief Retrieve manifest from the default location.
00143      * @details Manifest is stored in supplied buffer.
00144      *          Event is generated once manifest is in buffer.
00145      *
00146      * @param buffer Struct containing byte array, maximum size, and actual size.
00147      * @param offset Manifest offset in bytes where the requested fragment begins.
00148      * @return Error code.
00149      */
00150     arm_uc_error_t (*GetManifestDefault)(arm_uc_buffer_t* buffer, uint32_t offset);
00151 
00152     /**
00153      * @brief Retrieve manifest from URL.
00154      * @details Manifest is stored in supplied buffer.
00155      *          Event is generated once manifest is in buffer.
00156      *
00157      * @param uri URI struct with manifest location.
00158      * @param buffer Struct containing byte array, maximum size, and actual size.
00159      * @param offset Manifest offset in bytes where the requested fragment begins.
00160      *
00161      * @return Error code.
00162      */
00163     arm_uc_error_t (*GetManifestURL)(arm_uc_uri_t* uri, arm_uc_buffer_t* buffer, uint32_t offset);
00164 
00165     /**
00166      * @brief Retrieve firmware fragment.
00167      * @details Firmware fragment is stored in supplied buffer.
00168      *          Event is generated once fragment is in buffer.
00169      *
00170      * @param uri URI struct with firmware location.
00171      * @param buffer Struct containing byte array, maximum size, and actual size.
00172      * @param offset Firmware offset to retrieve fragment from.
00173      * @return Error code.
00174      */
00175     arm_uc_error_t (*GetFirmwareFragment)(arm_uc_uri_t* uri, arm_uc_buffer_t* buffer, uint32_t offset);
00176 
00177     /**
00178      * @brief Retrieve a key table from a URL.
00179      * @details Key table is stored in supplied buffer.
00180      *          Event is generated once fragment is in buffer.
00181      *
00182      * @param uri URI struct with keytable location.
00183      * @param buffer Struct containing byte array, maximum size, and actual size.
00184      * @return Error code.
00185      */
00186     arm_uc_error_t (*GetKeytableURL)(arm_uc_uri_t* uri, arm_uc_buffer_t* buffer);
00187 
00188 } ARM_UPDATE_SOURCE;
00189 
00190 #endif /* __ARM_UPDATE_SOURCE_H__ */