periph_cpu_common.h File Reference

Common CPU specific definitions for all SAMx21 based CPUs. More...

Detailed Description

Common CPU specific definitions for all SAMx21 based CPUs.

Common CPU specific definitions for all SAMx21 based CPUs

Author
Hauke Petersen hauke.nosp@m..pet.nosp@m.ersen.nosp@m.@fu-.nosp@m.berli.nosp@m.n.de
Dylan Laduranty dylan.nosp@m..lad.nosp@m.urant.nosp@m.y@me.nosp@m.sotic.nosp@m..com

Definition in file periph_cpu_common.h.

#include "cpu.h"
#include "exti_config.h"
#include "timer_config.h"
+ Include dependency graph for periph_cpu_common.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  uart_conf_t
 UART device configuration. More...
 
struct  tcc_cfg_t
 Common configuration for timer devices. More...
 
struct  pwm_conf_chan_t
 PWM channel configuration data structure. More...
 
struct  pwm_conf_t
 PWM device configuration. More...
 
struct  spi_conf_t
 SPI configuration structure type. More...
 
struct  i2c_conf_t
 I2C configuration options. More...
 
struct  tc32_conf_t
 Timer device configuration. More...
 
struct  adc_conf_chan_t
 ADC Channel Configuration. More...
 
struct  sam0_common_usb_config_t
 USB peripheral parameters. More...
 

Macros

#define GPIO_UNDEF   (0xffffffff)
 Definition of a fitting UNDEF value.
 
#define TIMER_CHANNEL_NUMOF   (2)
 Number of available timer channels.
 
#define WDT_HAS_STOP   (1)
 Watchdog can be stopped.
 
#define WDT_HAS_INIT   (1)
 Watchdog has to be initialized.
 

Enumerations

enum  i2c_flag_t { I2C_FLAG_NONE = 0x0, I2C_FLAG_RUN_STANDBY = 0x1 }
 Available SERCOM I2C flag selections. More...
 
enum  sam0_supc_t { SAM0_VREG_LDO, SAM0_VREG_BUCK }
 Available voltage regulators on the supply controller.
 

Functions

void gpio_init_mux (gpio_t pin, gpio_mux_t mux)
 Set up alternate function (PMUX setting) for a PORT pin. More...
 
void gpio_pm_cb_enter (int deep)
 Called before the power management enters a power mode. More...
 
void gpio_pm_cb_leave (int deep)
 Called after the power management left a power mode. More...
 
void cpu_pm_cb_enter (int deep)
 Called before the power management enters a power mode. More...
 
void cpu_pm_cb_leave (int deep)
 Called after the power management left a power mode. More...
 
static void sam0_cortexm_sleep (int deep)
 Wrapper for cortexm_sleep calling power management callbacks. More...
 
void gpio_disable_mux (gpio_t pin)
 Disable alternate function (PMUX setting) for a PORT pin. More...
 
static void sam0_set_voltage_regulator (sam0_supc_t src)
 Switch the internal voltage regulator used for generating the internal MCU voltages. More...
 
uint32_t sam0_gclk_freq (uint8_t id)
 Returns the frequency of a GCLK provider. More...
 
void sam0_gclk_enable (uint8_t id)
 Enables an on-demand GCLK that has been configured in cpu.c. More...
 
static uint8_t sercom_id (const void *sercom)
 Return the numeric id of a SERCOM device derived from its address. More...
 
static void sercom_clk_en (void *sercom)
 Enable peripheral clock for given SERCOM device. More...
 
static void sercom_clk_dis (void *sercom)
 Disable peripheral clock for given SERCOM device. More...
 
static void sercom_set_gen (void *sercom, uint8_t gclk)
 Configure generator clock for given SERCOM device. More...
 
static bool cpu_woke_from_backup (void)
 Returns true if the CPU woke deep sleep (backup/standby)
 
#define CPUID_LEN   (16U)
 Length of the CPU_ID in octets.
 
#define PERIPH_SPI_NEEDS_INIT_CS
 Use shared SPI functions.
 
#define PERIPH_SPI_NEEDS_TRANSFER_BYTE
 
