AM263Px MCU+ SDK: APIs for SDL ESM

| AM263Px MCU+ SDK 26.00.00 |

Sub Modules | Files | Data Structures | Functions | Typedefs | Enumerations | Macros
APIs for SDL ESM
APIs for SDL Module

## Introduction

This module contains APIs for using the ESM module. The APIs can be used to configure the ESM instances for notification when error events occur and also to set the error pin.

## Sub Modules
| ESM Low-Level API

## Files
file | sdl_esm.h
| This file contains the SDL ESM API's.
file | sdl_esm_soc.h
file | esm/v2/sdl_esm.h
| Header file contains enumerations, structure definitions and function declarations for SDL Error Signaling Module interface.

## Data Structures
struct | SDL_ESM_ErrorConfig_t
| ESM error configuration. More...
struct | SDL_ESM_config
| ESM init configuration. More...

## Functions
int32_t | SDL_ESM_getNErrorStatus (SDL_ESM_Inst instance, uint32_t *pStatus)
| SDL ESM API to get the status of the nError pin for the specified ESM instance. More...
int32_t | SDL_ESM_getStaticRegisters (SDL_ESM_Inst instance, SDL_ESM_staticRegs *pStaticRegs)
| SDL ESM API to read the static registers. The API reads and returns the static register configuration for the ESM module for the specified instance. This API can be used by the application to read back the static configuration. Comparision of the static configuration registers against expected values is the responsibility of the application. More...
int32_t | SDL_ESM_verifyConfig (SDL_ESM_Inst instance, const SDL_ESM_config *pConfig)
| SDL ESM API to verify the written configuration of the ESM module. The API verifies the written config that was done during SDL_ESM_init against the provided configuration. More...
int32_t | SDL_ESM_clrNError (SDL_ESM_Inst instance)
| SDL ESM API to clear the nError pin for the specified ESM instance. More...
int32_t | SDL_ESM_setNError (SDL_ESM_Inst instance)
| SDL ESM API to set the nError pin for the specified ESM instance. More...
int32_t | SDL_ESM_registerECCCallback (SDL_ESM_Inst instance, uint32_t eventBitMap[], SDL_ESM_applicationCallback eccCallback, void *callbackArg)
| There are modules within SDL which will generate ESM errors intentionally in the course of running self-tests. The ECC module is one such module. To allow these modules to get the notification when the ESM error occurs, callback registration APIs are provided. The following APIs allow registration of a callback for specific events. This API is used by other SDL modules and not by the application. More...
int32_t | SDL_ESM_init (SDL_ESM_Inst instance, const SDL_ESM_config *pConfig, SDL_ESM_applicationCallback applicationCallback, void *appArg)
| SDL ESM API to initialize an ESM instance. The API initializes the specified ESM instance with the provided configuration. The configuration will allow the application to specify for each event whether the interrupt is enabled or disabled, the priority of the event, and whether the nErrorPin assertion is enabled or disabled for the event. More...
int32_t | SDL_ESM_setPinOutMode (SDL_ESM_Inst instance, esmErrOutMode_t pinOutMode)
| This API is use to set error pin out mode(LEVEL or PWM). This API must be called after the below API- SDL_ESM_init. More...
int32_t | SDL_ESM_registerCCMCallback (SDL_ESM_Inst instance, uint32_t eventBitMap[], SDL_ESM_applicationCallback ccmCallback, void *callbackArg)
| There are modules within SDL which will generate ESM errors intentionally in the course of running self-tests. The CCM module is one such module. To allow these modules to get the notification when the ESM error occurs, callback registration APIs are provided. The following APIs allow registration of a callback for specific events. This API is used by other SDL modules and not by the application. More...
void | SDL_ESM_hiInterruptHandler (void *arg)
| Esm Hi Interrupt Handler for MCU Esm Instance. More...
void | SDL_ESM_loInterruptHandler (void *arg)
| Esm Lo Interrupt Handler for MCU Esm Instance. More...
void | SDL_ESM_configInterruptHandler (void *arg)
| Esm Config Interrupt Handler for MCU Instance. More...
int32_t | SDL_ESM_getIntNumber (SDL_ESM_Inst esmInstType, SDL_ESM_IntType esmIntType)
| Esm get Interrupt Number corresponding to the input interrupt type. More...
int32_t | SDL_ESM_getWarmResetReason (void)
| Get the warm reset reason if it is generated by ESM. More...
void | SDL_ESM_enableESMWarmReset (void)
| Enable ESM warm reset reason. More...

