Common Microcontroller Functions
Hardware Abstraction Layer (HAL) API Reference

Data Structures

struct  RTCCRamData

Macros

#define PTA_SUPPORT
 
#define PTA_GPIOCFG_INPUT   GPIOCFG_IN_PUD
 
#define PTA_GPIOCFG_OUTPUT   GPIOCFG_OUT
 
#define PTA_GPIOCFG_WIRED_OR   GPIOCFG_OUT_OD
 
#define PTA_GPIOCFG_WIRED_AND   GPIOCFG_OUT_OD
 
#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)
 
#define halGetEm2xxResetInfo()   halGetResetInfo()
 Calls halGetExtendedResetInfo() and translates the EM35x or COBRA 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.

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 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.
 
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 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 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.

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

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

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

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.

Macro Definition Documentation

#define ADC_VECTOR_INDEX   27U
#define BASEBAND_VECTOR_INDEX   19U
#define BUS_FAULT_VECTOR_INDEX   5U
#define DEBUG_MONITOR_VECTOR_INDEX   12U
#define DEBUG_TOGGLE (   n)
#define DEBUG_VECTOR_INDEX   32U
#define GPIO_MASK   0xFFFFFF
#define GPIO_MASK_SIZE   24
#define halGetEm2xxResetInfo ( )    halGetResetInfo()

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
#define IRQA_VECTOR_INDEX   28U
#define IRQB_VECTOR_INDEX   29U
#define IRQC_VECTOR_INDEX   30U
#define IRQD_VECTOR_INDEX   31U
#define MAC_RX_VECTOR_INDEX   26U
#define MAC_TIMER_VECTOR_INDEX   24U
#define MAC_TX_VECTOR_INDEX   25U
#define MANAGEMENT_VECTOR_INDEX   18U
#define MEMORY_FAULT_VECTOR_INDEX   4U
#define MICRO_DISABLE_WATCH_DOG_KEY   0xA5U
#define NMI_VECTOR_INDEX   2U
#define PENDSV_VECTOR_INDEX   14U
#define PTA_GPIOCFG_INPUT   GPIOCFG_IN_PUD
#define PTA_GPIOCFG_OUTPUT   GPIOCFG_OUT
#define PTA_GPIOCFG_WIRED_AND   GPIOCFG_OUT_OD
#define PTA_GPIOCFG_WIRED_OR   GPIOCFG_OUT_OD
#define PTA_SUPPORT
#define RESERVED07_VECTOR_INDEX   7U
#define RESERVED08_VECTOR_INDEX   8U
#define RESERVED09_VECTOR_INDEX   9U
#define RESERVED10_VECTOR_INDEX   10U
#define RESERVED13_VECTOR_INDEX   13U
#define RESET_VECTOR_INDEX   1U
#define SC1_VECTOR_INDEX   21U
#define SC2_VECTOR_INDEX   22U
#define SC3_VECTOR_INDEX   33U
#define SC4_VECTOR_INDEX   34U
#define SECURITY_VECTOR_INDEX   23U
#define SLEEP_TIMER_VECTOR_INDEX   20U
#define STACK_VECTOR_INDEX   0U
#define SVCALL_VECTOR_INDEX   11U
#define SYSTICK_VECTOR_INDEX   15U
#define TIMER1_VECTOR_INDEX   16U
#define TIMER2_VECTOR_INDEX   17U
#define USAGE_FAULT_VECTOR_INDEX   6U
#define USB_VECTOR_INDEX   35U
#define VECTOR_TABLE_LENGTH   36U
#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
  • 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)

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
usThe specified time, in microseconds. Values should be between 1 and 65535 microseconds.
void halCommonDisableVreg1v8 ( void  )
Note
: Only used when DISABLE_INTERNAL_1V8_REGULATOR is defined.
void halCommonEnableVreg1v8 ( void  )
Note
: Only used when DISABLE_INTERNAL_1V8_REGULATOR is defined.
uint16_t halGetExtendedResetInfo ( void  )
Returns
A 16-bit code identifying the base and extended cause of the reset
PGM_P halGetExtendedResetString ( void  )

Useful for diagnostic printing of text just after program initialization.

Returns
A pointer to a program space string.
bool halGetRadioHoldOff ( void  )
Returns
true if Radio HoldOff has been enabled, false otherwise.
uint8_t halGetResetInfo ( void  )
Returns
A code identifying the cause of the reset.
PGM_P halGetResetString ( void  )

Useful for diagnostic printing of text just after program initialization.

Returns
A pointer to a program space string.
void halInit ( void  )
void halInternalDisableWatchDog ( uint8_t  magicKey)
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.
void halInternalEnableWatchDog ( void  )
void halInternalSysReset ( uint16_t  extendedCause)

Referenced by halSimEepromCallback().

bool halInternalWatchDogEnabled ( void  )
Returns
A bool value indicating if the watchdog is current enabled.
void halPowerDown ( void  )
void halPowerUp ( void  )
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  )
void halResume ( void  )
EmberStatus halSetRadioHoldOff ( bool  enable)
Parameters
enableWhen 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)
Note
This routine always enables interrupts.
Parameters
sleepModeA microcontroller sleep mode
See also
SleepModes

Referenced by usbSuspendDsr().

void halStackProcessBootCount ( void  )

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  )
void halStackRadio2PowerUpBoard ( void  )
void halStackRadioPowerDownBoard ( void  )
void halStackRadioPowerMainControl ( bool  powerUp)
void halStackRadioPowerUpBoard ( void  )
void halSuspend ( void  )

Variable Documentation

volatile int8_t halCommonVreg1v8EnableCount
Note
: Only used when DISABLE_INTERNAL_1V8_REGULATOR is defined.