Peripheral Driver Interface

Low-level peripheral driver interface for vendor and platform independent access to MCU peripherals as UART, SPI, etc. More...

Detailed Description

Low-level peripheral driver interface for vendor and platform independent access to MCU peripherals as UART, SPI, etc.

The module contains the low-level peripheral driver interface. This interface defines a standardized interface to access MCU peripherals that is not tied to any specific vendor, platform or architecture.

Initialization and Thread Safety

Peripheral drivers fall into three categories regarding to their initialization:

1. Drivers that do not need to be initialized (e.g. EEPROM driver)
2. Drivers that are automatically initialized by the module periph_init at boot, (see Common peripheral initialization for details)
3. Drivers that require manual initialization (e.g. UART or ADC)

The initialization code of drivers initialized at boot up is not thread safe. This code is run sequentially anyway and never called by the user, so the overhead of thread safety would not be justified.

All other peripheral APIs (including the initialization functions of drivers that are not initialized with periph_init) are fully or partially thread safe. Partially thread safe drivers require the user to make sure that the same peripheral entity (e.g. one UART device) is exclusively used by one thread. So two threads may concurrently use two distinct UART devices without any synchronization, but they must synchronize explicitly to access the same UART device.

Fully thread safe are all bus peripherals: A call to e.g. spi_acquire will start a period of exclusive access to the given SPI bus by the calling thread until that calls spi_release.

Peripheral Driver	Initialized By	Thread Safety
periph_adc	user / driver	Partial (no concurrent use of the same ADC line allowed)
periph_can	user / driver	Partial (no concurrent use of the same CAN device allowed)
periph_cpuid	not needed	Full Thread Safety
periph_dac	user / driver	Partial (no concurrent use of the same DAC line allowed)
periph_eeprom	not needed	None (no concurrency whatsoever)
periph_flashpage	not needed	None (no concurrency whatsoever)
periph_gpio	not needed	Limited (reads are fine, concurrent writes to pins on distinct ports work)
periph_gpio_ll	not needed	Yes, except for concurrent initialization of the GPIO pin
periph_hwrng	periph_init	None (no concurrency whatsoever)
periph_i2c	periph_init	Full Thread Safety (except for initialization)
periph_pio	periph_init	Full Thread Safety (except for initialization)
periph_pm	not needed	Full Thread Safety
periph_ptp	periph_init	Full Thread Safety (except for initialization)
periph_pwm	user / driver	Partial (no concurrent use of the same PWM device)
periph_qdec	user / driver	Partial (no concurrent use of the same QDEC device)
periph_rtc	periph_init	None (no concurrency whatsoever)
periph_rtt	periph_init	None (no concurrency whatsoever)
periph_spi	periph_init	Full Thread Safety (except for initialization)
periph_timer	user / driver	Yes, except for concurrent initialization of the same timer
periph_uart	user / driver	Partial (no concurrent use of the same UART device allowed)
periph_usbdev	user / driver (*)	Full Thread Safety (except for initialization)
periph_vbat	periph_init	None (no concurrency whatsoever)
periph_wdt	periph_init	Only wdt_kick() is thread-safe

Note

periph_usbdev requires a low level initialization (usbdev_init_lowlevel) that is done by periph_init. A per device initialization is needed in addition by the user.

Todo:

describe concept in detail

link to driver model

describe/link implementation guide

list best practices

Modules
	ADC
	Low-level ADC peripheral driver interface.
	CAN
	Low-level CAN peripheral driver interface.
	CPUID
	Low-level CPU ID peripheral driver.
	Common peripheral initialization
	Common static peripheral driver initialization.
	DAC
	DAC peripheral driver interface.
	EEPROM driver
	Low-level EEPROM interface.
	FREQM
	FREQM peripheral driver interface.
	Flash page driver
	Low-level flash page interface.
	GPIO
	Low-level GPIO peripheral driver.
	GPIO Low-Level API
	Peripheral GPIO Low-Level API.
	HWRNG Abstraction
	Peripheral hardware random number generator interface.
	I2C
	Low-level I2C peripheral driver.
	PIO I2C program
	PIO I2C program interface.
	PTP-Clock
	Low-level PTP clock peripheral driver.
	PWM
	Low-level PWM peripheral driver.
	Power Management
	The kernels power management interface.
	Programmable IO (PIO)
	Low-level PIO peripheral driver.
	Quadrature Decoder (QDEC)
	Low-level QDEC peripheral driver.
	RTC
	Low-level RTC (Real Time Clock) peripheral driver.
	RTT
	Low-level RTT (Real Time Timer) peripheral driver.
	SDIO/SD/MMC Device API (SDMMC)
	SPI
	Low-level SPI peripheral driver.
	Timer
	Low-level timer peripheral driver.
	UART
	Low-level UART peripheral driver.
	WDT
	Watchdog timer peripheral driver.
	backup battery monitoring
	Driver to monitor the internal backup battery status.
	usbdev - USB Device Driver API
	This is a generic low-level USB driver interface.