Common Microcontroller Functions
Hardware Abstraction Layer (HAL) API Reference

Data Structures

struct RTCCRamData

Macros

#define halGetEm2xxResetInfo () halGetResetInfo ()
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.
#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 GPIO_MASK_SIZE 24
#define GPIO_MASK 0xFFFFFF
#define WAKE_GPIO_MASK GPIO_MASK
#define WAKE_GPIO_SIZE GPIO_MASK_SIZE
#define WAKE_MASK_INVALID (-1)
#define WAKE_EVENT_SIZE WakeMask
#define DEBUG_TOGGLE (n)

Typedefs

typedef uint32_t WakeEvents
typedef uint32_t WakeMask

Enumerations

enum SleepModes {
SLEEPMODE_RUNNING = 0U,
SLEEPMODE_IDLE = 1U,
SLEEPMODE_WAKETIMER = 2U,
SLEEPMODE_MAINTAINTIMER = 3U,
SLEEPMODE_NOTIMER = 4U,
SLEEPMODE_HIBERNATE = 5U,
SLEEPMODE_RESERVED = 6U,
SLEEPMODE_POWERDOWN = 7U,
SLEEPMODE_POWERSAVE = 8U
}
Enumerations for the possible microcontroller sleep modes.

Functions

void halStackProcessBootCount (void)
Called from emberInit and provides a means for the HAL to increment a boot counter, most commonly in non-volatile memory.
uint8_t halGetResetInfo (void)
Gets information about what caused the microcontroller to reset.
PGM_P 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 halPowerUp (void)
Powers up microcontroller peripherals and board peripherals.
void halPowerDown (void)
Powers down microcontroller peripherals and board peripherals.
void halResume (void)
Resumes microcontroller peripherals and board peripherals.
void halSuspend (void)
Suspends microcontroller peripherals and board peripherals.
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 halSleep ( SleepModes sleepMode)
Puts the microcontroller to sleep in a specified mode.
void halSleepPreserveInts ( SleepModes sleepMode)
Same as halSleep() except it preserves the current interrupt state rather than always enabling interrupts prior to returning.
void halCommonDelayMicroseconds (uint16_t us)
Blocks the current thread of execution for the specified amount of time, in microseconds.
void halCommonDisableVreg1v8 (void)
Disable the 1.8V regulator. This function is to be used when the 1.8V supply is provided externally. Disabling the regulator saves current consumption. Disabling the regulator will cause ADC readings of external signals to be wrong. These exteranl signals include analog sources ADC0 thru ADC5 and VDD_PADS/4.
void halCommonEnableVreg1v8 (void)
Enable the 1.8V regulator. Normally the 1.8V regulator is enabled out of reset. This function is only needed if the 1.8V regulator has been disabled and ADC conversions on external signals are needed. These exteranl signals include analog sources ADC0 thru ADC5 and VDD_PADS/4. The state of 1v8 survives deep sleep.
void halBeforeEM4 (uint32_t duration, RTCCRamData input)
RTCCRamData halAfterEM4 (void)
void halInternalSysReset (uint16_t extendedCause)
Records the specified reset cause then forces a reboot.
uint16_t halGetExtendedResetInfo (void)
Returns the Extended Reset Cause information.
PGM_P 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.
EmberStatus halSetRadioHoldOff (bool enable)
Enables or disables Radio HoldOff support.
bool halGetRadioHoldOff (void)
Returns whether Radio HoldOff has been enabled or not.
void halStackRadioPowerDownBoard (void)
To assist with saving power when the radio automatically powers down, this function allows the stack to tell the HAL to put pins specific to radio functionality in their powerdown state. The pin state used is the state used by halInternalPowerDownBoard, but applied only to the pins identified in the global variable gpioRadioPowerBoardMask. The stack will automatically call this function as needed, but it will only change GPIO state based on gpioRadioPowerBoardMask. Most commonly, the bits set in gpioRadioPowerBoardMask petain to using a Front End Module. This function is often called from interrupt context.
void halStackRadio2PowerDownBoard (void)
To assist with saving power when radio2 automatically powers down, this function allows the stack to tell the HAL to put pins specific to radio functionality in their powerdown state. The pin state used is the state used by halInternalPowerDownBoard, but applied only to the pins identified in the global variable gpioRadioPowerBoardMask. The stack will automatically call this function as needed, but it will only change GPIO state based on gpioRadioPowerBoardMask. Most commonly, the bits set in gpioRadioPowerBoardMask petain to using a Front End Module. This function is often called from interrupt context.
void halStackRadioPowerUpBoard (void)
To assist with saving power when the radio automatically powers up, this function allows the stack to tell the HAL to put pins specific to radio functionality in their powerup state. The pin state used is the state used by halInternalPowerUpBoard, but applied only to the pins identified in the global variable gpioRadioPowerBoardMask. The stack will automatically call this function as needed, but it will only change GPIO state based on gpioRadioPowerBoardMask. Most commonly, the bits set in gpioRadioPowerBoardMask petain to using a Front End Module. This function can be called from interrupt context.
void halStackRadio2PowerUpBoard (void)
To assist with saving power when radio2 automatically powers up, this function allows the stack to tell the HAL to put pins specific to radio functionality in their powerup state. The pin state used is the state used by halInternalPowerUpBoard, but applied only to the pins identified in the global variable gpioRadioPowerBoardMask. The stack will automatically call this function as needed, but it will only change GPIO state based on gpioRadioPowerBoardMask. Most commonly, the bits set in gpioRadioPowerBoardMask petain to using a Front End Module. This function can be called from interrupt context.
void halStackRadioPowerMainControl (bool powerUp)
This function is called automatically by the stack prior to Radio power-up and after Radio power-down. It can be used to prepare for the radio being powered on and to clean up after it's been powered off. Unlike halStackRadioPowerUpBoard() and halStackRadioPowerDownBoard() , which can be called from interrupt context, this function is only called from main-line context.
void halRadioPowerUpHandler (void)
Handler called in main context prior to radio being powered on.
void halRadioPowerDownHandler (void)
Handler called in main context after radio has been powered off.