#define PERIPH_SPI_NEEDS_TRANSFER_REG
 
#define PERIPH_SPI_NEEDS_TRANSFER_REGS
 
#define HAVE_GPIO_T
 Override GPIO type.
 
typedef uint32_t gpio_t
 
#define GPIO_PIN(x, y)   (((gpio_t)(&PORT->Group[x])) | y)
 Macro for accessing GPIO pins.
 
#define GPIO_MODE(pr, ie, pe)   (pr | (ie << 1) | (pe << 2))
 Generate GPIO mode bitfields. More...
 
#define UART_TXBUF_SIZE   (64)
 Size of the UART TX buffer for non-blocking mode.
 
#define TCC_CONFIG(tim)
 Static initializer for timer configuration. More...
 
enum  { PA = 0, PB = 1, PC = 2, PD = 3 }
 Available ports on the SAMD21 & SAML21. More...
 
enum  gpio_mux_t {
  GPIO_MUX_A = 0x0, GPIO_MUX_B = 0x1, GPIO_MUX_C = 0x2, GPIO_MUX_D = 0x3,
  GPIO_MUX_E = 0x4, GPIO_MUX_F = 0x5, GPIO_MUX_G = 0x6, GPIO_MUX_H = 0x7,
  GPIO_MUX_A = 0, GPIO_MUX_B = 1
}
 Available MUX values for configuring a pin's alternate function. More...
 
enum  uart_rxpad_t { UART_PAD_RX_0 = 0x0, UART_PAD_RX_1 = 0x1, UART_PAD_RX_2 = 0x2, UART_PAD_RX_3 = 0x3 }
 Available values for SERCOM UART RX pad selection. More...
 
enum  uart_txpad_t { UART_PAD_TX_0 = 0x0, UART_PAD_TX_2 = 0x1, UART_PAD_TX_0_RTS_2_CTS_3 = 0x2 }
 Available values for SERCOM UART TX pad selection. More...
 
enum  uart_flag_t {
  UART_FLAG_NONE = 0x0, UART_FLAG_RUN_STANDBY = 0x1, UART_FLAG_WAKEUP = 0x2, UART_FLAG_RXINV = 0x4,
  UART_FLAG_TXINV = 0x8
}
 Available SERCOM UART flag selections. More...
 
enum  spi_misopad_t { SPI_PAD_MISO_0 = 0x0, SPI_PAD_MISO_1 = 0x1, SPI_PAD_MISO_2 = 0x2, SPI_PAD_MISO_3 = 0x3 }
 Available values for SERCOM SPI MISO pad selection. More...
 
enum  spi_mosipad_t { SPI_PAD_MOSI_0_SCK_1 = 0x0, SPI_PAD_MOSI_2_SCK_3 = 0x1, SPI_PAD_MOSI_3_SCK_1 = 0x2, SPI_PAD_MOSI_0_SCK_3 = 0x3 }
 Available values for SERCOM SPI MOSI and SCK pad selection. More...
 

WDT upper and lower bound times in ms

#define NWDT_TIME_LOWER_LIMIT   (8U)
 
#define NWDT_TIME_UPPER_LIMIT   (16384U)
 

sam0 DMA peripheral

The sam0 DMA peripheral has a number of channels.

Each channel is a separate data stream, triggered by a configurable trigger when enabled, or triggered by software (not yet supported). In theory each DMA channel is equal and can have a configurable priority and can be triggered by the full set of triggers available.

DMA descriptors, specifying a single transfer with size, source and destination, are kept in RAM and are read when the channel is enabled and triggered. On the SAML21 platform, these descriptors must reside in the LP SRAM.

The DMA addresses supplied must point to the end of the array to be transferred. When address increment is enabled this means that the supplied src or dst argument must point to array + length. When increment is disabled, the source or destination address can be used directly. The calculation of the end of the array must be done by the calling function, because the beatsize and the increment can usually be hardcoded there and doesn't have to be retrieved from the DMA register configuration. See also section 20.6.2.7 of the SAM D21/DA1 Family Data Sheet.

Example:

