/***********************************************************************************************************************
 *  FILE DESCRIPTION
 *  ------------------------------------------------------------------------------------------------------------------*/
/** \file
 *  \brief        Main definitions for the Flash Boot Loader
 *
 *  --------------------------------------------------------------------------------------------------------------------
 *  COPYRIGHT
 *  --------------------------------------------------------------------------------------------------------------------
 *  \par Copyright
 *  \verbatim
 *  Copyright (c) 2025 by Vector Informatik GmbH.                                                  All rights reserved.
 *
 *                This software is copyright protected and proprietary to Vector Informatik GmbH.
 *                Vector Informatik GmbH grants to you only those rights as set out in the license conditions.
 *                All other rights remain with Vector Informatik GmbH.
 *  \endverbatim
 */
/**********************************************************************************************************************/

/***********************************************************************************************************************
 *  REVISION HISTORY
 *  --------------------------------------------------------------------------------------------------------------------
 *  Version    Date        Author       Change Id        Description
 *  --------------------------------------------------------------------------------------------------------------------
 *  04.00.00   2016-02-26  visach       ESCAN00088307    Rework to support FblMain 3.xx
 *                                      ESCAN00088433    Moved assertion specific code to fbl_assert.h
 *  04.00.01   2016-07-15  visdlm       ESCAN00091011    Added programming voltage check defines
 *  04.01.00   2016-08-18  vistns       ESCAN00091531    Updated support of HMC
 *  04.02.00   2016-10-31  viscb        ESCAN00092597    Added support for SYMC SLP2
 *  04.02.01   2017-05-09  visjhg       ESCAN00095090    Include upper-case Fbl_Cfg.h for DaVinci Configurator use-case
 *                         visrie       ESCAN00095204    No changes
 *  04.03.00   2017-07-28  viscb        ESCAN00095458    Removed unneeded client switches
 *                         visach       ESCAN00096096    Added fallback activation of NV-Wrapper and Vector SecMod
 *  04.04.00   2018-02-26  visdkl       ESCAN00098503    Updated support of Toyota SLP4
 *  04.04.01   2018-07-06  visdkl       ESCAN00099860    Compiler error: shift count is too large
 *  04.05.00   2018-09-13  visrie       ESCAN00100731    Added additional flags for BootManager use-case
 *             2018-11-20  visdkl       ESCAN00101393    Removed support for Ford SLP6
 *  04.06.00   2019-12-03  visjdn       FBL-999          Add define V_ENABLE_USE_DUMMY_STATEMENTS
 *  05.00.00   2020-03-02  vistbe       FBL-949          Add include for FblBm_Cfg.h
 *                                      ESCAN00105231    Compiler error: define syntax
 *  05.01.00   2020-04-29  vistmo       FBL-1584         Adding OTA startup support
 *  05.02.00   2020-05-08  visrie       FBL-1414         Adding One-Step-Updater support
 *  05.03.00   2020-07-16  visrie       FBL-2021         Adding OTA response after reset support
 *  05.04.00   2024-05-03  visrie       FBL-8515         Add generic defines and cleanup client list
 *                                      ESCAN00117096    Compiler error: Bit count of CPU not supported
 *  05.05.00   2025-10-03  pharring     FBL-10242        No changes
 *  05.06.00   2025-10-22  mpatil       FBL-11533        No changes
 **********************************************************************************************************************/

#ifndef FBL_DEF_H
#define FBL_DEF_H

/***********************************************************************************************************************
 *  INCLUDES
 **********************************************************************************************************************/

/* Basic configurations */
#include "v_cfg.h"

#if defined( VGEN_GENY ) && !defined( VGEN_ENABLE_CANFBL )
/* This file was obviously not included in FBL, so it's used in user application
   check if MAGIC_NUMBER was generated. In this case we have to remove the check for the
   following include because FBL generation use different number than application */
# if defined( MAGIC_NUMBER )
#  undef MAGIC_NUMBER
# endif
#endif

#include "FblBm_Cfg.h"

/* Configuration file for flash boot loader */
#include "Fbl_Cfg.h"
#if defined( VGEN_GENY ) && !defined( VGEN_ENABLE_CANFBL )
/* The last include redefined MAGIC_NUMBER, which is not relevant for application so
   invalidate it */
# if defined( MAGIC_NUMBER )
#  undef MAGIC_NUMBER
# endif
#endif

/* Basic type definitions */
#include "v_def.h"