Variables

volatile int8_t halCommonVreg1v8EnableCount
Helper variable to track the state of 1.8V regulator.

Vector Table Index Definitions

These are numerical definitions for vector table. Indices 0 through 15 are Cortex-M3 standard exception vectors and indices 16 through 35 are EM3XX specific interrupt vectors.

#define STACK_VECTOR_INDEX 0U
A numerical definition for a vector.
#define RESET_VECTOR_INDEX 1U
A numerical definition for a vector.
#define NMI_VECTOR_INDEX 2U
A numerical definition for a vector.
#define HARD_FAULT_VECTOR_INDEX 3U
A numerical definition for a vector.
#define MEMORY_FAULT_VECTOR_INDEX 4U
A numerical definition for a vector.
#define BUS_FAULT_VECTOR_INDEX 5U
A numerical definition for a vector.
#define USAGE_FAULT_VECTOR_INDEX 6U
A numerical definition for a vector.
#define RESERVED07_VECTOR_INDEX 7U
A numerical definition for a vector.
#define RESERVED08_VECTOR_INDEX 8U
A numerical definition for a vector.
#define RESERVED09_VECTOR_INDEX 9U
A numerical definition for a vector.
#define RESERVED10_VECTOR_INDEX 10U
A numerical definition for a vector.
#define SVCALL_VECTOR_INDEX 11U
A numerical definition for a vector.
#define DEBUG_MONITOR_VECTOR_INDEX 12U
A numerical definition for a vector.
#define RESERVED13_VECTOR_INDEX 13U
A numerical definition for a vector.
#define PENDSV_VECTOR_INDEX 14U
A numerical definition for a vector.
#define SYSTICK_VECTOR_INDEX 15U
A numerical definition for a vector.
#define TIMER1_VECTOR_INDEX 16U
A numerical definition for a vector.
#define TIMER2_VECTOR_INDEX 17U
A numerical definition for a vector.
#define MANAGEMENT_VECTOR_INDEX 18U
A numerical definition for a vector.
#define BASEBAND_VECTOR_INDEX 19U
A numerical definition for a vector.
#define SLEEP_TIMER_VECTOR_INDEX 20U
A numerical definition for a vector.
#define SC1_VECTOR_INDEX 21U
A numerical definition for a vector.
#define SC2_VECTOR_INDEX 22U
A numerical definition for a vector.
#define SECURITY_VECTOR_INDEX 23U
A numerical definition for a vector.
#define MAC_TIMER_VECTOR_INDEX 24U
A numerical definition for a vector.
#define MAC_TX_VECTOR_INDEX 25U
A numerical definition for a vector.
#define MAC_RX_VECTOR_INDEX 26U
A numerical definition for a vector.
#define ADC_VECTOR_INDEX 27U
A numerical definition for a vector.
#define IRQA_VECTOR_INDEX 28U
A numerical definition for a vector.
#define IRQB_VECTOR_INDEX 29U
A numerical definition for a vector.
#define IRQC_VECTOR_INDEX 30U
A numerical definition for a vector.
#define IRQD_VECTOR_INDEX 31U
A numerical definition for a vector.
#define DEBUG_VECTOR_INDEX 32U
A numerical definition for a vector.
#define SC3_VECTOR_INDEX 33U
A numerical definition for a vector.
#define SC4_VECTOR_INDEX 34U
A numerical definition for a vector.
#define USB_VECTOR_INDEX 35U
A numerical definition for a vector.
#define VECTOR_TABLE_LENGTH 36U
Number of vectors.