## Typedefs
typedef int32_t | SDL_Result
typedef int32_t(* | SDL_ESM_applicationCallback) (SDL_ESM_Inst instance, SDL_ESM_IntType intrType, uint32_t grpChannel, uint32_t index, uint32_t intSrc, void *arg)

## Enumerations
enum | SDL_ESM_Inst { SDL_ESM_INST_MAIN_ESM0 = 2U, SDL_ESM_INSTANCE_MAX =0xFFFF }
enum | SDL_ESM_IntType { SDL_ESM_INT_TYPE_HI = 1, SDL_ESM_INT_TYPE_LO = 2, SDL_ESM_INT_TYPE_CFG = 3, SDL_ESM_INT_TYPE_MAX = 4 }

## Macros
#define | SOC_MAIN_ESM_BASE (SDL_TOP_ESM_U_BASE)
#define | SOC_MAIN_ESM_MAX_NUM_EVENTS (SDL_ESM0_MCAN7_MCAN7_ECC_UNCORR_LVL_INT+1U)
#define | SDL_ESM_INTNUMBER_INVALID (0xffffffffu)
| Invalid interrupt number. More...
#define | SDL_ESM_INST_INVALID (0xfffffffeu)
| Invalid Esm Instance. More...
#define | SDL_ESM_ERRORADDR_INVALID (0xffffffffu)
| Address field: Error Address invalid. More...
#define | SDL_ESM_ERRORRAMID_INVALID (0xffffffffu)
| Address field: Error RAM ID invalid. More...
#define | SDL_ESM_ERRORBITOFFSET_INVALID (0xffffffffffffffffu)
| Address field: Error Bit Error Offset invalid. More...
#define | SDL_ESM_ERRORBITGROUP_INVALID (0xffffffffu)
| Address field: Error Bit Error Group invalid. More...
#define | SDL_ESM_MAX_EVENT_MAP_NUM_WORDS (32u)
| Maximum number of EVENT words. More...
#define | SDL_ESM_ECC_PARAM_MAIN_MSMC_AGGR0_SEC_ERROR (10001u)
| Main MSMC ECC AGGR0 detected 1-bit ECC error source. More...
#define | SDL_ESM_ECC_PARAM_MAIN_MSMC_AGGR0_DED_ERROR (10002u)
| Main MSMC ECC AGGR0 detected 2-bit ECC error source. More...
#define | SDL_ESM_ECC_PARAM_MAIN_A72_AGGR0_SEC_ERROR (10003u)
| Main A72 ECC AGGR0 detected 1-bit ECC error source. More...
#define | SDL_ESM_ECC_PARAM_MAIN_A72_AGGR0_DED_ERROR (10004u)
| Main A72 ECC AGGR0 detected 2-bit ECC error source. More...

## ESM ECC Error source type
typedef uint32_t | sdlEsmEccErrorSource_t
| Source of the ECC error which maps to the ESM interrupt source. More...
#define | SDL_ESM_ECC_PARAM_MCU_CPU0_SEC_ERROR (1u)
| MCU CPU0 detected 1-bit ECC error source. More...
#define | SDL_ESM_ECC_PARAM_MCU_CPU0_DED_ERROR (2u)
| MCU CPU0 detected 2-bit ECC error source. More...
#define | SDL_ESM_ECC_PARAM_MCU_CPU1_SEC_ERROR (3u)
| MCU CPU1 detected 1-bit ECC error source. More...
#define | SDL_ESM_ECC_PARAM_MCU_CPU1_DED_ERROR (4u)
| MCU CPU1 detected 2-bit ECC error source. More...
#define | SDL_ESM_ECC_PARAM_MCU_CBASS_SEC_ERROR (5u)
| MCU CBASS detected 1-bit ECC error source. More...
#define | SDL_ESM_ECC_PARAM_MCU_CBASS_DED_ERROR (6u)
| MCU CBASS detected 2-bit ECC error source. More...

## Macro Definition Documentation

## ◆ SOC_MAIN_ESM_BASE

#define SOC_MAIN_ESM_BASE (SDL_TOP_ESM_U_BASE)

## ◆ SOC_MAIN_ESM_MAX_NUM_EVENTS

#define SOC_MAIN_ESM_MAX_NUM_EVENTS (SDL_ESM0_MCAN7_MCAN7_ECC_UNCORR_LVL_INT+1U)

## ◆ SDL_ESM_INTNUMBER_INVALID

