This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's system relation functionality, necessary for the basic device operation.
This is not limited to a single peripheral, but extends across multiple hardware peripherals.
The following peripherals are used by this module:
The following devices can use this module:
The outline of this documentation is as follows:
There are no prerequisites for this module.
The System driver provides a collection of interfaces between the user application logic, and the core device functionality (such as clocks, reset cause determination, etc.) that is required for all applications. It contains a number of sub-modules that control one specific aspect of the device:
The various analog modules within the SAM devices (such as AC, ADC, and DAC) require a voltage reference to be configured to act as a reference point for comparisons and conversions.
The SAM devices contain multiple references, including an internal temperature sensor and a fixed band-gap voltage source. When enabled, the associated voltage reference can be selected within the desired peripheral where applicable.
In some applications there may be a need to execute a different program flow based on how the device was reset. For example, if the cause of reset was the Watchdog timer (WDT), this might indicate an error in the application, and a form of error handling or error logging might be needed.
For this reason, an API is provided to retrieve the cause of the last system reset, so that appropriate action can be taken.
The SAM devices have several sleep modes. The sleep mode controls which clock systems on the device will remain enabled or disabled when the device enters a low power sleep mode. The table below lists the clock settings of the different sleep modes.
Sleep mode | CPU clock | AHB clock | APB clocks | Clock sources | System clock | 32KHz | Reg mode | RAM mode |
---|---|---|---|---|---|---|---|---|
Idle 0 | Stop | Run | Run | Run | Run | Run | Normal | Normal |
Idle 1 | Stop | Stop | Run | Run | Run | Run | Normal | Normal |
Idle 2 | Stop | Stop | Stop | Run | Run | Run | Normal | Normal |
Standby | Stop | Stop | Stop | Stop | Stop | Stop | Low Power | Source/Drain biasing |
Before entering device sleep, one of the available sleep modes must be set. The device will automatically wake up in response to an interrupt being generated or upon any other sleep mode exit condition.
Some peripheral clocks will remain enabled during sleep, depending on their configuration. If desired, the modules can remain clocked during sleep to allow them continue to operate while other parts of the system are powered down to save power.
Most of the functions in this driver have device specific restrictions and caveats; refer to your device datasheet.
For extra information, see Extra Information for SYSTEM Driver. This includes:
For SYSTEM module related examples, refer to the sub-modules listed in the Module Overview.
Data Structures | |
struct | system_battery_backup_power_switch_config |
Battery Backup Power Switch (BBPS) Control configuration. More... | |
struct | system_standby_config |
Standby configuration. More... | |
struct | system_voltage_references_config |
Voltage References System (VREF) Control configuration. More... | |
struct | system_voltage_regulator_config |
Voltage Regulator System (VREG) Control configuration. More... | |
System Debugger | |
static bool | system_is_debugger_present (void) |
Check if debugger is present. More... | |
System Identification | |
static uint32_t | system_get_device_id (void) |
Retrieve the device identification signature. More... | |
System Initialization | |
void | system_init (void) |
Initialize system. More... | |
Voltage Regulator | |
static void | system_voltage_regulator_get_config_defaults (struct system_voltage_regulator_config *const config) |
Retrieve the default configuration for voltage regulator. More... | |
static void | system_voltage_regulator_set_config (struct system_voltage_regulator_config *const config) |
Configure voltage regulator. More... | |
static void | system_voltage_regulator_enable (void) |
Enable the selected voltage regulator. More... | |
static void | system_voltage_regulator_disable (void) |
Disable the selected voltage regulator. More... | |
Voltage References | |
static void | system_voltage_reference_get_config_defaults (struct system_voltage_references_config *const config) |
Retrieve the default configuration for voltage reference. More... | |
static void | system_voltage_reference_set_config (struct system_voltage_references_config *const config) |
Configure voltage reference. More... | |
static void | system_voltage_reference_enable (const enum system_voltage_reference vref) |
Enable the selected voltage reference. More... | |
static void | system_voltage_reference_disable (const enum system_voltage_reference vref) |
Disable the selected voltage reference. More... | |
Battery Backup Power Switch | |
static void | system_battery_backup_power_switch_get_config_defaults (struct system_battery_backup_power_switch_config *const config) |
Retrieve the default configuration for battery backup power switch control. More... | |
static void | system_battery_backup_power_switch_set_config (struct system_battery_backup_power_switch_config *const config) |
Configure battery backup power switch. More... | |
Output Pins in Backup Mode | |
static void | system_backup_pin_output_enable (enum system_backup_pin pin) |
Enable the backup pin output. More... | |
static void | system_backup_pin_output_disable (enum system_backup_pin pin) |
Disable the backup pin output. More... | |
static bool | system_backup_pin_output_is_enabled (enum system_backup_pin pin) |
Check if backup pin output is enabled. More... | |
static void | system_backup_pin_output_enable_rtc_toggle (enum system_backup_pin pin) |
Enable the backup pin toggle on RTC event. More... | |
static void | system_backup_pin_output_disable_rtc_toggle (enum system_backup_pin pin) |
Disable the backup pin toggle on RTC event. More... | |
static void | system_backup_pin_output_set (enum system_backup_pin pin) |
Set the backup pin. More... | |
static void | system_backup_pin_output_clear (enum system_backup_pin pin) |
Clear the backup pin. More... | |
static bool | system_backup_pin_output_get (enum system_backup_pin pin) |
Get the backup I/O input values. More... | |
Device Sleep Control | |
static void | system_set_sleepmode (const enum system_sleepmode sleep_mode) |
Set the sleep mode of the device. More... | |
static void | system_sleep (void) |
Put the system to sleep waiting for interrupt. More... | |
Performance Level Control | |
static enum status_code | system_switch_performance_level (const enum system_performance_level performance_level) |
Switch performance level. More... | |
static enum system_performance_level | system_get_performance_level (void) |
Get performance level. More... | |
static uint8_t | system_get_performance_level_status (void) |
Get performance level status. More... | |
static void | system_clear_performance_level_status (void) |
Clear performance level status. More... | |
Standby Configuration | |
static void | system_standby_get_config_defaults (struct system_standby_config *const config) |
Retrieve the default configuration for standby. More... | |
static void | system_standby_set_config (struct system_standby_config *const config) |
Configure standby mode. More... | |
I/O Retention | |
static void | system_io_retension_enable (void) |
Enable I/O retention. More... | |
static void | system_io_retension_disable (void) |
Disable I/O retention. More... | |
Reset Control | |
static void | system_reset (void) |
Reset the MCU. More... | |
static enum system_reset_cause | system_get_reset_cause (void) |
Get the reset cause. More... | |
Backup Exit Control | |
static enum system_reset_backup_exit_source | system_get_backup_exit_source (void) |
Get the backup exit source. More... | |
enum system_backup_pin |
Backup IO enum.
List of Backup input and output pins. If enabled (system_backup_pin_output_enable), the pins can be driven by the SUPC.
Enumerator | |
---|---|
SYSTEM_BACKUP_PIN_PSOK |
Power Supply OK status pin. |
SYSTEM_BACKUP_PIN_OUT_0 |
Backup output pin 0. |
SYSTEM_BACKUP_PIN_OUT_1 |
Backup output pin 1. |
Battery power switch configuration enum.
Enum for Battery power switch modes.
RAM Back-biasing mode.
List of RAM back bias modes. By default, in standby sleep mode, RAM is in low power mode (back biased) if its power domain is in retention state. This behavior can be changed by configuring the Back Bias bit groups in STDBYCFG(STDBYCFG.BBIASxx).
enum system_reset_cause |
Reset causes of the system.
List of possible reset causes of the system.
enum system_sleepmode |
Device sleep modes.
List of available sleep modes in the device. A table of clocks available in different sleep modes can be found in Sleep Modes.
Enumerator | |
---|---|
SYSTEM_SLEEPMODE_IDLE |
IDLE sleep mode. |
SYSTEM_SLEEPMODE_STANDBY |
STANDBY sleep mode. |
SYSTEM_SLEEPMODE_BACKUP |
BACKUP sleep mode. |
SYSTEM_SLEEPMODE_OFF |
OFF sleep mode. |
Voltage reference value.
Voltage references selection.
Low power efficiency.
Low power mode efficiency.
Voltage regulator.
Voltage regulators selection. In active mode, the voltage regulator can be chosen on the fly between a LDO or a Buck converter.
Enumerator | |
---|---|
SYSTEM_VOLTAGE_REGULATOR_LDO |
The voltage regulator in active mode is a LDO voltage regulator. |
SYSTEM_VOLTAGE_REGULATOR_BUCK |
The voltage regulator in active mode is a buck converter. |
|
inlinestatic |
Clear the backup pin.
Clear the corresponding output.
[in] | pin | Backup pin index |
References Assert, and SYSTEM_BACKUP_PIN_PSOK.
|
inlinestatic |
Disable the backup pin output.
The output is not enabled.
[in] | pin | Backup pin index |
References SYSTEM_BACKUP_PIN_PSOK.
|
inlinestatic |
Disable the backup pin toggle on RTC event.
Toggle output on RTC event is disabled.
[in] | pin | Backup pin index |
References Assert, and SYSTEM_BACKUP_PIN_PSOK.
|
inlinestatic |
Enable the backup pin output.
The output is enabled and driven by the SUPC.
[in] | pin | Backup pin index |
References SYSTEM_BACKUP_PIN_PSOK.
|
inlinestatic |
Enable the backup pin toggle on RTC event.
Toggle output on RTC event is enabled.
[in] | pin | Backup pin index |
References Assert, and SYSTEM_BACKUP_PIN_PSOK.
|
inlinestatic |
Get the backup I/O input values.
Get the backup I/O data input values. If the corresponding pin is enabled, the I/O input value is given on the pin.
[in] | pin | Backup pin index |
References Assert, and SYSTEM_BACKUP_PIN_PSOK.
|
inlinestatic |
Check if backup pin output is enabled.
[in] | pin | Backup pin index |
true | The output is enabled |
false | The output is not enabled |
References SYSTEM_BACKUP_PIN_PSOK.
|
inlinestatic |
Set the backup pin.
Set the corresponding output pin.
[in] | pin | Backup pin index |
References Assert, and SYSTEM_BACKUP_PIN_PSOK.
|
inlinestatic |
Retrieve the default configuration for battery backup power switch control.
Fills a configuration structure with the default configuration:
[out] | config | Configuration structure to fill with default values |
References Assert, system_battery_backup_power_switch_config::battery_power_switch, SYSTEM_BATTERY_POWER_SWITCH_NONE, and system_battery_backup_power_switch_config::wake_enabled.
|
inlinestatic |
Configure battery backup power switch.
Configures battery backup power switch with the given configuration.
[in] | config | Battery backup power switch configuration structure containing the new config |
References Assert, system_battery_backup_power_switch_config::battery_power_switch, SYSTEM_BATTERY_POWER_SWITCH_AUTOMATIC, and system_battery_backup_power_switch_config::wake_enabled.
|
inlinestatic |
Clear performance level status.
Clear performance level status.
|
inlinestatic |
Get the backup exit source.
Get the backup exit source when a backup reset occurs.
|
inlinestatic |
Retrieve the device identification signature.
Retrieves the signature of the current device.
|
inlinestatic |
Get performance level.
Get performance level.
|
inlinestatic |
Get performance level status.
Get performance level status.
|
inlinestatic |
Get the reset cause.
Retrieves the cause of the last system reset.
void system_init | ( | void | ) |
Initialize system.
This function will call the various initialization functions within the system namespace. If a given optional system module is not available, the associated call will effectively be a NOP (No Operation).
Currently the following initialization functions are supported:
References system_board_init(), and system_clock_init().
Referenced by main().
|
inlinestatic |
Disable I/O retention.
Disable IO retention. After waking up from Backup mode, I/O lines are not held.
|
inlinestatic |
Enable I/O retention.
Enable I/O retention. After waking up from Backup mode, I/O lines are held until the bit is written to 0.
|
inlinestatic |
Check if debugger is present.
Check if debugger is connected to the onboard debug system (DAP).
true | Debugger is connected to the system |
false | Debugger is not connected to the system |
|
inlinestatic |
Reset the MCU.
Resets the MCU and all associated peripherals and registers, except RTC, OSC32KCTRL, RSTC, GCLK (if WRTLOCK is set), and I/O retention state of PM.
|
inlinestatic |
Set the sleep mode of the device.
Sets the sleep mode of the device; the configured sleep mode will be entered upon the next call of the system_sleep() function.
For an overview of which systems are disabled in sleep for the different sleep modes, see Sleep Modes.
[in] | sleep_mode | Sleep mode to configure for the next sleep operation |
|
inlinestatic |
Put the system to sleep waiting for interrupt.
Executes a device DSB (Data Synchronization Barrier) instruction to ensure all ongoing memory accesses have completed. Further, a WFI (Wait For Interrupt) instruction is executed to place the device into the sleep mode specified by system_set_sleepmode.
|
inlinestatic |
Retrieve the default configuration for standby.
Fills a configuration structure with the default configuration for standby:
[out] | config | Configuration structure to fill with default values |
References Assert, system_standby_config::hmcramchs_back_bias, system_standby_config::hmcramclp_back_bias, and SYSTEM_RAM_BACK_BIAS_RETENTION.
|
inlinestatic |
Configure standby mode.
Configures standby with the given configuration.
[in] | config | Standby configuration structure containing the new config |
References Assert, system_standby_config::hmcramchs_back_bias, and system_standby_config::hmcramclp_back_bias.
|
inlinestatic |
Switch performance level.
The bus frequency must be reduced prior to scaling down the performance level, in order to not exceed the maximum frequency allowed for the performance level.
When scaling up the performance level (for example from PL0 to PL2), the bus frequency can be increased first when the performance level transition is completed. Check the performance level status before increasing the frequency.
[in] | performance_level | Performance level to switch |
STATUS_ERR_INVALID_ARG | Invalid parameter |
STATUS_OK | Successfully |
References STATUS_ERR_INVALID_ARG, and STATUS_OK.
Referenced by system_clock_init().
|
inlinestatic |
Disable the selected voltage reference.
Disables the selected voltage reference source.
[in] | vref | Voltage reference to disable |
References Assert, SYSTEM_VOLTAGE_REFERENCE_OUTPUT, and SYSTEM_VOLTAGE_REFERENCE_TEMPSENSE.
|
inlinestatic |
Enable the selected voltage reference.
Enables the selected voltage reference source, making the voltage reference available on a pin as well as an input source to the analog peripherals.
[in] | vref | Voltage reference to enable |
References Assert, SYSTEM_VOLTAGE_REFERENCE_OUTPUT, and SYSTEM_VOLTAGE_REFERENCE_TEMPSENSE.
|
inlinestatic |
Retrieve the default configuration for voltage reference.
Fill a configuration structure with the default configuration:
[out] | config | Configuration structure to fill with default values |
References Assert, system_voltage_references_config::on_demand, system_voltage_references_config::run_in_standby, system_voltage_references_config::sel, and SYSTEM_VOLTAGE_REFERENCE_1V0.
|
inlinestatic |
Configure voltage reference.
Configures voltage reference with the given configuration.
[in] | config | Voltage reference configuration structure containing the new config |
References Assert, system_voltage_references_config::on_demand, system_voltage_references_config::run_in_standby, and system_voltage_references_config::sel.
|
inlinestatic |
Disable the selected voltage regulator.
Disables the selected voltage regulator.
|
inlinestatic |
Enable the selected voltage regulator.
Enables the selected voltage regulator source.
|
inlinestatic |
Retrieve the default configuration for voltage regulator.
Fills a configuration structure with the default configuration:
[out] | config | Configuration structure to fill with default values |
References Assert, system_voltage_regulator_config::low_power_efficiency, system_voltage_regulator_config::regulator_sel, system_voltage_regulator_config::run_in_standby, SYSTEM_VOLTAGE_REGULATOR_LDO, SYSTEM_VOLTAGE_REGULATOR_LOW_POWER_EFFICIENCY_DEFAULT, system_voltage_regulator_config::voltage_scale_period, and system_voltage_regulator_config::voltage_scale_step.
|
inlinestatic |
Configure voltage regulator.
Configures voltage regulator with the given configuration.
[in] | config | Voltage regulator configuration structure containing the new config |
References Assert, system_voltage_regulator_config::low_power_efficiency, system_voltage_regulator_config::regulator_sel, system_voltage_regulator_config::run_in_standby, system_voltage_regulator_config::voltage_scale_period, and system_voltage_regulator_config::voltage_scale_step.