#if defined( FBL_ENABLE_SECMOD_VECTOR )
# include "SecM_cfg.h"
#endif

/* In application either remove FBL_ENABLE_ASSERTION switch or provide fbl_assert.h */
# include "fbl_assert.h"

/* PRQA S 3453 EOF */ /* MD_MSR_19.7 */
/* PRQA S 3458 EOF */ /* MD_MSR_19.4 */

/***********************************************************************************************************************
 *  VERSION
 **********************************************************************************************************************/

/* ##V_CFG_MANAGEMENT ##CQProject : FblDef CQComponent : Implementation */
#define FBLDEF_VERSION          0x0506u
#define FBLDEF_RELEASE_VERSION  0x00u

/***********************************************************************************************************************
 *  DEFINES
 **********************************************************************************************************************/

/* Select usage of unified main interface */
#define FBL_DEF_ENABLE_NON_KB_MAIN

#ifndef NULL
# define NULL ((void *)0)
#endif

/* Configuration of default switches */
/* Activate NV-Wrapper if not explicitly configured */
# if !defined( FBL_ENABLE_WRAPPER_NV ) && \
     !defined( FBL_DISABLE_WRAPPER_NV )
#  define FBL_ENABLE_WRAPPER_NV
# endif
/* Activate Vector SecMod if not explicitly configured */
# if !defined( FBL_ENABLE_SECMOD_VECTOR ) && \
     !defined( FBL_DISABLE_SECMOD_VECTOR )
#  define FBL_ENABLE_SECMOD_VECTOR
# endif
/* Disable StayInBoot if not explicitly configured */
#if !defined( FBL_ENABLE_STAY_IN_BOOT ) && \
    !defined( FBL_DISABLE_STAY_IN_BOOT )
# define FBL_DISABLE_STAY_IN_BOOT
#endif

/* Define return code of several functions */
#define kFblOk                   0x00u
#define kFblFailed               0x01u

/* Defines for programming voltage check */
#define kFblVoltageTooLow        0x01u
#define kFblVoltageTooHigh       0x02u

/* Programming request flag */
#define kProgRequest             0x00u    /**< Diagnostic programming request is reported to main */
#define kProgRequestXcp          0x01u    /**< XCP programming request is reported to main */
#define kProgRequestOta          0x02u    /**< OTA programming request is reported to main */
#define kNoProgRequest           0xFFu    /**< No programming request */

#define kProgRequestWithResponse 0x02u    /**< External programming request with response required */
#define kProgRequestNoResponse   0x03u    /**< No response required to programming request */

#define kCheckStayInBootRequest  0x10u    /**< Check for stay in boot message */
#define kInitKeysRequest         0x11u    /**< Initialize crypto keys */
#define kInitMacsRequest         0x12u    /**< Initialize MACs */

/* Flag indicates that a response is required after programming request (only used by certain SLPs) */
#define kFblStartWithResponse    0xAAu    /**< FBL shall send a response after startup */
#define kFblStartNoResponse      0x5Fu    /**< FBL shall not send a response after startup */

/* Application validation  */
# define kApplValid              1u       /**< Application is fully programmed */
# define kApplInvalid            0u       /**< Operational software is missing */

/* Memory status (flash erased detection) */
# define kFlashErased            1u       /**< Flash memory is in erased state */
# define kFlashNotErased         0u       /**< Flash memory is not in erased state (already written) */

/* Define return code of security access functions (only used by certain SLPs) */
#define kFblSecNewSeedIssued           3u /**< seed */
#define kFblSecGranted                 4u /**< seed - key - status */
#define kFblSecDeniedLocked            5u /**< status */
#define kFblSecDeniedIncorrectLevel    6u /**< seed */
#define kFblSecDeniedInvalidKey        7u

#if !defined( FBL_REPEAT_CALL_CYCLE )
/** Set default to 1ms for repeat time of main loop */
# define FBL_REPEAT_CALL_CYCLE         1u
#endif

#if defined( FBL_ENABLE_BANKING )
#else
# define FBL_CALL_TYPE
#endif /* FBL_ENABLE_BANKING */

#ifndef V_CALLBACK_NEAR
# define V_CALLBACK_NEAR
#endif
#ifndef V_API_NEAR
# define V_API_NEAR
#endif


