Microcontroller functions

Description

Microcontroller functions.

Many of the supplied example applications use these microcontroller functions. See hal/micro/micro.h for source code.

Note
The term SFD refers to the Start Frame Delimiter.

See also hal/micro/cortexm3/micro.h for source code.

Functions

uint8_t halGetResetInfo (void)
 Gets information about what caused the microcontroller to reset.
 
const char * halGetResetString (void)
 Calls halGetResetInfo() and supplies a string describing it.
 
void halInit (void)
 Initializes microcontroller-specific peripherals.
 
void halReboot (void)
 Restarts the microcontroller and therefore everything else.
 
void halInternalEnableWatchDog (void)
 Enables the watchdog timer.
 
void halInternalDisableWatchDog (uint8_t magicKey)
 Disables the watchdog timer.
 
bool halInternalWatchDogEnabled (void)
 Determines whether the watchdog has been enabled or disabled.
 
void halResetWatchdog (void)
 
void halInternalSetCtune (uint16_t tune)
 Change the CTUNE value.
 
uint16_t halInternalGetCtune (void)
 Get the CTUNE value.
 
void halInternalSysReset (uint16_t extendedCause)
 Records the specified reset cause then forces a reboot.
 
uint16_t halGetExtendedResetInfo (void)
 Returns the Extended Reset Cause information.
 
uint8_t halGetEm2xxResetInfo (void)
 Calls halGetExtendedResetInfo() and translates the EM35x reset code to the corresponding value used by the EM2XX HAL.
 
const char * halGetExtendedResetString (void)
 Calls halGetExtendedResetInfo() and supplies a string describing the extended cause of the reset.
 

Macros

#define MICRO_DISABLE_WATCH_DOG_KEY   0xA5U
 The value that must be passed as the single parameter to halInternalDisableWatchDog() in order to successfully disable the watchdog timer.
 
#define EM2XX_RESET_UNKNOWN   0
 EM2xx-compatible reset code returned by halGetEm2xxResetInfo()
 
#define EM2XX_RESET_EXTERNAL   1
 
#define EM2XX_RESET_POWERON   2
 
#define EM2XX_RESET_WATCHDOG   3
 
#define EM2XX_RESET_ASSERT   6
 
#define EM2XX_RESET_BOOTLOADER   9
 
#define EM2XX_RESET_SOFTWARE   11
 

Vector Table Index Definitions

These are numerical definitions for vector table.

Only Cortex-M standard exception vectors (indices 0 through 15) are represented since device specific vectors can be (and often are) different across dies.

#define STACK_VECTOR_INDEX   0U
 A numerical definition for a vector.
 
#define RESET_VECTOR_INDEX   1U
 
#define NMI_VECTOR_INDEX   2U
 
#define HARD_FAULT_VECTOR_INDEX   3U
 
#define MEMORY_FAULT_VECTOR_INDEX   4U
 
#define BUS_FAULT_VECTOR_INDEX   5U
 
#define USAGE_FAULT_VECTOR_INDEX   6U
 
#define RESERVED07_VECTOR_INDEX   7U
 
#define RESERVED08_VECTOR_INDEX   8U
 
#define RESERVED09_VECTOR_INDEX   9U
 
#define RESERVED10_VECTOR_INDEX   10U
 
#define SVCALL_VECTOR_INDEX   11U
 
#define DEBUG_MONITOR_VECTOR_INDEX   12U
 
#define RESERVED13_VECTOR_INDEX   13U
 
#define PENDSV_VECTOR_INDEX   14U
 
#define SYSTICK_VECTOR_INDEX   15U
 
#define IRQ_TO_VECTOR_NUMBER(x)   ((x) + 16U)
 Utility macro to convert from IRQ numbers to exception numbers/ vector indices.
 
#define VECTOR_TABLE_LENGTH   (IRQ_TO_VECTOR_NUMBER(EXT_IRQ_COUNT))
 Number of vectors.
 

Function Documentation

◆ halGetResetInfo()

