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