Detailed Description

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.

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

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

Macro Definition Documentation

#define ADC_VECTOR_INDEX   27U

A numerical definition for a vector.

#define BASEBAND_VECTOR_INDEX   19U

A numerical definition for a vector.

#define BUS_FAULT_VECTOR_INDEX   5U

A numerical definition for a vector.

#define DEBUG_MONITOR_VECTOR_INDEX   12U

A numerical definition for a vector.

#define DEBUG_TOGGLE ( n )
#define DEBUG_VECTOR_INDEX   32U

A numerical definition for a vector.

#define GPIO_MASK   0xFFFFFF
#define GPIO_MASK_SIZE   24
#define halGetEm2xxResetInfo ( ) halGetResetInfo ()

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.

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.
#define HARD_FAULT_VECTOR_INDEX   3U

A numerical definition for a vector.

#define IRQA_VECTOR_INDEX   28U

A numerical definition for a vector.

#define IRQB_VECTOR_INDEX   29U

A numerical definition for a vector.

#define IRQC_VECTOR_INDEX   30U

A numerical definition for a vector.

#define IRQD_VECTOR_INDEX   31U

A numerical definition for a vector.

#define MAC_RX_VECTOR_INDEX   26U

A numerical definition for a vector.

#define MAC_TIMER_VECTOR_INDEX   24U

A numerical definition for a vector.

#define MAC_TX_VECTOR_INDEX   25U

A numerical definition for a vector.

#define MANAGEMENT_VECTOR_INDEX   18U

A numerical definition for a vector.

#define MEMORY_FAULT_VECTOR_INDEX   4U

A numerical definition for a vector.

#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 NMI_VECTOR_INDEX   2U

A numerical definition for a vector.

#define PENDSV_VECTOR_INDEX   14U

A numerical definition for a vector.

#define RESERVED07_VECTOR_INDEX   7U

A numerical definition for a vector.

#define RESERVED08_VECTOR_INDEX   8U

A numerical definition for a vector.

#define RESERVED09_VECTOR_INDEX   9U

A numerical definition for a vector.

#define RESERVED10_VECTOR_INDEX   10U

A numerical definition for a vector.

#define RESERVED13_VECTOR_INDEX   13U

A numerical definition for a vector.

#define RESET_VECTOR_INDEX   1U

A numerical definition for a vector.

#define SC1_VECTOR_INDEX   21U

A numerical definition for a vector.

#define SC2_VECTOR_INDEX   22U

A numerical definition for a vector.

#define SC3_VECTOR_INDEX   33U

A numerical definition for a vector.

#define SC4_VECTOR_INDEX   34U

A numerical definition for a vector.

#define SECURITY_VECTOR_INDEX   23U

A numerical definition for a vector.

#define SLEEP_TIMER_VECTOR_INDEX   20U

A numerical definition for a vector.

#define STACK_VECTOR_INDEX   0U

A numerical definition for a vector.

#define SVCALL_VECTOR_INDEX   11U

A numerical definition for a vector.

#define SYSTICK_VECTOR_INDEX   15U

A numerical definition for a vector.

#define TIMER1_VECTOR_INDEX   16U

A numerical definition for a vector.

#define TIMER2_VECTOR_INDEX   17U

A numerical definition for a vector.

#define USAGE_FAULT_VECTOR_INDEX   6U

A numerical definition for a vector.

#define USB_VECTOR_INDEX   35U

A numerical definition for a vector.

#define VECTOR_TABLE_LENGTH   36U

Number of vectors.

#define WAKE_EVENT_SIZE WakeMask
Note
The preprocessor symbol WAKE_EVENT_SIZE has been deprecated. Please use WakeMask instead.
#define WAKE_GPIO_MASK GPIO_MASK
#define WAKE_GPIO_SIZE GPIO_MASK_SIZE
#define WAKE_MASK_INVALID   (-1)

Typedef Documentation

typedef uint32_t WakeEvents
typedef uint32_t WakeMask

Enumeration Type Documentation

enum SleepModes