uint8_t halGetResetInfo ( void  )

Gets information about what caused the microcontroller to reset.

Returns
A code identifying the cause of the reset.

◆ halGetResetString()

const char* halGetResetString ( void  )

Calls halGetResetInfo() and supplies a string describing it.

@appusage Useful for diagnostic printing of text just after program initialization.

Returns
A pointer to a program space string.

◆ halInit()

void halInit ( void  )

Initializes microcontroller-specific peripherals.

◆ halReboot()

void halReboot ( void  )

Restarts the microcontroller and therefore everything else.

◆ halInternalEnableWatchDog()

void halInternalEnableWatchDog ( void  )

Enables the watchdog timer.

◆ halInternalDisableWatchDog()

void halInternalDisableWatchDog ( uint8_t  magicKey)

Disables the watchdog timer.

Note
To prevent the watchdog from being disabled accidentally, a magic key must be provided.
Parameters
magicKeyA value (MICRO_DISABLE_WATCH_DOG_KEY) that enables the function.

◆ halInternalWatchDogEnabled()

bool halInternalWatchDogEnabled ( void  )

Determines whether the watchdog has been enabled or disabled.

Returns
A bool value indicating if the watchdog is current enabled.

◆ halInternalSetCtune()

void halInternalSetCtune ( uint16_t  tune)

Change the CTUNE value.

Involves switching to HFRCO and turning off the HFXO temporarily.

Parameters
tuneValue to set CTUNE to.

◆ halInternalGetCtune()

uint16_t halInternalGetCtune ( void  )

Get the CTUNE value.

Returns
Current CTUNE value.

◆ halInternalSysReset()

void halInternalSysReset ( uint16_t  extendedCause)

Records the specified reset cause then forces a reboot.

◆ halGetExtendedResetInfo()

uint16_t halGetExtendedResetInfo ( void  )

Returns the Extended Reset Cause information.

Returns
A 16-bit code identifying the base and extended cause of the reset

◆ halGetEm2xxResetInfo()

uint8_t halGetEm2xxResetInfo ( void  )

Calls halGetExtendedResetInfo() and translates the EM35x reset code to the corresponding value used by the EM2XX HAL.

Any reset codes not present in the EM2XX are returned after being OR'ed with 0x80.

@appusage Used by the EZSP host as a platform-independent NCP reset code.

Returns
The EM2XX-compatible reset code. If not supported by the EM2XX, return the platform-specific code with B7 set.

◆ halGetExtendedResetString()

const char* halGetExtendedResetString ( void  )

Calls halGetExtendedResetInfo() and supplies a string describing the extended cause of the reset.

halGetResetString() should also be called to get the string for the base reset cause

@appusage Useful for diagnostic printing of text just after program initialization.

Returns
A pointer to a program space string.

Macro Definition Documentation

◆ MICRO_DISABLE_WATCH_DOG_KEY

#define MICRO_DISABLE_WATCH_DOG_KEY   0xA5U

The value that must be passed as the single parameter to halInternalDisableWatchDog() in order to successfully disable the watchdog timer.

◆ STACK_VECTOR_INDEX

#define STACK_VECTOR_INDEX   0U

A numerical definition for a vector.

◆ IRQ_TO_VECTOR_NUMBER

#define IRQ_TO_VECTOR_NUMBER (   x)    ((x) + 16U)

Utility macro to convert from IRQ numbers to exception numbers/ vector indices.

These are different because the latter include the Cortex-M standard exceptions while the former do not.

◆ VECTOR_TABLE_LENGTH

#define VECTOR_TABLE_LENGTH   (IRQ_TO_VECTOR_NUMBER(EXT_IRQ_COUNT))

Number of vectors.

EXT_IRQ_COUNT is defined in the device header but does not include the Cortex-M standard exceptions.

◆ EM2XX_RESET_UNKNOWN

#define EM2XX_RESET_UNKNOWN   0

EM2xx-compatible reset code returned by halGetEm2xxResetInfo()