/**********************************************************************************************************************
 *  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
 *  -------------------------------------------------------------------------------------------------------------------
 *  FILE DESCRIPTION
 *  -----------------------------------------------------------------------------------------------------------------*/
/** \file  File:  BrsHw.h
 *      Project:  Vector Basic Runtime System
 *       Module:  BrsHw for platform TexasInstruments Sitara AM263x
 *
 *  \brief Description:  This is the hardware specific header file for Vector Basic Runtime System (BRS).
 *
 *  \attention Please note:
 *    The demo and example programs only show special aspects of the software. With regard to the fact
 *    that these programs are meant for demonstration purposes only, Vector Informatik liability shall be
 *    expressly excluded in cases of ordinary negligence, to the extent admissible by law or statute.
 *********************************************************************************************************************/

/**********************************************************************************************************************
 *  REVISION HISTORY
 *  -------------------------------------------------------------------------------------------------------------------
 *  Version   Date        Author  Description
 *  --------  ----------  ------  -------------------------------------------------------------------------------------
 *  00.01.00  2022-08-01  visjhr  Initial creation, based on Brs_AWRgen2
 *                                Removed all non supported compilers and eval boards from BrsHw_Ports.h
 *            2022-08-11  visbwa  Update to Brs_Template 1.03.05; UsageType=external in ALM (DemoComponents concept)
 *  00.01.01  2022-08-25  visjhr  Added iSystems debugger config
 *  00.01.02  2022-09-09  visjhr  Added _FirstTimeUseEvalBoardPreparation in svn content and a Brs_Readme.txt in 
 *                                content referencing it
 *  00.01.03  2022-09-21  visjhr  Added #define BRSHW_ARMCOMMON_COREEXCEPTIONS_AT_ADDRESS_0
 *  00.01.04  2022-09-27  visjhr  Added Lauterbach debugger config
 *  00.01.05  2022-10-11  visjhr  Updated implementation of BrsHwSoftwareResetECU and BrsHwGetResetReasonStartup
 *                                according to initialDE_TPR12_LlvmTI_AM263x_V3
 *  00.01.06  2022-12-22  visjhr  Integrated libs and sbl from 20221129_AM263x_V4_VectorDE
 *  01.00.00  2023-01-13  visjhr  Finalized testing on hardware, updated ReadMe.docx, added V3 Drop SBL for HS-FS 
 *                                (general purpose) devices and V4 Drop SBL for HS-SE (Security Enforced) device on
 *                                HSR-9782, added vBaseEnv_SitaraAM263x_handout.docx, removed Brs_Readme.txt
 *  01.00.01  2023-03-01  visjhr  Updated _FirstTimeUseEvalBoardPreparation\Readme.pdf, added folder
 *                                debug_certificate_creation_HSM_core_on_HS_SE_device to 
 *                                _FirstTimeUseEvalBoardPreparation - only in SVN, not in ALM content
 *  01.00.02  2025-04-22  kal     Removed Ethernet support from package (3rd party MCAL), added missing core IDs
 *  01.00.03  2025-10-30  vismaa  Updated with Brs_Template@Implementation[1.03.14]
 *********************************************************************************************************************/

#ifndef _BRSHW_H_
#define _BRSHW_H_

/**********************************************************************************************************************
 *  MODULE VERSION
 *********************************************************************************************************************/
/*
* Description: This is the BrsHw major, minor and patch version. The version numbers are decimally encoded.
*              E.g. a version of 01.03.12 is encoded with major 1u, minor 3u and patch version 12u.
*              No leading zeroes shall be used, as they would be treated as octal numbers.
*/

/* This is the BrsHw template major, minor and patch version, the platform BrsHw is reviewed to */
#define BRSHW_SOURCECODE_TEMPLATE_MAJOR_VERSION 1u
#define BRSHW_SOURCECODE_TEMPLATE_MINOR_VERSION 3u
#define BRSHW_SOURCECODE_TEMPLATE_PATCH_VERSION 14u

#define BRSHW_SOURCECODE_TEMPLATE_VERSION_COMBINED ((BRSHW_SOURCECODE_TEMPLATE_MAJOR_VERSION) * 10000 + \
                                                    (BRSHW_SOURCECODE_TEMPLATE_MINOR_VERSION) * 100 + \
                                                    (BRSHW_SOURCECODE_TEMPLATE_PATCH_VERSION))

