arm_uc_public.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_COMMON_PUBLIC_H
00020 #define ARM_UPDATE_COMMON_PUBLIC_H
00021 
00022 #include <stdint.h>
00023 #include <stdbool.h>
00024 
00025 #define ARM_UC_MAJOR_VERSION 1
00026 #define ARM_UC_MINOR_VERSION 4
00027 #define ARM_UC_PATCH_VERSION 1
00028 
00029 #define ARM_UC_ENCODE_VERSION_INT(major, minor, patch) ((major)*100000 + (minor)*1000 + (patch))
00030 #define ARM_UC_ENCODE_VERSION_STR(major, minor, patch) "Update Client " #major "." #minor "." #patch
00031 
00032 #define ARM_UC_VERSION_STR ARM_UC_ENCODE_VERSION_STR(ARM_UC_MAJOR_VERSION, ARM_UC_MINOR_VERSION, ARM_UC_PATCH_VERSION)
00033 #define ARM_UC_VERSION_INT ARM_UC_ENCODE_VERSION_INT(ARM_UC_MAJOR_VERSION, ARM_UC_MINOR_VERSION, ARM_UC_PATCH_VERSION)
00034 
00035 #ifndef ARM_UPDATE_CLIENT_VERSION
00036 #define ARM_UPDATE_CLIENT_VERSION ARM_UC_VERSION_STR
00037 #endif
00038 
00039 #ifndef ARM_UPDATE_CLIENT_VERSION_VALUE
00040 #define ARM_UPDATE_CLIENT_VERSION_VALUE ARM_UC_VERSION_INT
00041 #endif
00042 
00043 /**
00044  * Public error codes for the Update Client.
00045  *
00046  * When modifying the error codes, you must also update the respective
00047  * codes in MbedCloudClient.h and UpdateClient.h in mbed-cloud-client
00048  */
00049 enum {
00050     ARM_UC_WARNING,
00051     ARM_UC_WARNING_CERTIFICATE_NOT_FOUND,
00052     ARM_UC_WARNING_IDENTITY_NOT_FOUND,
00053     ARM_UC_WARNING_VENDOR_MISMATCH,
00054     ARM_UC_WARNING_CLASS_MISMATCH,
00055     ARM_UC_WARNING_DEVICE_MISMATCH,
00056     ARM_UC_WARNING_CERTIFICATE_INVALID,
00057     ARM_UC_WARNING_SIGNATURE_INVALID,
00058     ARM_UC_WARNING_BAD_KEYTABLE,
00059     ARM_UC_WARNING_URI_NOT_FOUND,
00060     ARM_UC_WARNING_ROLLBACK_PROTECTION,
00061     ARM_UC_WARNING_UNKNOWN,
00062     ARM_UC_ERROR,
00063     ARM_UC_ERROR_WRITE_TO_STORAGE,
00064     ARM_UC_ERROR_INVALID_HASH,
00065     ARM_UC_ERROR_CONNECTION,
00066     ARM_UC_FATAL,
00067     ARM_UC_UNKNOWN
00068 };
00069 
00070 /**
00071  * Public update requests
00072  */
00073 typedef enum {
00074     ARM_UCCC_REQUEST_INVALID,
00075     ARM_UCCC_REQUEST_DOWNLOAD,
00076     ARM_UCCC_REQUEST_INSTALL,
00077 } arm_uc_request_t;
00078 
00079 /**
00080  * New State & Result -enums based on http://www.openmobilealliance.org/tech/profiles/lwm2m/10252.xml
00081  */
00082 
00083 /**
00084  *  UPDATE STATE.
00085  *
00086  *      This enumeration lists the possible states of an Update Process finite state machine (FSM).
00087  *
00088  *      ARM_UC_UPDATE_STATE_UNINITIALISED
00089  *
00090  *          This is always the initial state of the FSM. All operations and events are ignored
00091  *            until the FSM has been initialized, at which point it transitions to the IDLE state.
00092  *
00093  *            UNINITIALISED {Initialize} -> IDLE
00094  *
00095  *      ARM_UC_UPDATE_STATE_IDLE
00096  *
00097  *          This is the state after initialization, but before an update has been initiated. Once
00098  *            an update has been started, the FSM state will transition to the following states in
00099  *            sequence.
00100  *
00101  *            IDLE {BeginUpdate} -> PROCESSING_MANIFEST
00102  *
00103  *          If at any point or state the update process fails, and a failure event is generated,
00104  *            the state will be reset to the default fallback state of IDLE.
00105  *
00106  *            <ANY_ACTIVE_STATE> {Fail} -> IDLE
00107  *
00108  *      ARM_UC_UPDATE_STATE_PROCESSING_MANIFEST
00109  *
00110  *          Once the manifest is received, it is checked for validity, and a request is made for
00111  *            download approval from the application.
00112  *
00113  *            PROCESSING_MANIFEST {ManifestProcessingDone} -> AWAITING_DOWNLOAD_APPROVAL
00114  *
00115  *      ARM_UC_UPDATE_STATE_AWAITING_DOWNLOAD_APPROVAL
00116  *
00117  *          This state is necessary to avoid interfering with possibly critical operations being
00118  *          undertaken by the application.
00119  *
00120  *            AWAITING_DOWNLOAD_APPROVAL {Approved} -> DOWNLOADING_UPDATE
00121  *            AWAITING_DOWNLOAD_APPROVAL {NotApproved} -> IDLE
00122  *
00123  *      ARM_UC_UPDATE_STATE_DOWNLOADING_UPDATE
00124  *
00125  *          After approval, the download begins. Once this completes and the full package has been
00126  *            downloaded and stored, the FSM requests approval for installation of the package.
00127  *
00128  *            DOWNLOADING_UPDATE {DownloadingDone} -> AWAITING_INSTALL_APPROVAL
00129  *
00130  *      ARM_UC_UPDATE_STATE_AWAITING_INSTALL_APPROVAL
00131  *
00132  *          Similar considerations apply as for ARM_UC_UPDATE_STATE_AWAITING_DOWNLOAD_APPROVAL above,
00133  *            but in this case the device will additionally reboot after installation has completed.
00134  *
00135  *            AWAITING_INSTALL_APPROVAL {Approved} -> INSTALLING_UPDATE
00136  *            AWAITING_INSTALL_APPROVAL {NotApproved} -> IDLE
00137  *
00138  *      ARM_UC_UPDATE_STATE_INSTALLING_UPDATE
00139  *
00140  *          Once the update has been installed, the device will reboot in order to start running
00141  *            with the newly installed download.
00142  *
00143  *            INSTALLING_UPDATE {InstallDone} -> REBOOTING
00144  *
00145  *      ARM_UC_UPDATE_STATE_REBOOTING
00146  *
00147  *          After a reboot the FSM will start up in the UNINITIALISED state.
00148  *
00149  *            REBOOTING {Rebooted} -> UNINITIALISED
00150  *
00151  */
00152 typedef enum {
00153     ARM_UC_UPDATE_STATE_FIRST                                  = 0,
00154     ARM_UC_UPDATE_STATE_UNINITIALISED                          = ARM_UC_UPDATE_STATE_FIRST,
00155     ARM_UC_UPDATE_STATE_IDLE                                   = 1,
00156     ARM_UC_UPDATE_STATE_PROCESSING_MANIFEST                    = 2,
00157     ARM_UC_UPDATE_STATE_AWAITING_DOWNLOAD_APPROVAL             = 3,
00158     ARM_UC_UPDATE_STATE_DOWNLOADING_UPDATE                     = 4,
00159     ARM_UC_UPDATE_STATE_DOWNLOADED_UPDATE                      = 5,
00160     ARM_UC_UPDATE_STATE_AWAITING_INSTALL_APPROVAL              = 6,
00161     ARM_UC_UPDATE_STATE_INSTALLING_UPDATE                      = 7,
00162     ARM_UC_UPDATE_STATE_REBOOTING                              = 8,
00163     ARM_UC_UPDATE_STATE_LAST                                   = ARM_UC_UPDATE_STATE_REBOOTING
00164 } arm_uc_update_state_t;
00165 
00166 /**
00167  * UPDATE RESULT.
00168  *
00169  *      Update operations can either succeed or fail. Various possible failures are given here.
00170  *        Where any particular actual failure is not covered by a specific identifying error case,
00171  *        it will be classified as a NONSPECIFIC_ERROR.
00172  *
00173  *      ARM_UC_UPDATE_RESULT_UPDATE_ defines result codes general to the update process and not covered
00174  *        by the more specific result codes following. Within the ARM_UC_UPDATE_RESULT_UPDATE_ range,
00175  *        the result code can identify varying levels of specificity.
00176  *
00177  *      ARM_UC_UPDATE_RESULT_UPDATE_NONSPECIFIC_SYSTEM_ERROR defines an error result code that
00178  *        indicates an error which cannot be directly addressed by the customer, but must be reported
00179  *        to Arm for further examination.
00180  *
00181  *      ARM_UC_UPDATE_RESULT_MANIFEST_ codes indicate results related to manifest processing during
00182  *        the update process.
00183  *
00184  *      ARM_UC_UPDATE_RESULT_FETCHER_ codes indicate results related to fetching of updates from the
00185  *        cloud service.
00186  *
00187  *      ARM_UC_UPDATE_RESULT_PROCESSOR_ codes indicate results related to processing of updates fetched
00188  *        from the cloud service. Processing entails some manipulation of the update in such a way that
00189  *        it is made suitable for use by the device. This could be decryption, decompression, delta
00190  *        reconstruction etc.
00191  *
00192  *      ARM_UC_UPDATE_RESULT_WRITER_ codes indicate results related to writing or storing of the update
00193  *        to some medium necessary for further use by the device, eg flash or SD card.
00194  */
00195 
00196 typedef enum {
00197     // General conditions.
00198     // -------------------
00199     ARM_UC_UPDATE_RESULT_UPDATE_FIRST                          = 100,
00200     ARM_UC_UPDATE_RESULT_UPDATE_SUCCEEDED                        = ARM_UC_UPDATE_RESULT_UPDATE_FIRST,
00201     ARM_UC_UPDATE_RESULT_UPDATE_NONSPECIFIC_NETWORK_ERROR      = 101,
00202     ARM_UC_UPDATE_RESULT_UPDATE_NONSPECIFIC_VALIDITY_ERROR     = 102,
00203     ARM_UC_UPDATE_RESULT_UPDATE_NONSPECIFIC_SYSTEM_ERROR       = 103,
00204     ARM_UC_UPDATE_RESULT_UPDATE_LAST                           = ARM_UC_UPDATE_RESULT_UPDATE_NONSPECIFIC_SYSTEM_ERROR,
00205 
00206     // Manifest-specific conditions.
00207     // -----------------------------
00208     ARM_UC_UPDATE_RESULT_MANIFEST_FIRST                        = 200,
00209     ARM_UC_UPDATE_RESULT_MANIFEST_NONSPECIFIC_ERROR            = ARM_UC_UPDATE_RESULT_MANIFEST_FIRST,
00210     ARM_UC_UPDATE_RESULT_MANIFEST_NONSPECIFIC_NETWORK_ERROR    = 201,
00211     ARM_UC_UPDATE_RESULT_MANIFEST_NETWORK_TIMEOUT              = 202,
00212     ARM_UC_UPDATE_RESULT_MANIFEST_NETWORK_CONNECTION_FAILURE   = 203,
00213     ARM_UC_UPDATE_RESULT_MANIFEST_DNS_LOOKUP_FAILURE           = 204,
00214     ARM_UC_UPDATE_RESULT_MANIFEST_NETWORK_CONNECTION_LOSS      = 205,
00215     ARM_UC_UPDATE_RESULT_MANIFEST_NOT_FOUND                    = 206,
00216     ARM_UC_UPDATE_RESULT_MANIFEST_INTEGRITY_CHECK_FAILED       = 207,
00217     ARM_UC_UPDATE_RESULT_MANIFEST_CERTIFICATE_NOT_FOUND        = 208,
00218     ARM_UC_UPDATE_RESULT_MANIFEST_INVALID_CERTIFICATE          = 209,
00219     ARM_UC_UPDATE_RESULT_MANIFEST_INVALID_SIGNATURE            = 210,
00220     ARM_UC_UPDATE_RESULT_MANIFEST_DEPENDENT_MANIFEST_NOT_FOUND = 211,
00221     ARM_UC_UPDATE_RESULT_MANIFEST_ALREADY_PROCESSING_ERROR     = 212,
00222     ARM_UC_UPDATE_RESULT_MANIFEST_RESOURCE_ALREADY_PRESENT_ERROR = 213,
00223     ARM_UC_UPDATE_RESULT_MANIFEST_UNSUPPORTED_MANIFEST_VERSION = 214,
00224     ARM_UC_UPDATE_RESULT_MANIFEST_WRONG_VENDOR_ID              = 215,
00225     ARM_UC_UPDATE_RESULT_MANIFEST_WRONG_CLASS_ID               = 216,
00226     ARM_UC_UPDATE_RESULT_MANIFEST_INVALID_MANIFEST_SIZE        = 217,
00227     ARM_UC_UPDATE_RESULT_MANIFEST_INVALID_MANIFEST_FORMAT      = 218,
00228     ARM_UC_UPDATE_RESULT_MANIFEST_INVALID_CRYPTO_MODE          = 219,
00229     ARM_UC_UPDATE_RESULT_MANIFEST_MISSING_FIELD                = 220,
00230     ARM_UC_UPDATE_RESULT_MANIFEST_ROLLBACK_PROTECTION          = 221,
00231     ARM_UC_UPDATE_RESULT_MANIFEST_MISSING_ITEM                 = 222,
00232     ARM_UC_UPDATE_RESULT_MANIFEST_CORRUPTED_KEYTABLE           = 223,
00233     ARM_UC_UPDATE_RESULT_MANIFEST_INVALID_KEYTABLE_ENCODING    = 224,
00234     ARM_UC_UPDATE_RESULT_MANIFEST_INSUFFICIENT_STORAGE_SPACE   = 225,
00235     ARM_UC_UPDATE_RESULT_MANIFEST_INSUFFICIENT_MEMORY_SPACE    = 226,
00236     ARM_UC_UPDATE_RESULT_MANIFEST_WRITE_FAILURE                = 227,
00237     ARM_UC_UPDATE_RESULT_MANIFEST_LAST                         = ARM_UC_UPDATE_RESULT_MANIFEST_WRITE_FAILURE,
00238 
00239     // Fetcher-specific conditions.
00240     // ----------------------------
00241     ARM_UC_UPDATE_RESULT_FETCHER_FIRST                         = 300,
00242     ARM_UC_UPDATE_RESULT_FETCHER_NONSPECIFIC_ERROR             = ARM_UC_UPDATE_RESULT_FETCHER_FIRST,
00243     ARM_UC_UPDATE_RESULT_FETCHER_NONSPECIFIC_NETWORK_ERROR     = 301,
00244     ARM_UC_UPDATE_RESULT_FETCHER_NO_ROUTE_AVAILABLE            = 302,
00245     ARM_UC_UPDATE_RESULT_FETCHER_NETWORK_TIMEOUT               = 303,
00246     ARM_UC_UPDATE_RESULT_FETCHER_NETWORK_CONNECTION_FAILURE    = 304,
00247     ARM_UC_UPDATE_RESULT_FETCHER_DNS_LOOKUP_FAILURE            = 305,
00248     ARM_UC_UPDATE_RESULT_FETCHER_NETWORK_CONNECTION_LOSS       = 306,
00249     ARM_UC_UPDATE_RESULT_FETCHER_INVALID_RESOURCE_URI          = 307,
00250     ARM_UC_UPDATE_RESULT_FETCHER_INVALID_REQUEST_TYPE          = 308,
00251     ARM_UC_UPDATE_RESULT_FETCHER_INTEGRITY_CHECK_FAILED        = 309,
00252     ARM_UC_UPDATE_RESULT_FETCHER_USER_DEFINED_ERROR_1          = 310,
00253     ARM_UC_UPDATE_RESULT_FETCHER_USER_DEFINED_ERROR_2          = 311,
00254     ARM_UC_UPDATE_RESULT_FETCHER_USER_DEFINED_ERROR_3          = 312,
00255     ARM_UC_UPDATE_RESULT_FETCHER_USER_DEFINED_ERROR_4          = 313,
00256     ARM_UC_UPDATE_RESULT_FETCHER_USER_DEFINED_ERROR_5          = 314,
00257     ARM_UC_UPDATE_RESULT_FETCHER_LAST                          = ARM_UC_UPDATE_RESULT_FETCHER_USER_DEFINED_ERROR_5,
00258 
00259     // Processor-specific conditions.
00260     // ------------------------------
00261     ARM_UC_UPDATE_RESULT_PROCESSOR_FIRST                       = 400,
00262     ARM_UC_UPDATE_RESULT_PROCESSOR_NONSPECIFIC_ERROR           = ARM_UC_UPDATE_RESULT_PROCESSOR_FIRST,
00263     ARM_UC_UPDATE_RESULT_PROCESSOR_USER_DEFINED_ERROR_1        = 401,
00264     ARM_UC_UPDATE_RESULT_PROCESSOR_USER_DEFINED_ERROR_2        = 402,
00265     ARM_UC_UPDATE_RESULT_PROCESSOR_USER_DEFINED_ERROR_3        = 403,
00266     ARM_UC_UPDATE_RESULT_PROCESSOR_USER_DEFINED_ERROR_4        = 404,
00267     ARM_UC_UPDATE_RESULT_PROCESSOR_USER_DEFINED_ERROR_5        = 405,
00268     ARM_UC_UPDATE_RESULT_PROCESSOR_PLUGIN_NOT_FOUND            = 406,
00269     ARM_UC_UPDATE_RESULT_PROCESSOR_INVALID_INPUT_PROCESSOR     = 407,
00270     ARM_UC_UPDATE_RESULT_PROCESSOR_INVALID_OUTPUT_PROCESSOR    = 408,
00271     ARM_UC_UPDATE_RESULT_PROCESSOR_INVALID_BUFFER              = 409,
00272     ARM_UC_UPDATE_RESULT_PROCESSOR_INSUFFICIENT_MEMORY_SPACE   = 410,
00273     ARM_UC_UPDATE_RESULT_PROCESSOR_BAD_DATA_FORMAT             = 411,
00274     ARM_UC_UPDATE_RESULT_PROCESSOR_INPUT_PROCESSOR_TIMED_OUT   = 412,
00275     ARM_UC_UPDATE_RESULT_PROCESSOR_OUTPUT_PROCESSOR_TIMED_OUT  = 413,
00276     ARM_UC_UPDATE_RESULT_PROCESSOR_LAST                        = ARM_UC_UPDATE_RESULT_PROCESSOR_OUTPUT_PROCESSOR_TIMED_OUT,
00277 
00278     // Writer-specific conditions.
00279     // ---------------------------
00280     ARM_UC_UPDATE_RESULT_WRITER_FIRST                          = 500,
00281     ARM_UC_UPDATE_RESULT_WRITER_NONSPECIFIC_ERROR              = ARM_UC_UPDATE_RESULT_WRITER_FIRST,
00282     ARM_UC_UPDATE_RESULT_WRITER_INSUFFICIENT_STORAGE_SPACE     = 501,
00283     ARM_UC_UPDATE_RESULT_WRITER_INSUFFICIENT_MEMORY_SPACE      = 502,
00284     ARM_UC_UPDATE_RESULT_WRITER_WRITE_FAILURE                  = 503,
00285     ARM_UC_UPDATE_RESULT_WRITER_HASH_ERROR                     = 504,
00286     ARM_UC_UPDATE_RESULT_WRITER_ACTIVATION_FAILURE             = 505,
00287     ARM_UC_UPDATE_RESULT_WRITER_USER_DEFINED_ERROR_1           = 506,
00288     ARM_UC_UPDATE_RESULT_WRITER_USER_DEFINED_ERROR_2           = 507,
00289     ARM_UC_UPDATE_RESULT_WRITER_USER_DEFINED_ERROR_3           = 508,
00290     ARM_UC_UPDATE_RESULT_WRITER_USER_DEFINED_ERROR_4           = 509,
00291     ARM_UC_UPDATE_RESULT_WRITER_USER_DEFINED_ERROR_5           = 510,
00292     ARM_UC_UPDATE_RESULT_WRITER_LAST                           = ARM_UC_UPDATE_RESULT_WRITER_USER_DEFINED_ERROR_5,
00293 
00294 } arm_uc_update_result_t;
00295 
00296 #ifdef __cplusplus
00297 extern "C" {
00298 #endif
00299 
00300 extern bool ARM_UC_IsValidState(arm_uc_update_state_t an_update_state);
00301 extern bool ARM_UC_IsValidResult(arm_uc_update_result_t an_update_result);
00302 
00303 #ifdef __cplusplus
00304 }
00305 #endif
00306 
00307 #endif // ARM_UPDATE_COMMON_PUBLIC_H