Merge #19794 #19912

19794: drivers/periph: Add documentation on thread safety and initialization r=aabadie a=maribu 19912: drivers/at86rf215: switch example config to use EXT3 on same54-xpro r=aabadie a=benpicco Co-authored-by: Marian Buschsieweke <marian.buschsieweke@posteo.net> Co-authored-by: Benjamin Valentin <benjamin.valentin@ml-pa.com>
RIOT-OS · Sep 5, 2023 · da7deb5 · da7deb5
3 parents 9be022a + 6bf23bd + 05bf944
commit da7deb5
Show file tree

Hide file tree

Showing 4 changed files with 71 additions and 5 deletions.
diff --git a/cpu/sam0_common/periph/gpio.c b/cpu/sam0_common/periph/gpio.c
@@ -333,6 +333,10 @@ int gpio_init_int(gpio_t pin, gpio_mode_t mode, gpio_flank_t flank,
         return -1;
     }
 
+    if (gpio_config[exti].cb) {
+        DEBUG("gpio: Warning - interrupt line %u already in use\n", exti);
+    }
+
     /* save callback */
     gpio_config[exti].cb = cb;
     gpio_config[exti].arg = arg;

diff --git a/drivers/at86rf215/include/at86rf215_params.h b/drivers/at86rf215/include/at86rf215_params.h
@@ -28,23 +28,23 @@ extern "C" {
 
 /**
  * @name    Set default configuration parameters for the AT86RF215 driver
- *          Example config for EXT1 on same54-xpro
+ *          Example config for EXT3 on same54-xpro
  * @{
  */
 #ifndef AT86RF215_PARAM_SPI
-#define AT86RF215_PARAM_SPI         (SPI_DEV(0))
+#define AT86RF215_PARAM_SPI         (SPI_DEV(1))
 #endif
 #ifndef AT86RF215_PARAM_SPI_CLK
 #define AT86RF215_PARAM_SPI_CLK     (SPI_CLK_5MHZ)
 #endif
 #ifndef AT86RF215_PARAM_CS
-#define AT86RF215_PARAM_CS          (GPIO_PIN(1, 28))
+#define AT86RF215_PARAM_CS          (GPIO_PIN(2, 14))
 #endif
 #ifndef AT86RF215_PARAM_INT
-#define AT86RF215_PARAM_INT         (GPIO_PIN(1, 7))
+#define AT86RF215_PARAM_INT         (GPIO_PIN(2, 30))
 #endif
 #ifndef AT86RF215_PARAM_RESET
-#define AT86RF215_PARAM_RESET       (GPIO_PIN(1, 8))
+#define AT86RF215_PARAM_RESET       (GPIO_PIN(3, 10))
 #endif
 
 #ifndef AT86RF215_PARAMS

diff --git a/drivers/include/periph/doc.txt b/drivers/include/periph/doc.txt
@@ -16,6 +16,64 @@
  * 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. @ref drivers_periph_eeprom)
+ * 2. Drivers that are automatically initialized by the module `periph_init` at boot,
+ *    (see @ref drivers_periph_init for details)
+ * 3. Drivers that require manual initialization (e.g. @ref drivers_periph_uart
+ *    or @ref drivers_periph_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. @ref spi_acquire
+ * will start a period of exclusive access to the given SPI bus by the calling
+ * thread until that calls @ref 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
+ *          (@ref 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
  * @todo        link to driver model
  * @todo        describe/link implementation guide

diff --git a/drivers/include/periph/init.h b/drivers/include/periph/init.h
@@ -36,6 +36,10 @@ extern "C" {
  * configured peripheral drivers like SPI or I2C. This function SHOULD be called
  * early in the boot process, e.g. before the actual kernel initialization is
  * started.
+ *
+ * @note    This function is called by the boot up code. Application developers
+ *          do not need to care. Developers porting RIOT to a new MCU must make
+ *          sure that this function is called during boot up early on.
  */
 void periph_init(void);