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