SAM Brown Out Detector (BOD) Driver

This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's Brown Out Detector (BOD) modules, to detect and respond to under-voltage events and take an appropriate action.

The following peripheral is used by this module:

• SYSCTRL (System Control)

The following devices can use this module:

• Atmel | SMART SAM D20/D21
• Atmel | SMART SAM R21
• Atmel | SMART SAM D10/D11
• Atmel | SMART SAM DA1
• Atmel | SMART SAM HA1

The outline of this documentation is as follows:

• Prerequisites
• Module Overview
• Special Considerations
• Extra Information
• Examples
• API Overview

Prerequisites

There are no prerequisites for this module.

Module Overview

The SAM devices contain a number of Brown Out Detector (BOD) modules. Each BOD monitors the supply voltage for any dips that go below the set threshold for the module. In case of a BOD detection the BOD will either reset the system or raise a hardware interrupt so that a safe power-down sequence can be attempted.

Special Considerations

The time between a BOD interrupt being raised and a failure of the processor to continue executing (in the case of a core power failure) is system specific; care must be taken that all critical BOD detection events can complete within the amount of time available.

Extra Information

For extra information, see Extra Information for BOD Driver. This includes:

• Acronyms
• Dependencies
• Errata
• Module History

Examples

For a list of examples related to this driver, see Examples for BOD Driver.

API Overview

Data Structures
struct	bod_config
	Configuration structure for a BOD module. More...

Enumerations
enum	bod { BOD_BOD33 }
	Brown Out Detector hardware instance IDs. More...
enum	bod_action {   BOD_ACTION_NONE = SYSCTRL_BOD33_ACTION(0),   BOD_ACTION_RESET = SYSCTRL_BOD33_ACTION(1),   BOD_ACTION_INTERRUPT = SYSCTRL_BOD33_ACTION(2) }
	Brown Out Detector detection actions. More...
enum	bod_mode {   BOD_MODE_CONTINUOUS = 0,   BOD_MODE_SAMPLED = SYSCTRL_BOD33_MODE }
	Brown Out Detector sampling modes. More...
enum	bod_prescale {   BOD_PRESCALE_DIV_2 = SYSCTRL_BOD33_PSEL(0),   BOD_PRESCALE_DIV_4 = SYSCTRL_BOD33_PSEL(1),   BOD_PRESCALE_DIV_8 = SYSCTRL_BOD33_PSEL(2),   BOD_PRESCALE_DIV_16 = SYSCTRL_BOD33_PSEL(3),   BOD_PRESCALE_DIV_32 = SYSCTRL_BOD33_PSEL(4),   BOD_PRESCALE_DIV_64 = SYSCTRL_BOD33_PSEL(5),   BOD_PRESCALE_DIV_128 = SYSCTRL_BOD33_PSEL(6),   BOD_PRESCALE_DIV_256 = SYSCTRL_BOD33_PSEL(7),   BOD_PRESCALE_DIV_512 = SYSCTRL_BOD33_PSEL(8),   BOD_PRESCALE_DIV_1024 = SYSCTRL_BOD33_PSEL(9),   BOD_PRESCALE_DIV_2048 = SYSCTRL_BOD33_PSEL(10),   BOD_PRESCALE_DIV_4096 = SYSCTRL_BOD33_PSEL(11),   BOD_PRESCALE_DIV_8192 = SYSCTRL_BOD33_PSEL(12),   BOD_PRESCALE_DIV_16384 = SYSCTRL_BOD33_PSEL(13),   BOD_PRESCALE_DIV_32768 = SYSCTRL_BOD33_PSEL(14),   BOD_PRESCALE_DIV_65536 = SYSCTRL_BOD33_PSEL(15) }
	Brown Out Detector input clock prescale values. More...

Configuration and Initialization
static void	bod_get_config_defaults (struct bod_config *const conf)
	Get default BOD configuration. More...
enum status_code	bod_set_config (const enum bod bod_id, struct bod_config *const conf)
	Configure a Brown Out Detector module. More...
static enum status_code	bod_enable (const enum bod bod_id)
	Enables a configured BOD module. More...
static enum status_code	bod_disable (const enum bod bod_id)
	Disables an enabled BOD module. More...
static bool	bod_is_detected (const enum bod bod_id)
	Checks if a specified BOD low voltage detection has occurred. More...
static void	bod_clear_detected (const enum bod bod_id)
	Clears the low voltage detection state of a specified BOD. More...

enum bod

Brown Out Detector hardware instance IDs.

List of possible BOD controllers within the device.

Enumerator
BOD_BOD33	BOD33 External I/O voltage.

enum bod_action

Brown Out Detector detection actions.

List of possible BOD actions when a BOD module detects a brown out condition.

Enumerator
BOD_ACTION_NONE	A BOD detect will do nothing, and the BOD state can't be polled.
BOD_ACTION_RESET	A BOD detect will reset the device.
BOD_ACTION_INTERRUPT	A BOD detect will fire an interrupt.

enum bod_mode

Brown Out Detector sampling modes.

List of possible BOD module voltage sampling modes.

