arm_uc_source_manager.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_UC_SOURCE_MANAGER_H
00020 #define ARM_UC_SOURCE_MANAGER_H
00021 
00022 #include "update-client-common/arm_uc_common.h"
00023 #include "update-client-source/arm_uc_source.h"
00024 
00025 typedef enum {
00026     ARM_UC_SM_EVENT_NOTIFICATION,
00027     ARM_UC_SM_EVENT_MANIFEST,
00028     ARM_UC_SM_EVENT_FIRMWARE,
00029     ARM_UC_SM_EVENT_KEYTABLE,
00030     ARM_UC_SM_EVENT_ERROR,
00031     ARM_UC_SM_EVENT_ERROR_BUFFER_SIZE
00032 } ARM_UC_SM_Event_t;
00033 
00034 typedef struct _ARM_UC_SOURCE_MANAGER {
00035 
00036     /**
00037      * @brief Initialize module and register event handler.
00038      * @details The event handler is shared among all asynchronous calls.
00039      *
00040      * @param  callback Function pointer to event handler.
00041      * @return Error code.
00042      */
00043     arm_uc_error_t (*Initialize)(ARM_SOURCE_SignalEvent_t event_cb);
00044 
00045     /**
00046      * @brief Add firmware source to manager.
00047      * @details Each source is represented as a pointer to a struct, containing
00048      *          function pointers.
00049      *
00050      *          For example:
00051      *          typedef struct _ARM_UPDATE_SOURCE {
00052      *              ARM_DRIVER_VERSION     (*GetVersion)     (void);
00053      *              ARM_SOURC_CAPABILITIES (*GetCapabilities)(void);
00054      *              int32_t                (*Initialize)     (ARM_SOURCE_SignalEvent_t event);
00055      *          } ARM_UPDATE_SOURCE;
00056      *
00057      * @param source Collection of function pointers to source.
00058      * @return Error code.
00059      */
00060     arm_uc_error_t (*AddSource)(const ARM_UPDATE_SOURCE* source);
00061     arm_uc_error_t (*RemoveSource)(const ARM_UPDATE_SOURCE* source);
00062 
00063     /**
00064      * @brief Copy manifest into provided buffer.
00065      * @details Default manifest location is used. An event is generated when the
00066      *          manifest has been received.
00067      *
00068      * @param buffer Struct holding a byte array, maximum size, and actual size.
00069      *
00070      * @return Error code.
00071      */
00072     arm_uc_error_t (*GetManifest)(arm_uc_buffer_t* buffer, uint32_t offset);
00073 
00074     /**
00075      * @brief Copy manifest into provided buffer.
00076      * @details Manifest location is provided. An event is generated when the
00077      *          manifest has been received.
00078      *
00079      * @param uri Struct containing the URI to the manifest.
00080      * @param buffer Struct holding a byte array, maximum size, and actual size.
00081      *
00082      * @return Error code.
00083      */
00084     arm_uc_error_t (*GetManifestFrom)(arm_uc_uri_t* uri, arm_uc_buffer_t* buffer, uint32_t offset);
00085 
00086     /**
00087      * @brief Copy firmware fragment into provided buffer.
00088      * @details Firmware is downloaded one fragment at a time. Each call generates
00089      *          an event when the fragment has been received.
00090      *
00091      * @param uri Struct containing the URI to the manifest.
00092      * @param buffer Struct holding a byte array, maximum size, and actual size.
00093      * @param offset Firmware offset in bytes where the next fragment begins.
00094      * @return Error code.
00095      */
00096     arm_uc_error_t (*GetFirmwareFragment)(arm_uc_uri_t* uri, arm_uc_buffer_t* buffer, uint32_t offset);
00097 
00098     /**
00099      * @brief Retrieve key table and write it into provided buffer.
00100      * @details An event is generated when the manifest has been received.
00101      *
00102      * @param uri Struct containing the URI to the keytable.
00103      * @param buffer Struct holding a byte array, maximum size, and actual size.
00104      * @return Error code.
00105      */
00106     arm_uc_error_t (*GetKeytable)(arm_uc_uri_t* uri, arm_uc_buffer_t* buffer);
00107 
00108 } ARM_UC_SOURCE_MANAGER_t;
00109 
00110 extern ARM_UC_SOURCE_MANAGER_t ARM_UC_SourceManager;
00111 
00112 /**
00113  * Usage examples
00114  *
00115  * void callback(uint32_t event)
00116  * {
00117  *      switch (event)
00118  *      {
00119  *          // New manifest is available
00120  *          case ARM_UC_SM_EVENT_NOTIFICATION:
00121  *              break;
00122  *
00123  *          // Manifest received from default location
00124  *          case ARM_UC_SM_EVENT_MANIFEST:
00125  *              break;
00126  *
00127  *          // Manifest received from URL
00128  *          case ARM_UC_SM_EVENT_FIRMWARE:
00129  *              break;
00130  *
00131  *          // Firmware fragment received
00132  *          case ARM_UC_SM_EVENT_KEYTABLE:
00133  *              break;
00134  *      }
00135  * }
00136  *
00137  * void main(int)
00138  * {
00139  *      // initialize Source Manager with callback handler
00140  *      ARM_UC_SourceManager.Initialise(callback);
00141  * }
00142  *
00143  */
00144 
00145 #endif /* SOURCE_MANAGER_H */