void transfer_data(void *src, void *dst, size_t len)
{
if (channel == 0xff) {
return -E_BUSY;
}
dma_setup(channel, DMA_TRIGGER_MY_PERIH, 0, true);
dma_prepare(channel, DMAC_BTCTRL_BEATSIZE_BYTE_Val,
(uint8_t*)src + len, (uint8_t*)dst + len, len);
dma_start(channel);
dma_wait(channel);
}
#define DMA_TRIGGER_DISABLED   0
 Indicates that the peripheral doesn't utilize the DMA controller. More...
 
#define DMA_DESCRIPTOR_IN_LPSRAM
 Move the DMA descriptors to the LP SRAM. More...
 
#define DMA_DESCRIPTOR_ATTRS   __attribute__((section(".backup.bss")))
 Extra attributes required for instantiating DMA descriptors.
 
enum  dma_incr_t { DMA_INCR_NONE = 0, DMA_INCR_SRC = 1, DMA_INCR_DEST = 2, DMA_INCR_BOTH = 3 }
 Available DMA address increment modes. More...
 
typedef unsigned dma_t
 DMA channel type.
 
void dma_init (void)
 Initialize DMA.
 
dma_t dma_acquire_channel (void)
 Acquire a DMA channel. More...
 
void dma_release_channel (dma_t dma)
 Release a previously acquired DMA channel. More...
 
void dma_setup (dma_t dma, unsigned trigger, uint8_t prio, bool irq)
 Initialize a previously allocated DMA channel with one-time settings. More...
 
void dma_prepare (dma_t dma, uint8_t width, const void *src, void *dst, size_t num, dma_incr_t incr)
 Prepare the DMA channel for an individual transfer. More...
 
void dma_prepare_src (dma_t dma, const void *src, size_t num, bool incr)
 Prepare a transfer without modifying the destination address settings. More...
 
void dma_prepare_dst (dma_t dma, void *dst, size_t num, bool incr)
 Prepare a transfer without modifying the source address settings. More...
 
void dma_append (dma_t dma, DmacDescriptor *descriptor, uint8_t width, const void *src, void *dst, size_t num, dma_incr_t incr)
 Append a second transfer descriptor after the default channel descriptor. More...
 
void dma_append_src (dma_t dma, DmacDescriptor *next, const void *src, size_t num, bool incr)
 Append a second transfer descriptor after the default channel descriptor, copying destination and block size from the initial descriptor. More...
 
void dma_append_dst (dma_t dma, DmacDescriptor *next, void *dst, size_t num, bool incr)
 Append a second transfer descriptor after the default channel descriptor, copying source and block size from the initial descriptor. More...
 
void dma_start (dma_t dma)
 Start a DMA transfer. More...
 
void dma_wait (dma_t dma)
 Wait for a DMA channel to finish the transfer. More...
 
void dma_cancel (dma_t dma)
 Cancel an active DMA transfer. More...
 

Macro Definition Documentation

◆ DMA_DESCRIPTOR_IN_LPSRAM

#define DMA_DESCRIPTOR_IN_LPSRAM

Move the DMA descriptors to the LP SRAM.

Required on the SAML21

Definition at line 825 of file periph_cpu_common.h.

◆ DMA_TRIGGER_DISABLED

#define DMA_TRIGGER_DISABLED   0

Indicates that the peripheral doesn't utilize the DMA controller.

Matches with the register configuration for software based triggers.

Definition at line 819 of file periph_cpu_common.h.

◆ GPIO_MODE

#define GPIO_MODE (   pr,
  ie,
  pe 
)    (pr | (ie << 1) | (pe << 2))

Generate GPIO mode bitfields.

We use 3 bit to determine the pin functions:

  • bit 0: PD(0) or PU(1)
  • bit 1: input enable
  • bit 2: pull enable

Definition at line 100 of file periph_cpu_common.h.

◆ TCC_CONFIG

