update.h

Go to the documentation of this file.

 
#ifndef _UPDATE_H
#define _UPDATE_H
 
// Dependencies
#include "boot_config.h"
#include "core/crc32.h"
#include "core/crypto.h"
#include "core/flash.h"
#include "hash/hash_algorithms.h"
#include "image/image.h"
#include "memory/memory.h"
 
#include <stdint.h>
#if ((CIPHER_SUPPORT == ENABLED) &&                                                                \
   ((IMAGE_INPUT_ENCRYPTED == ENABLED) || (IMAGE_OUTPUT_ENCRYPTED == ENABLED)))
#include "security/cipher.h"
#endif
#include "core/cboot_error.h"
#include "error.h"
#include "core/verify.h"
 
// CycloneBOOT Version string
#define CYCLONE_BOOT_UPDATE_VERSION_STRING "2.6.2"
// CycloneBOOT Major version
#define CYCLONE_BOOT_UPDATE_MAJOR_VERSION 2
// CycloneBOOT Minor version
#define CYCLONE_BOOT_UPDATE_MINOR_VERSION 6
// CycloneBOOT Revision number
#define CYCLONE_BOOT_UPDATE_REV_NUMBER 2
 
#define IMAGE_MAX_CHECK_DATA_SIZE 512
 
// Update single bank internal flash memory mode support
#ifndef UPDATE_SINGLE_BANK_SUPPORT
#define UPDATE_SINGLE_BANK_SUPPORT DISABLED
#elif (UPDATE_SINGLE_BANK_SUPPORT != ENABLED && UPDATE_SINGLE_BANK_SUPPORT != DISABLED)
#error UPDATE_SINGLE_BANK_SUPPORT parameter is not valid!
#endif
 
// Update dual bank internal flash memory mode support
#ifndef UPDATE_DUAL_BANK_SUPPORT
#define UPDATE_DUAL_BANK_SUPPORT ENABLED
#elif (UPDATE_DUAL_BANK_SUPPORT != ENABLED && UPDATE_DUAL_BANK_SUPPORT != DISABLED)
#error UPDATE_DUAL_BANK_SUPPORT parameter is not valid!
#endif
 
// Update fallback support
#ifndef UPDATE_FALLBACK_SUPPORT
#define UPDATE_FALLBACK_SUPPORT DISABLED
#elif (UPDATE_FALLBACK_SUPPORT != ENABLED && UPDATE_FALLBACK_SUPPORT != DISABLED)
#error UPDATE_FALLBACK_SUPPORT parameter is not valid!
#endif
 
// Update automatic backup support
#ifndef UPDATE_AUTO_BACKUP_SUPPORT
#define UPDATE_AUTO_BACKUP_SUPPORT DISABLED
#elif (UPDATE_AUTO_BACKUP_SUPPORT != ENABLED && UPDATE_AUTO_BACKUP_SUPPORT != DISABLED)
#error UPDATE_AUTO_BACKUP_SUPPORT parameter is not valid!
#endif
 
// Update anti-rollback support
#ifndef UPDATE_ANTI_ROLLBACK_SUPPORT
#define UPDATE_ANTI_ROLLBACK_SUPPORT DISABLED
#elif (UPDATE_ANTI_ROLLBACK_SUPPORT != ENABLED && UPDATE_ANTI_ROLLBACK_SUPPORT != DISABLED)
#error UPDATE_ANTI_ROLLBACK_SUPPORT parameter is not valid!
#endif
 
// Acceptable internal memory mode
#if ((UPDATE_SINGLE_BANK_SUPPORT == ENABLED && UPDATE_DUAL_BANK_SUPPORT == ENABLED) ||             \
   (UPDATE_SINGLE_BANK_SUPPORT == DISABLED && UPDATE_DUAL_BANK_SUPPORT == DISABLED))
#error Exactly one of the following parameters MUST be enabled: \
   UPDATE_SINGLE_BANK_SUPPORT - \
   UPDATE_DUAL_BANK_SUPPORT
#endif
 
// Acceptable encryption of the output image activation
#if (((CIPHER_SUPPORT == ENABLED) && (IMAGE_OUTPUT_ENCRYPTED == ENABLED)) &&                       \
   (UPDATE_SINGLE_BANK_SUPPORT == DISABLED))
#error Encryption of the output image is available only in Singel Bank mode!
#endif
 
// Acceptable automatic backup activation
#if ((UPDATE_AUTO_BACKUP_SUPPORT == ENABLED) && (UPDATE_SINGLE_BANK_SUPPORT == DISABLED))
#error Automatic backup is available only in Single Bank mode!
#endif
 
// Add update encryption related dependencies
#if ((CIPHER_SUPPORT == ENABLED) &&                                                                \
   ((IMAGE_INPUT_ENCRYPTED == ENABLED) || (IMAGE_OUTPUT_ENCRYPTED == ENABLED)))
#include "security/cipher.h"
#endif
 