/*
* Description: This is the legacy BrsHw template main and bug fix version. The version numbers are BCD encoded.
*              Nothing to do here, as the version numbers will be generated by macro.
*/
#define BRSHW_SOURCECODE_TEMPLATE_VERSION        (((BRSHW_SOURCECODE_TEMPLATE_MAJOR_VERSION / 10u) << 12u) | \
                                                  ((BRSHW_SOURCECODE_TEMPLATE_MAJOR_VERSION % 10u) << 8u)  | \
                                                  ((BRSHW_SOURCECODE_TEMPLATE_MINOR_VERSION / 10u) << 4u)  | \
                                                  ((BRSHW_SOURCECODE_TEMPLATE_MINOR_VERSION % 10u)))
#define BRSHW_SOURCECODE_TEMPLATE_BUGFIX_VERSION (((BRSHW_SOURCECODE_TEMPLATE_PATCH_VERSION / 10u) << 4u)  | \
                                                  ((BRSHW_SOURCECODE_TEMPLATE_PATCH_VERSION  % 10u)))

/* This is the BrsHw major, minor and patch version */
#define BRSHW_MAJOR_VERSION 1u
#define BRSHW_MINOR_VERSION 0u
#define BRSHW_PATCH_VERSION 3u

#define BRSHW_VERSION_COMBINED ((BRSHW_MAJOR_VERSION) * 10000 + (BRSHW_MINOR_VERSION) * 100 + (BRSHW_PATCH_VERSION))
/**********************************************************************************************************************
 *  INCLUDES
 *********************************************************************************************************************/
/*
 * Description: Inclusion of generic ARM parts
 */
#include "ARMBrsHw_CortexR.h"

#ifndef SOC_AM263X
  #define SOC_AM263X
#endif

#if defined (BRS_COMP_LLVMTEXASINSTRUMENTS)
  #include "drivers/hw_include/cslr_soc.h"
  #include "drivers/gpio.h"
  #include "drivers/soc.h"
  #include "drivers/pinmux.h"
#endif

#if defined (BRS_ENABLE_PORT)
  #include "BrsHw_Ports.h"
#endif

/**********************************************************************************************************************
 *  CONFIGURATION CHECK
 *********************************************************************************************************************/
/* The following parameters are necessary for this platform, to be generated by BRS-Cfg5-Generator into BrsCfg.h */
#if !defined (BRS_OSC_CLK)
  #error "BRS CHECK: The parameter BRS_OSC_CLK is missing! Please check your BRS Cfg5 configuration."
#endif

#if !defined (BRS_TIMEBASE_CLOCK)
  #error "BRS CHECK: The parameter BRS_TIMEBASE_CLOCK is missing! Please check your BRS Cfg5 configuration."
#endif

#if !defined (BRS_PERIPH_CLOCK)
  #error "BRS CHECK: The parameter BRS_PERIPH_CLOCK is missing! Please check your BRS Cfg5 configuration."
#endif

#if !defined (BRS_CPU_MAX_FREQUENCY)
  #error "BRS CHECK: The parameter BRS_CPU_MAX_FREQUENCY is missing! Please check your BRS Cfg5 configuration."
#endif

#if !defined (BRS_CPU_CORE_CORTEX_R5F)
  #error "BRS CHECK: The parameter BRS_CPU_CORE_x is missing or not supported! Please check your BRS Cfg5 configuration."
#endif

#if !defined (BRS_CPU_CORE_AMOUNT)
  #error "BRS CHECK: The parameter BRS_CPU_CORE_AMOUNT is missing! Please check your BRS Cfg5 configuration."
#endif

/**********************************************************************************************************************
 *  GLOBAL CONSTANT MACROS
 *********************************************************************************************************************/
/*
/*
* Description: This corresponds to the return value of BRS_READ_COREID and BrsHw_GetCore().
*              BRSHW_INIT_CORE_ID is used e.g. in main@BrsMain to detect the valid core for HW initialization
*              (boot core)
*/
#define BRSHW_DERIVATIVE_CORE0_ID     0x00  /*R5FSS0_0*/
#define BRSHW_DERIVATIVE_CORE1_ID     0x01  /*R5FSS0_1*/
#define BRSHW_DERIVATIVE_CORE2_ID     0x02  /*R5FSS1_0*/
#define BRSHW_DERIVATIVE_CORE3_ID     0x03  /*R5FSS0_1*/
#define BRSHW_INIT_CORE_ID  BRSHW_DERIVATIVE_CORE0_ID

/* Description: Access the active exception table using base address 0 on all cores */
#define BRSHW_ARMCOMMON_COREEXCEPTIONS_AT_ADDRESS_0

/**********************************************************************************************************************
 * Compiler abstraction
 *********************************************************************************************************************/
/* part of ArmCommon */