#define SDL_ESM_INTNUMBER_INVALID (0xffffffffu)

Invalid interrupt number.

## ◆ SDL_ESM_INST_INVALID

#define SDL_ESM_INST_INVALID (0xfffffffeu)

Invalid Esm Instance.

## ◆ SDL_ESM_ERRORADDR_INVALID

#define SDL_ESM_ERRORADDR_INVALID (0xffffffffu)

Address field: Error Address invalid.

## ◆ SDL_ESM_ERRORRAMID_INVALID

#define SDL_ESM_ERRORRAMID_INVALID (0xffffffffu)

Address field: Error RAM ID invalid.

## ◆ SDL_ESM_ERRORBITOFFSET_INVALID

#define SDL_ESM_ERRORBITOFFSET_INVALID (0xffffffffffffffffu)

Address field: Error Bit Error Offset invalid.

## ◆ SDL_ESM_ERRORBITGROUP_INVALID

#define SDL_ESM_ERRORBITGROUP_INVALID (0xffffffffu)

Address field: Error Bit Error Group invalid.

## ◆ SDL_ESM_MAX_EVENT_MAP_NUM_WORDS

#define SDL_ESM_MAX_EVENT_MAP_NUM_WORDS (32u)

Maximum number of EVENT words.

## ◆ SDL_ESM_ECC_PARAM_MCU_CPU0_SEC_ERROR

#define SDL_ESM_ECC_PARAM_MCU_CPU0_SEC_ERROR (1u)

MCU CPU0 detected 1-bit ECC error source.

## ◆ SDL_ESM_ECC_PARAM_MCU_CPU0_DED_ERROR

#define SDL_ESM_ECC_PARAM_MCU_CPU0_DED_ERROR (2u)

MCU CPU0 detected 2-bit ECC error source.

## ◆ SDL_ESM_ECC_PARAM_MCU_CPU1_SEC_ERROR

#define SDL_ESM_ECC_PARAM_MCU_CPU1_SEC_ERROR (3u)

MCU CPU1 detected 1-bit ECC error source.

## ◆ SDL_ESM_ECC_PARAM_MCU_CPU1_DED_ERROR

#define SDL_ESM_ECC_PARAM_MCU_CPU1_DED_ERROR (4u)

MCU CPU1 detected 2-bit ECC error source.

## ◆ SDL_ESM_ECC_PARAM_MCU_CBASS_SEC_ERROR

#define SDL_ESM_ECC_PARAM_MCU_CBASS_SEC_ERROR (5u)

MCU CBASS detected 1-bit ECC error source.

## ◆ SDL_ESM_ECC_PARAM_MCU_CBASS_DED_ERROR

#define SDL_ESM_ECC_PARAM_MCU_CBASS_DED_ERROR (6u)

MCU CBASS detected 2-bit ECC error source.

## ◆ SDL_ESM_ECC_PARAM_MAIN_MSMC_AGGR0_SEC_ERROR

#define SDL_ESM_ECC_PARAM_MAIN_MSMC_AGGR0_SEC_ERROR (10001u)

Main MSMC ECC AGGR0 detected 1-bit ECC error source.

## ◆ SDL_ESM_ECC_PARAM_MAIN_MSMC_AGGR0_DED_ERROR

#define SDL_ESM_ECC_PARAM_MAIN_MSMC_AGGR0_DED_ERROR (10002u)

Main MSMC ECC AGGR0 detected 2-bit ECC error source.

## ◆ SDL_ESM_ECC_PARAM_MAIN_A72_AGGR0_SEC_ERROR

#define SDL_ESM_ECC_PARAM_MAIN_A72_AGGR0_SEC_ERROR (10003u)

Main A72 ECC AGGR0 detected 1-bit ECC error source.

## ◆ SDL_ESM_ECC_PARAM_MAIN_A72_AGGR0_DED_ERROR

#define SDL_ESM_ECC_PARAM_MAIN_A72_AGGR0_DED_ERROR (10004u)

Main A72 ECC AGGR0 detected 2-bit ECC error source.

## Typedef Documentation

## ◆ SDL_Result

typedef int32_t SDL_Result

## ◆ sdlEsmEccErrorSource_t

typedef uint32_t sdlEsmEccErrorSource_t

Source of the ECC error which maps to the ESM interrupt source.

## ◆ SDL_ESM_applicationCallback

typedef int32_t(* SDL_ESM_applicationCallback) (SDL_ESM_Inst instance, SDL_ESM_IntType intrType, uint32_t grpChannel, uint32_t index, uint32_t intSrc, void *arg)