/* Defines to convert BigEndian bytes into short or long values ********************/
#if defined( C_CPUTYPE_BIGENDIAN )
# if defined( C_CPUTYPE_32BIT )
#  define FblBytesToShort(hi,lo)       (((vuint16)(hi) << 8u) | ((vuint16)(lo)))
# else
#  define FblBytesToShort(hi,lo)       (vuint16)*(V_MEMRAM1_FAR vuint16 V_MEMRAM2_FAR *)(&(hi))
# endif /* C_CPUTYPE_32BIT */
#endif /* C_CPUTYPE_BIGENDIAN */
#if defined( C_CPUTYPE_LITTLEENDIAN )
# define FblBytesToShort(hi,lo)        (((vuint16)(hi) << 8u) | ((vuint16)(lo)))
#endif /* C_CPUTYPE_LITTLEENDIAN */

#if defined( C_CPUTYPE_BIGENDIAN )
# if defined( C_CPUTYPE_32BIT )
#  define FblBytesToLong(hiWrd_hiByt,hiWrd_loByt,loWrd_hiByt,loWrd_loByt)  \
                                       (((vuint32)(hiWrd_hiByt) << 24u) |  \
                                        ((vuint32)(hiWrd_loByt) << 16u) |  \
                                        ((vuint32)(loWrd_hiByt) <<  8u) |  \
                                        ((vuint32)(loWrd_loByt)       )  )
# else
#  define FblBytesToLong(hiWrd_hiByt,hiWrd_loByt,loWrd_hiByt, loWrd_loByt)  \
                                       (vuint32)*(V_MEMRAM1_FAR vuint32 V_MEMRAM2_FAR *)(&(hiWrd_hiByt))
# endif /* C_CPUTYPE_32BIT */
#endif /* C_CPUTYPE_BIGENDIAN */
#if defined( C_CPUTYPE_LITTLEENDIAN )
# define FblBytesToLong(hiWrd_hiByt,hiWrd_loByt,loWrd_hiByt,loWrd_loByt)   \
                                       (((vuint32)(hiWrd_hiByt) << 24u) |  \
                                        ((vuint32)(hiWrd_loByt) << 16u) |  \
                                        ((vuint32)(loWrd_hiByt) <<  8u) |  \
                                        ((vuint32)(loWrd_loByt)       )  )
#endif /* C_CPUTYPE_LITTLEENDIAN */

/* FBL bit definitions */
#define FBL_BIT0   0x01u
#define FBL_BIT1   0x02u
#define FBL_BIT2   0x04u
#define FBL_BIT3   0x08u
#define FBL_BIT4   0x10u
#define FBL_BIT5   0x20u
#define FBL_BIT6   0x40u
#define FBL_BIT7   0x80u

/* Defines for response after reset */
#define RESET_RESPONSE_NOT_REQUIRED             0x00u    /**< No response required */
#define RESET_RESPONSE_SDS_REQUIRED             0x01u    /**< Response to SessionControl-DefaultSession required */
#define RESET_RESPONSE_ECURESET_REQUIRED        0x02u    /**< Response to EcuReset-HardReset required */
#define RESET_RESPONSE_KEYOFFON_REQUIRED        0x03u    /**< Response to EcuReset-KeyOffOnReset required */
#define RESET_RESPONSE_OSU_REQUIRED             0x04u    /**< Response to One-Step-Updater required */
#define RESET_RESPONSE_OTA_REQUIRED             0x05u    /**< Response to OTA required */

/* Macros to harmonize type casts for inverting bits */
#define FblInvertBits(x,type)    ((type)~((type)(x)))    /* PRQA S 0277 */ /* MD_FblDef_Invert */
#define FblInvert8Bit(x)         ((vuint8) ((x) ^ ((vuint8 )0xFFu)))
#define FblInvert16Bit(x)        ((vuint16)((x) ^ ((vuint16)0xFFFFu)))
#define FblInvert32Bit(x)        ((vuint32)((x) ^ ((vuint32)0xFFFFFFFFul)))

/* Logical Marker (only used by certain SLPs) */
#define LM_Upload          0x80u
#define LM_Calibration     0x81u
#define LM_Global          0x82u
#define LM_LogZone         0x83u
#define LM_UploadNoCrc     0x84u
#define LM_AppliKey        0x88u

# define kFblDiagTimeP2          FBL_DIAG_TIME_P2MAX
# define kFblDiagTimeP2Star      FBL_DIAG_TIME_P3MAX