/**********************************************************************************************************************
 *  BrsHW configuration
 *********************************************************************************************************************/
/* part of ArmCommon */

/**********************************************************************************************************************
 *  GLOBAL VARIABLES
 *********************************************************************************************************************/

/**********************************************************************************************************************
 *  GLOBAL FUNCTION PROTOTYPES
 *********************************************************************************************************************/

#if defined (BRS_FIRST_EXECUTION_INSTANCE)
#define BRS_START_SEC_STARTUP_CODE
#include "Brs_MemMap.h"
/*****************************************************************************/
/* @brief      This function can be used to initialize controller specific
 *             stuff that should be handled by the first execution instance,
 *             even before the memory initialization took place (e.g.
 *             everything that is necessary to access the memory or to handle
 *             exceptions). This function is called at the beginning of
 *             BrsMainStartup(), immediately after the stackpointer was
 *             initialized in StartupCode
 *             (if BRSHW_EARLYINIT_AVAILABLE is set in BrsHw.h).
 * @pre        -
 * @param[in]  -
 * @param[out] -
 * @return     -
 * @context    Function is called from Brs_PreMainStartup() at power on
 *             initialization
 *****************************************************************************/
#define BRSHW_EARLYINIT_AVAILABLE
void BrsHwEarlyInitPowerOn(void);
#define BRS_STOP_SEC_STARTUP_CODE
#include "Brs_MemMap.h"
#endif /* BRS_FIRST_EXECUTION_INSTANCE */

/*****************************************************************************/
/* @brief      This function can be used to initialize controller specific
 *             stuff that is not related to one of the other InitPowerOn
 *             functions (e.g. code that is always mandatory, also if MCAL
 *             and/or OS is used). This function is called from BrsMain
 *             immediately after BrsHwDisableInterruptAtPowerOn() during
 *             initialization (if BRSHW_PREINIT_AVAILABLE is set in BrsHw.h) or
 *             from the BrsMain_MemoryInit_StageHardReset_Hook() during
 *             initialization (if BRS_ENABLE_PREFER_PLL_WATCHDOG_INIT is set).
 * @pre        -
 * @param[in]  -
 * @param[out] -
 * @return     -
 * @context    Function is called from BrsMainInit() at power on initialization
 *****************************************************************************/
#define BRSHW_PREINIT_AVAILABLE
void BrsHwPreInitPowerOn(void);

#if defined (BRS_ENABLE_WATCHDOG)
/*****************************************************************************/
/* @brief      This function must be used to initialize the Watchdog.
 * @pre        -
 * @param[in]  -
 * @param[out] -
 * @return     -
 * @context    Function is called from BrsMainInit() at power on initialization
 *****************************************************************************/
void BrsHwWatchdogInitPowerOn(void);
#endif /* BRS_ENABLE_WATCHDOG */

#if defined (BRS_ENABLE_PLLCLOCKS)
/*****************************************************************************/
/* @brief      This function must be used to initialize the PLL.
 * @pre        -
 * @param[in]  -
 * @param[out] -
 * @return     -
 * @context    Function is called from BrsMainInit() at power on initialization
 *****************************************************************************/
void BrsHwPllInitPowerOn(void);
#endif /* BRS_ENABLE_PLLCLOCKS */

#if defined (BRS_ENABLE_PORT)

/* BrsHwInitPortInput(), BrsHwInitPortOutput(), BrsHwInitPortInputOutput() are replaced by 
 * proprietary functions provided by TI. */

# if defined (BRS_ENABLE_FBL_SUPPORT)
  #define BRS_START_SEC_RAM_CODE
  #include "Brs_MemMap.h"
# endif
/*****************************************************************************/
/* @brief      This function sets the output level of a port pin.
 * @pre        Port pin configurations available within BrsHw_Ports.h,
 *             no DrvPort used for port pin initialization and
 *             transferred port pin has to be initialized as output pin with
 *             GPIO functionality.
 * @param[in]  p     - brsHw_Port_PortType, to be set,
 *             Level - level, port pin has to be set to
 *                     (BRSHW_PORT_LOGIC_LOW or BRSHW_PORT_LOGIC_HIGH).
 * @param[out] -
 * @return     -
 * @context    Function is called from BrsHwPortInitPowerOn() and
 *             provided to external modules (e.g. BrsMainTogglePin()).
 *****************************************************************************/
void BrsHwPort_SetLevel(brsHw_Port_PortType, uint8);