## Enumeration Type Documentation

## ◆ SDL_ESM_Inst

enum SDL_ESM_Inst

## \brief Defines the different ESM instance types

Enumerator
SDL_ESM_INST_MAIN_ESM0 | ESM0 (Main domain) instance
SDL_ESM_INSTANCE_MAX |

## ◆ SDL_ESM_IntType

enum SDL_ESM_IntType

## \brief This enumerator defines the values for ESM interrupt types

Enumerator
SDL_ESM_INT_TYPE_HI | Interrupt type Hi
SDL_ESM_INT_TYPE_LO | Interrupt type Lo
SDL_ESM_INT_TYPE_CFG | Interrupt type Config
SDL_ESM_INT_TYPE_MAX | Interrupt type Max

## Function Documentation

## ◆ SDL_ESM_getNErrorStatus()

int32_t SDL_ESM_getNErrorStatus | ( | SDL_ESM_Inst | instance,
|  | uint32_t * | pStatus
| ) |  |

SDL ESM API to get the status of the nError pin for the specified ESM instance.

============================================================================

Parameters

  instance | ESM Instance
  pStatus | Pointer to variable to store the status. If status is 1, then error pin is not active. If status is 0, then error pin is active.

Returns
  SDL_PASS if nError pin status is successfully retrieved. SDL_EBADARGS if instance or pStatus pointer are invalid. SDL_EFAIL if fail to read the error pin.

## ◆ SDL_ESM_getStaticRegisters()

int32_t SDL_ESM_getStaticRegisters | ( | SDL_ESM_Inst | instance,
|  | SDL_ESM_staticRegs * | pStaticRegs
| ) |  |

SDL ESM API to read the static registers. The API reads and returns the static register configuration for the ESM module for the specified instance. This API can be used by the application to read back the static configuration. Comparision of the static configuration registers against expected values is the responsibility of the application.

============================================================================

Parameters

  instance | ESM Instance
  pStaticRegs | Pointer to the static config register structure

Returns
  SDL_PASS if registers are successfully read. SDL_EBADARGS if instance or pStaticRegs are invalid.

## ◆ SDL_ESM_verifyConfig()

int32_t SDL_ESM_verifyConfig | ( | SDL_ESM_Inst | instance,
|  | const SDL_ESM_config * | pConfig
| ) |  |

SDL ESM API to verify the written configuration of the ESM module. The API verifies the written config that was done during SDL_ESM_init against the provided configuration.

============================================================================

Parameters

  instance | ESM Instance
  pConfig | Pointer to the ESM configuration to be used for verification.

Returns
  SDL_PASS if Verification passed SDL_EBADARGS if instance or pConfig are invalid. SDL_EFAIL if verification failed.

## ◆ SDL_ESM_clrNError()

int32_t SDL_ESM_clrNError | ( | SDL_ESM_Inst | instance | ) |

SDL ESM API to clear the nError pin for the specified ESM instance.

============================================================================

Parameters

  instance | ESM Instance

Returns
  SDL_PASS if nError pin status is successfully cleared. SDL_EBADARGS if instance is invalid.

## ◆ SDL_ESM_setNError()

int32_t SDL_ESM_setNError | ( | SDL_ESM_Inst | instance | ) |

SDL ESM API to set the nError pin for the specified ESM instance.

============================================================================

Parameters

  instance | ESM Instance

Returns
  SDL_PASS if nError pin status is successfully set. SDL_EBADARGS if instance is invalid.

## ◆ SDL_ESM_registerECCCallback()

int32_t SDL_ESM_registerECCCallback | ( | SDL_ESM_Inst | instance,
|  | uint32_t | eventBitMap[],
|  | SDL_ESM_applicationCallback | eccCallback,
|  | void * | callbackArg
| ) |  |

There are modules within SDL which will generate ESM errors intentionally in the course of running self-tests. The ECC module is one such module. To allow these modules to get the notification when the ESM error occurs, callback registration APIs are provided. The following APIs allow registration of a callback for specific events. This API is used by other SDL modules and not by the application.

============================================================================

Parameters

  instance | ESM Instance
  eventBitMap | Bitmap for ESM error event of interest for this callback. Array of uint32_t type with each bit representing one ESM error event.
  eccCallback | Pointer to the callback to be called by the ESM Handler to notify the ECC module of an ESM error event
  callbackArg | Argument that will be passed along with the callback.