Enumerations for the possible microcontroller sleep modes.

  • SLEEPMODE_RUNNING Everything is active and running. In practice this mode is not used, but it is defined for completeness of information.
  • SLEEPMODE_IDLE Only the CPU is idled. The rest of the chip continues running normally. The chip will wake from any interrupt.
  • SLEEPMODE_WAKETIMER The sleep timer clock sources remain running. The RC is always running and the 32kHz XTAL depends on the board header. Wakeup is possible from both GPIO and the sleep timer. System time is maintained. The sleep timer is assumed to be configured properly for wake events.
  • SLEEPMODE_MAINTAINTIMER The sleep timer clock sources remain running. The RC is always running and the 32kHz XTAL depends on the board header. Wakeup is possible from only GPIO. System time is maintained. NOTE: This mode is not available on EM2XX chips.
  • SLEEPMODE_NOTIMER The sleep timer clock sources (both RC and XTAL) are turned off. Wakeup is possible from only GPIO. System time is lost.
  • SLEEPMODE_HIBERNATE This maps to EM4 Hibernate on the EFM32/EFR32 devices. RAM is not retained in SLEEPMODE_HIBERNATE so waking up from this sleepmode will behave like a reset. NOTE: This mode is only available on EFM32/EFR32
Enumerator
SLEEPMODE_RUNNING
SLEEPMODE_IDLE
SLEEPMODE_WAKETIMER
SLEEPMODE_MAINTAINTIMER
SLEEPMODE_NOTIMER
SLEEPMODE_HIBERNATE
SLEEPMODE_RESERVED
SLEEPMODE_POWERDOWN
SLEEPMODE_POWERSAVE

Function Documentation

RTCCRamData halAfterEM4 ( void )
void halBeforeEM4 ( uint32_t duration,
RTCCRamData input
)
void halCommonDelayMicroseconds ( uint16_t us )

Blocks the current thread of execution for the specified amount of time, in microseconds.

The function is implemented with cycle-counted busy loops and is intended to create the short delays required when interfacing with hardware peripherals.

The accuracy of the timing provided by this function is not specified, but a general rule is that when running off of a crystal oscillator it will be within 10us. If the micro is running off of another type of oscillator (e.g. RC) the timing accuracy will potentially be much worse.

Parameters
us The specified time, in microseconds. Values should be between 1 and 65535 microseconds.
void halCommonDisableVreg1v8 ( void )

Disable the 1.8V regulator. This function is to be used when the 1.8V supply is provided externally. Disabling the regulator saves current consumption. Disabling the regulator will cause ADC readings of external signals to be wrong. These exteranl signals include analog sources ADC0 thru ADC5 and VDD_PADS/4.

Note
: Only used when DISABLE_INTERNAL_1V8_REGULATOR is defined.
void halCommonEnableVreg1v8 ( void )

Enable the 1.8V regulator. Normally the 1.8V regulator is enabled out of reset. This function is only needed if the 1.8V regulator has been disabled and ADC conversions on external signals are needed. These exteranl signals include analog sources ADC0 thru ADC5 and VDD_PADS/4. The state of 1v8 survives deep sleep.

Note
: Only used when DISABLE_INTERNAL_1V8_REGULATOR is defined.
uint16_t halGetExtendedResetInfo ( void )

Returns the Extended Reset Cause information.

Returns
A 16-bit code identifying the base and extended cause of the reset
PGM_P 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.

Useful for diagnostic printing of text just after program initialization.

Returns
A pointer to a program space string.
bool halGetRadioHoldOff ( void )

Returns whether Radio HoldOff has been enabled or not.

Returns
true if Radio HoldOff has been enabled, false otherwise.
uint8_t halGetResetInfo ( void )

Gets information about what caused the microcontroller to reset.

Returns
A code identifying the cause of the reset.
PGM_P halGetResetString ( void )

Calls halGetResetInfo() and supplies a string describing it.

Useful for diagnostic printing of text just after program initialization.

Returns
A pointer to a program space string.
void halInit ( void )

Initializes microcontroller-specific peripherals.

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
magicKey A value ( MICRO_DISABLE_WATCH_DOG_KEY ) that enables the function.
void halInternalEnableWatchDog ( void )

Enables the watchdog timer.

void halInternalSysReset ( uint16_t extendedCause )

Records the specified reset cause then forces a reboot.

bool halInternalWatchDogEnabled ( void )

Determines whether the watchdog has been enabled or disabled.

Returns
A bool value indicating if the watchdog is current enabled.
void halPowerDown ( void )

Powers down microcontroller peripherals and board peripherals.

void halPowerUp ( void )

Powers up microcontroller peripherals and board peripherals.