#define TCC_CONFIG (   tim)
Value:
{ \
.dev = tim, \
.pm_mask = PM_APBCMASK_ ## tim, \
.gclk_id = tim ## _GCLK_ID, }

Static initializer for timer configuration.

Definition at line 265 of file periph_cpu_common.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Available ports on the SAMD21 & SAML21.

Enumerator
PA 

port A

PB 

port B

PC 

port C

PD 

port D

Definition at line 85 of file periph_cpu_common.h.

◆ dma_incr_t

enum dma_incr_t

Available DMA address increment modes.

Enumerator
DMA_INCR_NONE 

Don't increment any addresses after a beat.

DMA_INCR_SRC 

Increment the source address after a beat.

DMA_INCR_DEST 

Increment destination address after a beat.

DMA_INCR_BOTH 

Increment both addresses after a beat.

Definition at line 845 of file periph_cpu_common.h.

◆ gpio_mux_t

enum gpio_mux_t

Available MUX values for configuring a pin's alternate function.

Enumerator
GPIO_MUX_A 

select peripheral function A

GPIO_MUX_B 

select peripheral function B

GPIO_MUX_C 

select peripheral function C

GPIO_MUX_D 

select peripheral function D

GPIO_MUX_E 

select peripheral function E

GPIO_MUX_F 

select peripheral function F

GPIO_MUX_G 

select peripheral function G

GPIO_MUX_H 

select peripheral function H

GPIO_MUX_A 

alternate function A

GPIO_MUX_B 

alternate function B

Definition at line 133 of file periph_cpu_common.h.

◆ i2c_flag_t

enum i2c_flag_t

Available SERCOM I2C flag selections.

Enumerator
I2C_FLAG_NONE 

No flags set.

I2C_FLAG_RUN_STANDBY 

run SERCOM in standby mode

Definition at line 373 of file periph_cpu_common.h.

◆ spi_misopad_t

Available values for SERCOM SPI MISO pad selection.

Enumerator
SPI_PAD_MISO_0 

use pad 0 for MISO line

SPI_PAD_MISO_1 

use pad 0 for MISO line

SPI_PAD_MISO_2 

use pad 0 for MISO line

SPI_PAD_MISO_3 

use pad 0 for MISO line

Definition at line 293 of file periph_cpu_common.h.

◆ spi_mosipad_t

Available values for SERCOM SPI MOSI and SCK pad selection.

Enumerator
SPI_PAD_MOSI_0_SCK_1 

use pad 0 for MOSI, pad 1 for SCK

SPI_PAD_MOSI_2_SCK_3 

use pad 2 for MOSI, pad 3 for SCK

SPI_PAD_MOSI_3_SCK_1 

use pad 3 for MOSI, pad 1 for SCK

SPI_PAD_MOSI_0_SCK_3 

use pad 0 for MOSI, pad 3 for SCK

Definition at line 303 of file periph_cpu_common.h.

◆ uart_flag_t

Available SERCOM UART flag selections.

Enumerator
UART_FLAG_NONE 

No flags set.

UART_FLAG_RUN_STANDBY 

run SERCOM in standby mode

UART_FLAG_WAKEUP 

wake from sleep on receive

UART_FLAG_RXINV 

invert RX signal

UART_FLAG_TXINV 

invert TX signal

Definition at line 168 of file periph_cpu_common.h.

◆ uart_rxpad_t

Available values for SERCOM UART RX pad selection.

Enumerator
UART_PAD_RX_0 

use pad 0 for RX line

UART_PAD_RX_1 

select pad 1

UART_PAD_RX_2 

select pad 2

UART_PAD_RX_3 

select pad 3

Definition at line 148 of file periph_cpu_common.h.

◆ uart_txpad_t

Available values for SERCOM UART TX pad selection.

Enumerator
UART_PAD_TX_0 

select pad 0

UART_PAD_TX_2 

select pad 2

UART_PAD_TX_0_RTS_2_CTS_3 

TX is pad 0, on top RTS on pad 2 and CTS on pad 3.

Definition at line 158 of file periph_cpu_common.h.

Function Documentation

◆ cpu_pm_cb_enter()

void cpu_pm_cb_enter ( int  deep)

Called before the power management enters a power mode.

Parameters
[in]deep

◆ cpu_pm_cb_leave()

void cpu_pm_cb_leave ( int  deep)

Called after the power management left a power mode.

Parameters
[in]deep

◆ dma_acquire_channel()

dma_t dma_acquire_channel ( void  )

Acquire a DMA channel.

A free DMA channel is marked as allocated and a reference is returned. DMA channels can be acquired for long periods of time, e.g. from the start to end of a number of transfers or directly at boot and never released.

Returns
A reference to the DMA channel
UINT8_MAX when no DMA channel is available

◆ dma_append()

void dma_append ( dma_t  dma,
DmacDescriptor *  descriptor,
uint8_t  width,
const void *  src,
void *  dst,
size_t  num,
dma_incr_t  incr 
)

Append a second transfer descriptor after the default channel descriptor.

Note
Only a single extra transfer descriptor is supported for now.
next must remain valid throughout the full transfer duration
When increment is enabled for source or destination, src and/or dst must point to the end of the array.
Parameters
dmaDMA channel reference to add the descriptor to
descriptorExtra transfer descriptor to append
widthTransfer beat size to use
srcSource address for the transfer
dstDestination address for the transfer
numNumber of beats to transfer
incrWhich of the addresses to increment after a beat

◆ dma_append_dst()

void dma_append_dst ( dma_t  dma,
DmacDescriptor *  next,
void *  dst,
size_t  num,
bool  incr 
)

Append a second transfer descriptor after the default channel descriptor, copying source and block size from the initial descriptor.

Note
Only a single extra transfer descriptor is supported for now.
next must remain valid throughout the full transfer duration
When increment is enabled for destination, dst must point to the end of the array.
Parameters
dmaDMA channel reference to add the descriptor to
nextExtra transfer descriptor to append
dstDestination address for the transfer
numNumber of beats to transfer
incrWhether to increment the source address after a beat

◆ dma_append_src()

void dma_append_src ( dma_t  dma,
DmacDescriptor *  next,
const void *  src,
size_t  num,
bool  incr 
)

Append a second transfer descriptor after the default channel descriptor, copying destination and block size from the initial descriptor.

Note
Only a single extra transfer descriptor is supported for now.
next must remain valid throughout the full transfer duration
When increment is enabled for source, src must point to the end of the array.
Parameters
dmaDMA channel reference to add the descriptor to
nextExtra transfer descriptor to append
srcSource address for the transfer
numNumber of beats to transfer
incrWhether to increment the source address after a beat

◆ dma_cancel()

void dma_cancel ( dma_t  dma)

Cancel an active DMA transfer.

It is not harmful to call this on an inactive channel, but it will waste some processing time

Parameters
dmaDMA channel reference

◆ dma_prepare()

void dma_prepare ( dma_t  dma,
uint8_t  width,
const void *  src,
void *  dst,
size_t  num,
dma_incr_t  incr 
)

Prepare the DMA channel for an individual transfer.

Note
When increment is enabled for source or destination, the src and/or dst must point to the end of the array.
Parameters
dmaDMA channel reference
widthTransfer beat size to use
srcSource address for the transfer
dstDestination address for the transfer
numNumber of beats to transfer
incrWhich of the addresses to increment after a beat

◆ dma_prepare_dst()

void dma_prepare_dst ( dma_t  dma,
void *  dst,
size_t  num,
bool  incr 
)

Prepare a transfer without modifying the source address settings.

Can be used when repeatedly using a dma channel to transfer from the same peripheral address, leaving the source address and related settings untouched

Note
This only touches the destination address, the number of transfers and destination increment settings. Be sure to initialize the full descriptor beforehand with dma_prepare
When increment is enabled for destination, dst must point to the end of the array.
Parameters
dmaDMA channel reference
dstDestination address for the transfer
numNumber of beats to transfer
incrWhether to increment the destination address after a beat

◆ dma_prepare_src()

void dma_prepare_src ( dma_t  dma,
const void *  src,
size_t  num,
bool  incr 
)

Prepare a transfer without modifying the destination address settings.

Can be used when repeatedly using a dma channel to transfer to the same peripheral address, leaving the destination address and related settings untouched

Note
This only touches the source address, number of transfers and source increment settings. Be sure to initialize the full descriptor beforehand with dma_prepare
When increment is enabled for source, the src must point to the end of the array.
Parameters
dmaDMA channel reference
srcSource address for the transfer
numNumber of beats to transfer
incrWhether to increment the source address after a beat

◆ dma_release_channel()

void dma_release_channel ( dma_t  dma)

Release a previously acquired DMA channel.

Parameters
dmaDMA channel to release

◆ dma_setup()

void dma_setup ( dma_t  dma,
unsigned  trigger,
uint8_t  prio,
bool  irq 
)

Initialize a previously allocated DMA channel with one-time settings.

Parameters
dmaDMA channel reference
triggerTrigger to use for this DMA channel
prioChannel priority
irqWhether to enable the interrupt handler for this channel

◆ dma_start()

void dma_start ( dma_t  dma)

Start a DMA transfer.

Parameters
dmaDMA channel reference

◆ dma_wait()

void dma_wait ( dma_t  dma)

Wait for a DMA channel to finish the transfer.

This function uses a blocking mutex to wait for the transfer to finish

Note
Use only with DMA channels of which the interrupt is enabled
Parameters
dmaDMA channel reference

◆ gpio_disable_mux()

void gpio_disable_mux ( gpio_t  pin)

Disable alternate function (PMUX setting) for a PORT pin.

Parameters
[in]pinPin to reset the multiplexing for

◆ gpio_init_mux()

void gpio_init_mux ( gpio_t  pin,
gpio_mux_t  mux 
)

Set up alternate function (PMUX setting) for a PORT pin.

Parameters
[in]pinPin to set the multiplexing for
[in]muxMux value

◆ gpio_pm_cb_enter()

void gpio_pm_cb_enter ( int  deep)

Called before the power management enters a power mode.

Parameters
[in]deep

◆ gpio_pm_cb_leave()

void gpio_pm_cb_leave ( int  deep)

Called after the power management left a power mode.

Parameters
[in]deep

◆ sam0_cortexm_sleep()

static void sam0_cortexm_sleep ( int  deep)
inlinestatic

Wrapper for cortexm_sleep calling power management callbacks.

Parameters
[in]deep

Definition at line 489 of file periph_cpu_common.h.

◆ sam0_gclk_enable()

void sam0_gclk_enable ( uint8_t  id)

Enables an on-demand GCLK that has been configured in cpu.c.

Parameters
[in]idThe ID of the GCLK

◆ sam0_gclk_freq()

uint32_t sam0_gclk_freq ( uint8_t  id)

Returns the frequency of a GCLK provider.

Parameters
[in]idThe ID of the GCLK
Returns
The frequency of the GCLK with the given ID.

◆ sam0_set_voltage_regulator()

static void sam0_set_voltage_regulator ( sam0_supc_t  src)
inlinestatic

Switch the internal voltage regulator used for generating the internal MCU voltages.

Available options are:

  • LDO: not very efficient, but will always work
  • BUCK converter: Most efficient, but incompatible with the use of DFLL or DPLL. Please refer to the errata sheet, further restrictions may apply depending on the MCU.
Parameters
[in]src

Definition at line 535 of file periph_cpu_common.h.

◆ sercom_clk_dis()

static void sercom_clk_dis ( void *  sercom)
inlinestatic

Disable peripheral clock for given SERCOM device.

Parameters
[in]sercomSERCOM device

Definition at line 653 of file periph_cpu_common.h.

◆ sercom_clk_en()

static void sercom_clk_en ( void *  sercom)
inlinestatic

Enable peripheral clock for given SERCOM device.

Parameters
[in]sercomSERCOM device

Definition at line 623 of file periph_cpu_common.h.

◆ sercom_id()

static uint8_t sercom_id ( const void *  sercom)
inlinestatic

Return the numeric id of a SERCOM device derived from its address.

Parameters
[in]sercomSERCOM device
Returns
numeric id of the given SERCOM device

Definition at line 569 of file periph_cpu_common.h.

◆ sercom_set_gen()

static void sercom_set_gen ( void *  sercom,
uint8_t  gclk 
)
inlinestatic

Configure generator clock for given SERCOM device.

Parameters
[in]sercomSERCOM device
[in]gclkGenerator clock

Definition at line 695 of file periph_cpu_common.h.