/* Reprogramming request flags */
#define kEepFblReprogram         0xB5u    /**< FBL is started with normal reprogramming request, e.g. programming session */
#define kEepFblXcpProgram        0x5Bu    /**< FBL is started with XCP reprogramming request */
#define kEepFblOtaReprogram      0x5Cu    /**< FBL is started with OTA reprogramming request */
#define kEepFblActive            0xA4u
#define kEepFblVpm               0xC6u
#define kEepFblLinkControl       0x93u

/* Flags to indicate if NV functions should read or write data */
#define kEepWriteData            1u    /**< Write data to NV memory */
#define kEepReadData             2u    /**< Read data from NV memory */

/* Error code defines for ApplFblErrorNotification */
#define kFblErrTypeAppl          0x10u
#define kFblErrTypeFlash         0x20u
#define kFblErrTypeEeprom        0x30u
#define kFblErrTypeSec           0x40u
#define kFblErrTypeVectorTPMC    0x50u

/** Round length up to next multiple of alignment */
#define FBL_LENGTH_ALIGN_ROUND_UP(length, align)      (((((length) - 1u) / (align)) + 1u) * (align))
/** Round length down to next multiple of alignment */
#define FBL_LENGTH_ALIGN_ROUND_DOWN(length, align)    (((length) / (align)) * (align))

/** Helper macro to get number of array entries */
#define FBL_ARRAY_SIZE(arr)                           (sizeof(arr) / sizeof((arr)[0]))

/** Number of validity bytes required for logical block validity information */
#define FBL_NUMBER_OF_VALIDITY_FLAG_BYTES             (FBL_LENGTH_ALIGN_ROUND_UP(FBL_LBT_BLOCK_COUNT, 8u) / 8u)

#if defined( FBL_USE_DUMMY_STATEMENT )
# if !defined( V_ENABLE_USE_DUMMY_STATEMENT )
#  define V_ENABLE_USE_DUMMY_STATEMENT
# endif
#endif

/***********************************************************************************************************************
 *  State handling framework
 **********************************************************************************************************************/

/* State array settings */
#if defined( C_CPUTYPE_8BIT )
typedef vuint8 tFblStateBitmap;
# define FBL_STATE_BITS             8u
# define kFblStateMaskNone          0x00u
# define kFblStateMaskAll           0xFFu
# define FblInvertStates(x)         FblInvert8Bit(x)  /* PRQA S 3453 */ /* MD_MSR_19.7 */
#elif defined( C_CPUTYPE_16BIT )
typedef vuint16 tFblStateBitmap;
# define FBL_STATE_BITS             16u
# define kFblStateMaskNone          0x0000u
# define kFblStateMaskAll           0xFFFFu
# define FblInvertStates(x)         FblInvert16Bit(x) /* PRQA S 3453 */ /* MD_MSR_19.7 */
#elif defined( C_CPUTYPE_32BIT ) || \
      defined( C_CPUTYPE_64BIT )
typedef vuint32 tFblStateBitmap;
# define FBL_STATE_BITS             32u
# define kFblStateMaskNone          0x00000000ul
# define kFblStateMaskAll           0xFFFFFFFFul
# define FblInvertStates(x)         FblInvert32Bit(x) /* PRQA S 3453 */ /* MD_MSR_19.7 */
#else
# error "Bit count of CPU not supported."
#endif

/* State mask build macros */
/* PRQA S 3453 10 */ /* MD_MSR_19.7 */
#define FBL_STATE_MASK(bit)               ((tFblStateBitmap)(1ul << ((bit) % FBL_STATE_BITS)))
#define FBL_STATE_MULTIMASK(min, max)     ((((kFblStateMaskAll) >> ((min) % FBL_STATE_BITS)) << ((min) % FBL_STATE_BITS)) ^ (((kFblStateMaskAll) >> (((max) + 1u) % FBL_STATE_BITS)) << (((max) + 1u) % FBL_STATE_BITS)))
#define FBL_STATE_MASKLONG(bit)           (1ul << (bit))
#define FBL_STATE_MULTIMASKLONG(min, max) ((((~0ul) >> (min)) << (min)) ^ (((max) < (STATE_BITS - 1u)) ? (((~0ul) >> ((max) + 1u)) << ((max) + 1u)) : 0ul))
#define FBL_STATE_INDEX(bit)              ((bit) / FBL_STATE_BITS)
#define FBL_STATE_SET(arr, bit)           ((arr)[FBL_STATE_INDEX(bit)] |= FBL_STATE_MASK(bit))
#define FBL_STATE_CLR(arr, bit)           ((arr)[FBL_STATE_INDEX(bit)] &= FblInvertStates(FBL_STATE_MASK(bit)))
#define FBL_STATE_MULTICLR(arr, min, max) ((arr)[FBL_STATE_INDEX(min)] &= FblInvertStates(FBL_STATE_MULTIMASK((min), (max))))
#define FBL_STATE_TEST(arr, bit)          (((arr)[FBL_STATE_INDEX(bit)] & FBL_STATE_MASK(bit)) == FBL_STATE_MASK(bit))