void halRadioPowerDownHandler ( void )

Handler called in main context after radio has been powered off.

void halRadioPowerUpHandler ( void )

Handler called in main context prior to radio being powered on.

void halReboot ( void )

Restarts the microcontroller and therefore everything else.

void halResume ( void )

Resumes microcontroller peripherals and board peripherals.

EmberStatus halSetRadioHoldOff ( bool enable )

Enables or disables Radio HoldOff support.

Parameters
enable When true, configures RHO_GPIO in BOARD_HEADER as an input which, when asserted, will prevent the radio from transmitting. When false, configures RHO_GPIO for its original default purpose.
Returns
EMBER_SUCCESS if Radio HoldOff was configured as desired or EMBER_BAD_ARGUMENT if requesting it be enabled but RHO has not been configured by the BOARD_HEADER.
void halSleep ( SleepModes sleepMode )

Puts the microcontroller to sleep in a specified mode.

Note
This routine always enables interrupts.
Parameters
sleepMode A microcontroller sleep mode
See also
SleepModes
void halSleepPreserveInts ( SleepModes sleepMode )

Same as halSleep() except it preserves the current interrupt state rather than always enabling interrupts prior to returning.

Parameters
sleepMode A microcontroller sleep mode
See also
SleepModes
void halStackProcessBootCount ( void )

Called from emberInit and provides a means for the HAL to increment a boot counter, most commonly in non-volatile memory.

This is useful while debugging to determine the number of resets that might be seen over a period of time. Exposing this functionality allows the application to disable or alter processing of the boot counter if, for example, the application is expecting a lot of resets that could wear out non-volatile storage or some

Called from emberInit only as helpful debugging information. This should be left enabled by default, but this function can also be reduced to a simple return statement if boot counting is not desired.

void halStackRadio2PowerDownBoard ( void )

To assist with saving power when radio2 automatically powers down, this function allows the stack to tell the HAL to put pins specific to radio functionality in their powerdown state. The pin state used is the state used by halInternalPowerDownBoard, but applied only to the pins identified in the global variable gpioRadioPowerBoardMask. The stack will automatically call this function as needed, but it will only change GPIO state based on gpioRadioPowerBoardMask. Most commonly, the bits set in gpioRadioPowerBoardMask petain to using a Front End Module. This function is often called from interrupt context.

void halStackRadio2PowerUpBoard ( void )

To assist with saving power when radio2 automatically powers up, this function allows the stack to tell the HAL to put pins specific to radio functionality in their powerup state. The pin state used is the state used by halInternalPowerUpBoard, but applied only to the pins identified in the global variable gpioRadioPowerBoardMask. The stack will automatically call this function as needed, but it will only change GPIO state based on gpioRadioPowerBoardMask. Most commonly, the bits set in gpioRadioPowerBoardMask petain to using a Front End Module. This function can be called from interrupt context.

void halStackRadioPowerDownBoard ( void )

To assist with saving power when the radio automatically powers down, this function allows the stack to tell the HAL to put pins specific to radio functionality in their powerdown state. The pin state used is the state used by halInternalPowerDownBoard, but applied only to the pins identified in the global variable gpioRadioPowerBoardMask. The stack will automatically call this function as needed, but it will only change GPIO state based on gpioRadioPowerBoardMask. Most commonly, the bits set in gpioRadioPowerBoardMask petain to using a Front End Module. This function is often called from interrupt context.

void halStackRadioPowerMainControl ( bool powerUp )

This function is called automatically by the stack prior to Radio power-up and after Radio power-down. It can be used to prepare for the radio being powered on and to clean up after it's been powered off. Unlike halStackRadioPowerUpBoard() and halStackRadioPowerDownBoard() , which can be called from interrupt context, this function is only called from main-line context.

void halStackRadioPowerUpBoard ( void )

To assist with saving power when the radio automatically powers up, this function allows the stack to tell the HAL to put pins specific to radio functionality in their powerup state. The pin state used is the state used by halInternalPowerUpBoard, but applied only to the pins identified in the global variable gpioRadioPowerBoardMask. The stack will automatically call this function as needed, but it will only change GPIO state based on gpioRadioPowerBoardMask. Most commonly, the bits set in gpioRadioPowerBoardMask petain to using a Front End Module. This function can be called from interrupt context.

void halSuspend ( void )

Suspends microcontroller peripherals and board peripherals.

Variable Documentation

volatile int8_t halCommonVreg1v8EnableCount

Helper variable to track the state of 1.8V regulator.

Note
: Only used when DISABLE_INTERNAL_1V8_REGULATOR is defined.