/*****************************************************************************/
/* @brief      This function reads the input level of a port pin.
 * @pre        Port pin configurations available within BrsHw_Ports.h,
 *             no DrvPort used for port pin initialization and
 *             transferred port pin has to be initialized as input pin with
 *             GPIO functionality.
 * @param[in]  p - brsHw_Port_PortType, to be read.
 * @param[out] -
 * @return     Level, read from port pin
 *             (BRSHW_PORT_LOGIC_LOW or BRSHW_PORT_LOGIC_HIGH).
 * @context    Function is provided to external modules.
 *****************************************************************************/
uint8 BrsHwPort_GetLevel(brsHw_Port_PortType);
# if defined (BRS_ENABLE_FBL_SUPPORT)
  #define BRS_STOP_SEC_RAM_CODE
  #include "Brs_MemMap.h"
# endif

/*****************************************************************************/
/* @brief      This function must be used to initialize the used ports.
 * @pre        -
 * @param[in]  -
 * @param[out] -
 * @return     -
 * @context    Function is called from BrsMainInit() at power on initialization
 *****************************************************************************/
void BrsHwPortInitPowerOn(void);
#endif /* BRS_ENABLE_PORT */

/* BrsHwDisableInterruptAtPowerOn() is part of ArmCommon */

/* BrsHw_ExceptionTable_Init() is part of ArmCommon */

/*****************************************************************************/
/* @brief      Restart ECU (issue a software reset or jump to startup code)
 * @pre        -
 * @param[in]  -
 * @param[out] -
 * @return     -
 * @context    Function is called from e.g. ECU state handling
 *****************************************************************************/
void BrsHwSoftwareResetECU(void);

#if defined (BRS_FIRST_EXECUTION_INSTANCE)
/* This code is only needed for the first instance/executable in the system */
#define BRS_START_SEC_STARTUP_CODE
#include "Brs_MemMap.h"
/*****************************************************************************/
/* @brief      Get reset reason
 * @pre        -
 * @param[in]  -
 * @param[out] -
 * @return     Reset reason
 * @context    Function is called from BrsMainStartup to determine if reset
 *             was triggered through software call (BrsHwSoftwareResetECU()).
 *             The result is stored by BrsMainStartup in the global variable
 *             brsMain_ResetReason. It should only be called once, during
 *             startup. The old API name BrsHwGetResetReason() is remapped
 *             to BrsMainGetResetReason.
 *****************************************************************************/
brsMain_ResetReasonType BrsHwGetResetReasonStartup(void);
#define BRS_STOP_SEC_STARTUP_CODE
#include "Brs_MemMap.h"

/*
* Wrapper from old BrsHwGetResetReason() function to new BrsMainGetResetReason().
* This is to prevent multiple selection of reset reason registers, as this is not
* supported on all HW platforms.
*/
#define BrsHwGetResetReason() BrsMainGetResetReason()
#endif /* BRS_FIRST_EXECUTION_INSTANCE */

/* BrsHwTime100NOP() is part of ArmCommon */

#if defined (BRS_ENABLE_SAFECTXSUPPORT)
/*****************************************************************************/
/* @brief      This API is used to enable hardware access in untrusted mode
 * @pre        -
 * @param[in]  -
 * @param[out] -
 * @return     -
 * @context    Function must be called after all depending peripheral modules
 *             are supplied by proper clocks AND before the OS is started.
 *****************************************************************************/
void BrsHw_EnableHwAccess(void);
#endif /* BRS_ENABLE_SAFECTXSUPPORT */

/* BrsHw_GetCore() is part of ArmCommon */

/*****************************************************************************/
/* @brief      This API is used to enable an interrupt source in the core
 *             interrupt controller.
 * @pre        -
 * @param[in]  Source to be enabled.
 * @param[in]  Priority level to be set.
 * @param[out] -
 * @return     -
 * @context    Function is called from HlpTest and other test environments.
 *****************************************************************************/
void BrsHw_EnableInterrupt(uint32, uint8);

/*****************************************************************************/
/* @brief      This API is used to disable an interrupt source in the core
 *             interrupt controller.
 * @pre        -
 * @param[in]  Source to be disabled.
 * @param[out] -
 * @return     -
 * @context    Function is called from HlpTest and other test environments.
 *****************************************************************************/
void BrsHw_DisableInterrupt(uint32);

/*****************************************************************************/
/* @brief      This API is used to trigger the given software interrupt source.
 * @pre        -
 * @param[in]  Source to be triggered.
 *             Some derivatives only support few software triggerable sources,
 *             check for their validity.
 * @param[out] -
 * @return     -
 * @context    Function is called from HlpTest and other test environments.
 *****************************************************************************/
void BrsHw_TriggerSoftwareInterrupt(uint32);
#endif /*_BRSHW_H_*/