/***********************************************************************************************************************
 *  TYPEDEFS (basic types)
 **********************************************************************************************************************/
typedef vuint8  tFblErrorType;
typedef vuint16 tFblErrorCode;

typedef vuint8 tFblResult;                    /**< FBL result codes */
typedef vuint8 tFblProgStatus;                /**< Status of reprogramming flag */
typedef vuint8 tApplStatus;                   /**< Application valid status */
typedef vuint8 tMagicFlag;                    /**< Application valid flag */
typedef vuint8 tFlashStatus;                  /**< Flash erased status flag */

/* The below bootloader address types always define logical addresses.
 * This is important for those platforms which provide a paged physical memory
 * address space. For those platforms with linear physical address space, logical
 * and physical addresses are identical.
 */
#if defined( C_CPUTYPE_8BIT ) && !defined( FBL_PROCESSOR_BANKED )
typedef vuint16 FBL_ADDR_TYPE;
typedef vuint16 FBL_MEMSIZE_TYPE;
#else
typedef vuint32 FBL_ADDR_TYPE;
typedef vuint32 FBL_MEMSIZE_TYPE;
#endif

typedef vuint8 FBL_MEMID_TYPE;

typedef FBL_ADDR_TYPE       tFblAddress;
typedef FBL_MEMSIZE_TYPE    tFblLength;

typedef FBL_ADDR_TYPE       tMtabAddress;
typedef FBL_MEMSIZE_TYPE    tMtabLength;
typedef FBL_MEMID_TYPE      tMtabMemId;

typedef vuint16 tChecksum;

/***********************************************************************************************************************
 *  TYPEDEFS (function pointers)
 **********************************************************************************************************************/

/* Function pointer for FBL-exported functions */
#if defined( FBL_ENABLE_BANKING )
typedef FBL_CALL_TYPE void (*FBL_CALL_TYPE tExportFct)(void); /* PRQA S 0313 */ /* MD_FblDef_Export */
#else
typedef MEMORY_FAR void (*tExportFct)(void); /* PRQA S 0313 */ /* MD_FblDef_Export */
#endif /* FBL_ENABLE_BANKING */

typedef FBL_CALL_TYPE vuint8 (* tFblRealtimeFct)(void);

/** Function pointer to read memory */
typedef FBL_CALL_TYPE tFblLength (* tReadMemoryFct)(tFblAddress address, V_MEMRAM1 vuint8 V_MEMRAM2 V_MEMRAM3 * buffer, tFblLength length);

/***********************************************************************************************************************
 *  TYPEDEFS (other)
 **********************************************************************************************************************/

#if defined( FBL_ENABLE_DATA_PROCESSING )
typedef struct tagProcParam
{
   V_MEMRAM1 vuint8 V_MEMRAM2 V_MEMRAM3 * dataBuffer;
   vuint16        dataLength;
   V_MEMRAM1 vuint8 V_MEMRAM2 V_MEMRAM3 * dataOutBuffer;
   vuint16        dataOutLength;
   vuint16        dataOutMaxLength;
   vuint8         (* wdTriggerFct)(void);
   vuint8         mode;
} tProcParam;
#endif

#endif /* FBL_DEF_H */

/* Module specific MISRA deviations:

   MD_FblDef_Export:
     Reason: Verify interface functions are stored as void pointers as actual type is not known at configuration time.
             The software that uses these functions has to take care that a cast to the correct function type is being done before usage
     Risk: The software that uses this elements does not correctly cast before usage.
     Prevention: Review of implementations and testing of the functionality.

   MD_FblDef_Invert:
     Reason: Usage of FblInvert.. macros implies usage of ~ operator and appropriate casts. This includes a cast from
             negative integer to unsigned value. The integer is only an intermediate type that occurs because of
             integer promotion while using ~ operator, though only a bit mask is operated on.
     Risk: No risk.
     Prevention: No prevention defined.

*/

/***********************************************************************************************************************
 *  END OF FILE: FBL_DEF.H
 **********************************************************************************************************************/