Enumerator
BOD_MODE_CONTINUOUS	BOD will sample the supply line continuously.
BOD_MODE_SAMPLED	BOD will use the BOD sampling clock (1KHz) to sample the supply line.

enum bod_prescale

Brown Out Detector input clock prescale values.

List of possible BOD controller prescaler values, to reduce the sampling speed of a BOD to lower the power consumption.

Enumerator
BOD_PRESCALE_DIV_2	Divide input prescaler clock by 2.
BOD_PRESCALE_DIV_4	Divide input prescaler clock by 4.
BOD_PRESCALE_DIV_8	Divide input prescaler clock by 8.
BOD_PRESCALE_DIV_16	Divide input prescaler clock by 16.
BOD_PRESCALE_DIV_32	Divide input prescaler clock by 32.
BOD_PRESCALE_DIV_64	Divide input prescaler clock by 64.
BOD_PRESCALE_DIV_128	Divide input prescaler clock by 128.
BOD_PRESCALE_DIV_256	Divide input prescaler clock by 256.
BOD_PRESCALE_DIV_512	Divide input prescaler clock by 512.
BOD_PRESCALE_DIV_1024	Divide input prescaler clock by 1024.
BOD_PRESCALE_DIV_2048	Divide input prescaler clock by 2048.
BOD_PRESCALE_DIV_4096	Divide input prescaler clock by 4096.
BOD_PRESCALE_DIV_8192	Divide input prescaler clock by 8192.
BOD_PRESCALE_DIV_16384	Divide input prescaler clock by 16384.
BOD_PRESCALE_DIV_32768	Divide input prescaler clock by 32768.
BOD_PRESCALE_DIV_65536	Divide input prescaler clock by 65536.

static void bod_clear_detected ( const enum bod  bod_id )

inlinestatic

Clears the low voltage detection state of a specified BOD.

Clears the low voltage condition of a specified BOD module, so that new low voltage conditions can be detected.

Parameters

[in]

bod_id

BOD module to clear

References Assert, and BOD_BOD33.

Referenced by run_bod_test().

static enum status_code bod_disable ( const enum bod  bod_id )

inlinestatic

Disables an enabled BOD module.

Disables the specified BOD module that was previously enabled.

Parameters

[in]

bod_id

BOD module to disable

Returns

Error code indicating the status of the disable operation.

Return values

STATUS_OK	If the BOD was successfully disabled
STATUS_ERR_INVALID_ARG	An invalid BOD was supplied

References Assert, BOD_BOD33, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by run_bod_test().

static enum status_code bod_enable ( const enum bod  bod_id )

inlinestatic

Enables a configured BOD module.

Enables the specified BOD module that has been previously configured.

Parameters

[in]

bod_id

BOD module to enable

Returns

Error code indicating the status of the enable operation.

Return values

STATUS_OK	If the BOD was successfully enabled
STATUS_ERR_INVALID_ARG	An invalid BOD was supplied

References Assert, BOD_BOD33, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by configure_bod(), configure_bod33(), and run_bod_init_test().

static void bod_get_config_defaults ( struct bod_config *const  conf )

inlinestatic

Get default BOD configuration.

The default BOD configuration is:

• Clock prescaler set to divide the input clock by two
• Continuous mode
• Reset on BOD detect
• Hysteresis enabled
• BOD level 0x12
• BOD kept enabled during device sleep

Parameters

[out]

conf

BOD configuration struct to set to default settings

References bod_config::action, Assert, BOD_ACTION_RESET, BOD_MODE_CONTINUOUS, BOD_PRESCALE_DIV_2, bod_config::hysteresis, bod_config::level, bod_config::mode, bod_config::prescaler, and bod_config::run_in_standby.

Referenced by configure_bod(), configure_bod33(), and run_bod_init_test().

static bool bod_is_detected ( const enum bod  bod_id )

inlinestatic

Checks if a specified BOD low voltage detection has occurred.

Determines if a specified BOD has detected a voltage lower than its configured threshold.

Parameters

[in]

bod_id

BOD module to check

Returns

Detection status of the specified BOD.

Return values

true	If the BOD has detected a low voltage condition
false	If the BOD has not detected a low voltage condition

References Assert, and BOD_BOD33.

Referenced by run_bod_test().

enum status_code bod_set_config	(	const enum bod	bod_id,
		struct bod_config *const	conf
	)

Configure a Brown Out Detector module.

Configures a given BOD module with the settings stored in the given configuration structure.

Parameters

[in]	bod_id	BOD module to configure
[in]	conf	Configuration settings to use for the specified BOD

Return values

STATUS_OK	Operation completed successfully
STATUS_ERR_INVALID_ARG	An invalid BOD was supplied
STATUS_ERR_INVALID_OPTION	The requested BOD level was outside the acceptable range

References bod_config::action, Assert, BOD_BOD33, BOD_MODE_SAMPLED, bod_config::hysteresis, if(), bod_config::level, bod_config::mode, bod_config::prescaler, bod_config::run_in_standby, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by configure_bod(), configure_bod33(), and run_bod_init_test().