Returns
  SDL_PASS if success. SDL_EBADARGS if invalid argument is passed. SDL_EFAIL if other failure.

## ◆ SDL_ESM_init()

int32_t SDL_ESM_init | ( | SDL_ESM_Inst | instance,
|  | const SDL_ESM_config * | pConfig,
|  | SDL_ESM_applicationCallback | applicationCallback,
|  | void * | appArg
| ) |  |

SDL ESM API to initialize an ESM instance. The API initializes the specified ESM instance with the provided configuration. The configuration will allow the application to specify for each event whether the interrupt is enabled or disabled, the priority of the event, and whether the nErrorPin assertion is enabled or disabled for the event.

============================================================================

Parameters

  instance | ESM Instance
  pConfig | Pointer to the ESM configuration structure
  applicationCallback | Pointer to the callback to be called by the ESM Handler to notify the application of an ESM error event.
  appArg | Application argument that will passed to the application when the application callback is called.

Returns
  SDL_PASS if success. SDL_EBADARGS if invalid argument is passed. SDL_EFAIL if other failure.

## ◆ SDL_ESM_setPinOutMode()

int32_t SDL_ESM_setPinOutMode | ( | SDL_ESM_Inst | instance,
|  | esmErrOutMode_t | pinOutMode
| ) |  |

This API is use to set error pin out mode(LEVEL or PWM). This API must be called after the below API- SDL_ESM_init.

============================================================================

Parameters

  instance | ESM Instance.
  pinOutMode | enum value to select error pin out mode. Refer enum esmErrOutMode_t.

Returns
  SDL_PASS - API success SDL_EBADARGS - Instance is not valid. SDL_EFAIL - Output (LVL or PWM) is not changed.

## ◆ SDL_ESM_registerCCMCallback()

int32_t SDL_ESM_registerCCMCallback | ( | SDL_ESM_Inst | instance,
|  | uint32_t | eventBitMap[],
|  | SDL_ESM_applicationCallback | ccmCallback,
|  | void * | callbackArg
| ) |  |

There are modules within SDL which will generate ESM errors intentionally in the course of running self-tests. The CCM module is one such module. To allow these modules to get the notification when the ESM error occurs, callback registration APIs are provided. The following APIs allow registration of a callback for specific events. This API is used by other SDL modules and not by the application.

============================================================================

Parameters

  instance | ESM Instance
  eventBitMap | Bitmap for ESM error event of interest for this callback. Array of uint32_t type with each bit representing one ESM error event.
  ccmCallback | Pointer to the callback to be called by the ESM Handler to notify the ECC module of an ESM error event
  callbackArg | Argument that will be passed along with the callback.

Returns
  SDL_PASS if success. SDL_EBADARGS if invalid argument is passed. SDL_EFAIL if other failure.

## ◆ SDL_ESM_hiInterruptHandler()

void SDL_ESM_hiInterruptHandler | ( | void * | arg | ) |

Esm Hi Interrupt Handler for MCU Esm Instance.

============================================================================

Parameters

  arg | argument for handler

## ◆ SDL_ESM_loInterruptHandler()

void SDL_ESM_loInterruptHandler | ( | void * | arg | ) |

Esm Lo Interrupt Handler for MCU Esm Instance.

============================================================================

Parameters

  arg | argument for handler

## ◆ SDL_ESM_configInterruptHandler()

void SDL_ESM_configInterruptHandler | ( | void * | arg | ) |

Esm Config Interrupt Handler for MCU Instance.

============================================================================

Parameters

  arg | argument for handler

## ◆ SDL_ESM_getIntNumber()

int32_t SDL_ESM_getIntNumber | ( | SDL_ESM_Inst | esmInstType,
|  | SDL_ESM_IntType | esmIntType
| ) |  |

Esm get Interrupt Number corresponding to the input interrupt type.

============================================================================

Parameters

  esmInstType | Instance of ESM
  esmIntType | ESM Interrupt type

Returns
  Interrupt Number or SDL_ESM_INTNUMBER_INVALID error

## ◆ SDL_ESM_getWarmResetReason()

int32_t SDL_ESM_getWarmResetReason | ( | void |  | ) |

Get the warm reset reason if it is generated by ESM.

============================================================================

Returns
  SDL_PASS if warm reset was by ESM. SDL_EFAIL if warm reset was not by ESM.

## ◆ SDL_ESM_enableESMWarmReset()

void SDL_ESM_enableESMWarmReset | ( | void |  | ) |

Enable ESM warm reset reason.

============================================================================