#if (UPDATE_SINGLE_BANK_SUPPORT == ENABLED)
#if (VERIFY_INTEGRITY_SUPPORT == DISABLED)
// Force activation of VERIFY_INTEGRITY_SUPPORT when UPDATE_SINGLE_BANK_SUPPORT
// is activated.
#error Integrity support (VERIFY_INTEGRITY_SUPPORT) MUST be enabled when using CycloneBOOT in Single Bank Mode!
#endif
#endif
 
// C++ guard
#ifdef __cplusplus
extern "C"
{
#endif
 
// Forward declaration of UpdateContext structure
struct _UpdateContext;
#define UpdateContext struct _UpdateContext
 
typedef cboot_error_t (*IapRandCallback)(uint8_t *data, size_t length);
 
typedef enum
{
   UPDATE_AUTH_NONE,
   UPDATE_AUTH_HMAC
} UpdateAuthAlgo;
 
typedef enum
{
   UPDATE_SIGN_NONE,
   UPDATE_SIGN_RSA,
   UPDATE_SIGN_ECDSA
} UpdateSignAlgo;
 
typedef struct
{
#if ((CIPHER_SUPPORT == ENABLED) &&                                                                \
   ((IMAGE_INPUT_ENCRYPTED == ENABLED) || (IMAGE_OUTPUT_ENCRYPTED == ENABLED)))
   const CipherAlgo *cipherAlgo;      
   CipherMode cipherMode;             
   const uint8_t *cipherKey;      
   size_t cipherKeyLen;           
#endif
   VerifySettings verifySettings;      
} UpdateCryptoSettings;
 
typedef struct
{
#if (UPDATE_ANTI_ROLLBACK_SUPPORT == ENABLED)
   ImageVersion appVersion;      
#endif
   UpdateCryptoSettings
      imageInCrypto;       
#if (UPDATE_SINGLE_BANK_SUPPORT == ENABLED)
   UpdateCryptoSettings imageOutCrypto;      
#if (IMAGE_OUTPUT_ENCRYPTED == ENABLED)
   // const char_t *psk;                           ///<PSK key used to encrypt
   // the output image
   const uint8_t *psk;      
   uint32_t pskSize;        
#endif
#endif
   Memory memories[NB_MEMORIES];
} UpdateSettings;
 
typedef enum
{
   UPDATE_STATE_IDLE,
   UPDATE_STATE_RECV_APP_HEADER,
   UPDATE_STATE_RECV_APP_DATA,
   UPDATE_STATE_RECV_APP_CHECK,
   UPDATE_STATE_VALIDATE_APP,
   UPDATE_STATE_APP_REBOOT,
   UPDATE_STATE_WRITE_APP_INIT,
   UPDATE_STATE_WRITE_APP_HEADER,
   UPDATE_STATE_WRITE_APP_DATA,
   UPDATE_STATE_WRITE_APP_CHECK,
   UPDATE_STATE_WRITE_APP_END
} UpdateState;
 
struct _UpdateContext
{
   UpdateSettings settings;      
   Memory memories[NB_MEMORIES];
   ImageProcessContext imageProcessCtx;
};
 
// CycloneBOOT Update application related functions
void updateGetDefaultSettings(UpdateSettings *settings);
char_t *updateGetVersion(void);
cboot_error_t updateRegisterRandCallback(IapRandCallback callback);
 
cboot_error_t updateInit(UpdateContext *context, UpdateSettings *settings);
cboot_error_t updateProcess(UpdateContext *context, const void *data, size_t length);
cboot_error_t updateFinalize(UpdateContext *context);
cboot_error_t updateCreateBackup(UpdateContext *context);
cboot_error_t updateReboot(UpdateContext *context);
cboot_error_t updateConfirm(void);
 
// Update acceptance callback. Declared weak; an integrator may replace it to refuse an image the
// library accepted. Only wired when UPDATE_ANTI_ROLLBACK_SUPPORT is ENABLED.
bool_t updateAcceptUpdateImageCallback(ImageVersion currentAppVersion,
   ImageVersion updateAppVersion);
 
// Extern device MCU related function
extern uint32_t mcuGetVtorOffset(void);
extern void mcuSystemReset(void);
extern void mcuJumpToApplication(uint32_t address);
 
// Random data generation callback function
extern IapRandCallback updateRandCallback;
 
 
#if ((defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)) || defined(__GNUC__) ||            \
   defined(__CC_ARM) || defined(__IAR_SYSTEMS_ICC__) || defined(__TASKING__) ||                  \
   defined(__CWCC__) || defined(__TI_ARM__))
void updateResetMcuHook(void);
#elif ((defined(_MSC_VER) || defined(_WIN32) || defined(WIN32) || defined(WIN64) ||                \
   defined(__unix__)))
void updateResetMcuHook(void);
#endif
 
 
// C++ guard
#ifdef __cplusplus
}
#endif
 
#endif // !_UPDATE_H