Merge branch 'master' into rust-gcoap-add-saul

.murdock

@@ -37,8 +37,10 @@ esac
 
 #: ${EMULATED_BOARDS_AVAILABLE:="microbit"}
 
-# temporarily disabling llvm builds until https://github.com/RIOT-OS/RIOT/pull/15595
-# is in
+# Only a subset of boards are compiled on LLVM to not increase CI time by
+# factor 2, but still have a decent regression test coverage.
+# TODO: Consider reusing QUICKBUILD_BOARDS once all those boards are supported
+# on LLVM.
 : ${TEST_BOARDS_LLVM_COMPILE:="iotlab-m3 native native64 nrf52dk mulle nucleo-f401re samr21-xpro slstk3402a"}
 
 : ${TEST_WITH_CONFIG_SUPPORTED:="examples/suit_update tests/drivers/at86rf2xx_aes"}

CODEOWNERS

@@ -7,6 +7,9 @@
 
 *.md                                        @jia200x
 
+Cargo.*                                     @chrysn
+*.rs                                        @chrysn
+
 /.murdock                                   @kaspar030
 
 /boards/common/atxmega/                     @nandojve

Makefile.base

@@ -97,9 +97,6 @@ compile-commands: | $(DIRS:%=COMPILE-COMMANDS--%)
 	$(file >>$(BINDIR)/$(MODULE)/compile_cmds.txt,TARGET_ARCH: $(TARGET_ARCH))
 	$(file >>$(BINDIR)/$(MODULE)/compile_cmds.txt,TARGET_ARCH_LLVM: $(TARGET_ARCH_LLVM))
 
-# include makefile snippets for packages in $(PKG_PATHS) that modify GENSRC:
--include $(PKG_PATHS:%=%Makefile.gensrc)
-
 GENOBJC     := $(GENSRC:%.c=%.o)
 OBJC_LTO    := $(SRC:%.c=$(BINDIR)/$(MODULE)/%.o)
 OBJC_NOLTO  := $(SRC_NOLTO:%.c=$(BINDIR)/$(MODULE)/%.o)

Makefile.include

@@ -506,6 +506,15 @@ TOOLCHAINS_SUPPORTED ?= gnu
 # Import all toolchain settings
 include $(RIOTMAKE)/toolchain/$(TOOLCHAIN).inc.mk
 
+# Other than on native, RWX segments in ROM are not actually RWX, as regular
+# store instructions won't write to flash.
+ifeq (,$(filter native native64,$(BOARD)))
+  LINKER_SUPPORTS_NOWARNRWX ?= $(shell LC_ALL=C $(LINK) $(RIOTTOOLS)/testprogs/minimal_linkable.c -o /dev/null -lc -Wall -Wextra -pedantic -Wl,--no-warn-rwx-segments 2> /dev/null && echo 1 || echo 0)
+  ifeq (1,$(LINKER_SUPPORTS_NOWARNRWX))
+    LINKFLAGS += -Wl,--no-warn-rwx-segments
+  endif
+endif
+
 # Append ldscript path after importing CPU and board makefiles to allow
 # overriding the core ldscripts
 LINKFLAGS += -L$(RIOTBASE)/core/ldscripts
@@ -709,6 +718,12 @@ BUILDDEPS += $(BUILD_DIR)/CACHEDIR.TAG
 # clean removing dependencies that make previously considered as up to date.
 $(BUILDDEPS): $(CLEAN)
 
+# include makefile snippets for packages in $(PKG_PATHS) that modify GENSRC:
+-include $(PKG_PATHS:%=%Makefile.gensrc)
+# remove duplicates & make accessible to subprocesses
+GENSRC := $(sort $(GENSRC))
+export GENSRC
+
 # Save value to verify it is not modified later
 _BASELIBS_VALUE_BEFORE_USAGE := $(BASELIBS)
 
@@ -757,7 +772,7 @@ $(APPLICATION_MODULE).module: FORCE
 
 # Other modules are built by application.inc.mk and packages building
 _SUBMAKE_LIBS = $(filter-out $(APPLICATION_MODULE).module $(APPDEPS), $(BASELIBS) $(ARCHIVES))
-$(_SUBMAKE_LIBS): $(APPLICATION_MODULE).module pkg-build
+$(_SUBMAKE_LIBS): $(APPLICATION_MODULE).module pkg-build $(GENSRC)
 
 # 'print-size' triggers a rebuild. Use 'info-buildsize' if you do not need to rebuild.
 print-size: $(ELFFILE)
@@ -810,13 +825,15 @@ endif
 	@$(COLOR_ECHO)
 
 # The `clean` needs to be serialized before everything else.
-all $(BASELIBS) $(ARCHIVES) $(BUILDDEPS) ..in-docker-container: | $(CLEAN)
+all $(BASELIBS) $(ARCHIVES) $(BUILDDEPS) $(GENSRC) ..in-docker-container: | $(CLEAN)
 
 .PHONY: pkg-prepare pkg-build
 pkg-prepare:
 	-@$(foreach dir,$(PKG_PATHS),"$(MAKE)" -C $(dir) prepare $(NEWLINE))
 
-pkg-build: $(BUILDDEPS)
+$(GENSRC): pkg-prepare
+
+pkg-build: $(BUILDDEPS) | $(GENSRC)
 	$(foreach dir,$(PKG_PATHS),$(QQ)"$(MAKE)" -C $(dir) $(NEWLINE))
 
 clean:

README.md

@@ -4,7 +4,7 @@
 [![API docs][api-badge]][api-link]
 [![Wiki][wiki-badge]][wiki-link]
 [![Stack Overflow questions][stackoverflow-badge]][stackoverflow-link]
-[![Twitter][twitter-badge]][twitter-link]
+[![Mastodon][mastodon-badge]][mastodon-link]
 [![Matrix][matrix-badge]][matrix-link]
 
 <p align="center"><img src="doc/doxygen/src/riot-logo.svg" width="66%"><!--
@@ -117,6 +117,11 @@ For specific toolchain installation, follow instructions in the
   version of the documentation is uploaded daily to
   [doc.riot-os.org](https://doc.riot-os.org).
 
+Using Windows? Use [this guide][dev-setup-windows] to
+[setup the development environment][dev-setup-windows].
+
+[dev-setup-windows]: doc/guides/setup-windows
+
 ## Forum
 Do you have a question, want to discuss a new feature, or just want to present
 your latest project using RIOT? Come over to our [forum] and post to your hearts
@@ -160,7 +165,7 @@ https://www.riot-os.org
 [release-link]: https://github.com/RIOT-OS/RIOT/releases/latest
 [stackoverflow-badge]: https://img.shields.io/badge/stackoverflow-%5Briot--os%5D-yellow
 [stackoverflow-link]: https://stackoverflow.com/questions/tagged/riot-os
-[twitter-badge]: https://img.shields.io/badge/social-Twitter-informational.svg
-[twitter-link]: https://twitter.com/RIOT_OS
+[mastodon-badge]: https://img.shields.io/badge/social-Mastodon-informational.svg
+[mastodon-link]: https://fosstodon.org/@RIOT_OS
 [wiki-badge]: https://img.shields.io/badge/docs-Wiki-informational.svg
 [wiki-link]: https://github.com/RIOT-OS/RIOT/wiki

boards/common/nucleo144/include/board.h

@@ -26,8 +26,8 @@
 #ifndef BOARD_H
 #define BOARD_H
 
-#include "board_nucleo.h"
 #include "arduino_pinmap.h"
+#include "board_nucleo.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -37,24 +37,27 @@ extern "C" {
  * @name    LED pin definitions and handlers
  * @{
  */
-#if defined(CPU_MODEL_STM32L496ZG) || defined(CPU_MODEL_STM32L4R5ZI) || \
-    defined(CPU_MODEL_STM32L552ZE)
-#define LED0_PIN_NUM        7
-#define LED0_PORT_NUM       PORT_C
+#if defined(CPU_MODEL_STM32L496ZG) || defined(CPU_MODEL_STM32L4R5ZI) ||        \
+    defined(CPU_MODEL_STM32L552ZE) || defined(CPU_MODEL_STM32U575ZI)
+#define LED0_PIN_NUM 7
+#define LED0_PORT_NUM PORT_C
 #else
-#define LED0_PIN_NUM        0
-#define LED0_PORT_NUM       PORT_B
+#define LED0_PIN_NUM 0
+#define LED0_PORT_NUM PORT_B
 #endif
 
-#define LED1_PIN_NUM        7
-#define LED1_PORT_NUM       PORT_B
+#define LED1_PIN_NUM 7
+#define LED1_PORT_NUM PORT_B
 
 #if defined(CPU_MODEL_STM32L552ZE)
-#define LED2_PIN_NUM        9
-#define LED2_PORT_NUM       PORT_A
+#define LED2_PIN_NUM 9
+#define LED2_PORT_NUM PORT_A
+#elif defined(CPU_MODEL_STM32U575ZI)
+#define LED2_PIN_NUM 2
+#define LED2_PORT_NUM PORT_G
 #else
-#define LED2_PIN_NUM        14
-#define LED2_PORT_NUM       PORT_B
+#define LED2_PIN_NUM 14
+#define LED2_PORT_NUM PORT_B
 #endif
 /** @} */
 
@@ -62,8 +65,8 @@ extern "C" {
  * @name    User button
  * @{
  */
-#define BTN0_PIN            GPIO_PIN(PORT_C, 13)
-#define BTN0_MODE           GPIO_IN_PD
+#define BTN0_PIN GPIO_PIN(PORT_C, 13)
+#define BTN0_MODE GPIO_IN_PD
 /** @} */
 
 #ifdef __cplusplus

boards/feather-nrf52840-sense/Makefile.dep

@@ -2,6 +2,7 @@ ifneq (,$(filter saul_default,$(USEMODULE)))
   USEMODULE += apds9960
   USEMODULE += bmp280_i2c
   USEMODULE += lis3mdl
+  USEMODULE += lsm6ds33
   USEMODULE += saul_gpio
   USEMODULE += sht3x
 endif

boards/nucleo-u575zi-q/Makefile

@@ -0,0 +1,4 @@
+MODULE = board
+DIRS = $(RIOTBOARD)/common/nucleo
+
+include $(RIOTBASE)/Makefile.base

boards/nucleo-u575zi-q/Makefile.dep

@@ -0,0 +1 @@
+include $(RIOTBOARD)/common/nucleo/Makefile.dep

boards/nucleo-u575zi-q/Makefile.features

@@ -0,0 +1,12 @@
+CPU = stm32
+CPU_MODEL = stm32u575zi
+
+# Put defined MCU peripherals here (in alphabetical order)
+FEATURES_PROVIDED += periph_i2c
+FEATURES_PROVIDED += periph_pwm
+FEATURES_PROVIDED += periph_timer
+FEATURES_PROVIDED += periph_uart periph_lpuart
+FEATURES_PROVIDED += periph_usbdev
+
+# load the common Makefile.features for Nucleo boards
+include $(RIOTBOARD)/common/nucleo144/Makefile.features

boards/nucleo-u575zi-q/Makefile.include

@@ -0,0 +1,2 @@
+# load the common Makefile.include for Nucleo boards
+include $(RIOTBOARD)/common/nucleo144/Makefile.include

boards/nucleo-u575zi-q/doc.txt

@@ -0,0 +1,63 @@
+/**
+@defgroup    boards_nucleo-u575zi-q STM32 Nucleo-U575ZI-Q
+@ingroup     boards_common_nucleo144
+@brief       Support for the STM32 Nucleo-U575ZI-Q
+
+## Overview
+
+The Nucleo-L552ZE-Q is a board from ST's Nucleo family supporting the ARM Cortex-M33
+STM32U575ZIT6Q ultra-low-power microcontroller with TrustZone, 768KiB of RAM and 2MiB
+of Flash.
+
+## Hardware
+
+![Nucleo144 L552ZE-Q](https://www.st.com/bin/ecommerce/api/image.PF271812.en.feature-description-include-personalized-no-cpn-medium.jpg)
+
+### MCU
+
+| MCU          | STM32U575ZIT6Q               |
+|:-------------|:-----------------------------|
+| Family       | ARM Cortex-M33               |
+| Vendor       | ST Microelectronics          |
+| RAM          | 786KiB                       |
+| Flash        | 2MiB                         |
+| Frequency    | up tp 160MHz                 |
+| FPU          | yes                          |
+| TrustZone    | yes                          |
+| Timers       | 17                           |
+| UARTs        | 6 (3xUSART, 2xUART, 1xLPUART)|
+| I2cs         | 4                            |
+| SPIs         | 3                            |
+| CAN          | 1                            |
+| Datasheet    | [Datasheet](https://www.st.com/resource/en/datasheet/stm32u575zi.pdf)|
+| Programming Manual | [Programming Manual](https://www.st.com/resource/en/programming_manual/pm0264-stm32-cortexm33-mcus-programming-manual-stmicroelectronics.pdf)|
+| Board Manual | [Board Manual](https://www.st.com/resource/en/user_manual/um2861-stm32u5-nucleo144-board-mb1549-stmicroelectronics.pdf)|
+
+## Flashing the device
+
+### Flashing the Board Using OpenOCD
+
+The ST Nucleo-L552ZE-Q board includes an on-board ST-LINK programmer and can be
+flashed using OpenOCD.
+
+Once OpenOCD is installed, you can flash the board simply by typing
+
+```
+make BOARD=nucleo-u575zi-q flash
+```
+
+and debug via GDB by simply typing
+```
+make BOARD=nucleo-u575zi-q debug
+```
+
+## Accessing RIOT shell
+
+Default RIOT shell access utilize VCP (Virtual COM Port) via USB interface,
+provided by integrated ST-LINK programmer. ST-LINK is connected to the
+microcontroller USART1.
+
+The default baud rate is 115 200.
+
+If a physical connection to USART1 is needed, connect UART interface to pins PA9 (USART1 TX) and PA10 (USART1 RX).
+*/

boards/nucleo-u575zi-q/include/periph_conf.h

@@ -0,0 +1,183 @@
+/*
+ * Copyright (C) 2024 TU Dresden
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     boards_nucleo-u575zi-q
+ * @{
+ *
+ * @file
+ * @brief       Peripheral MCU configuration for the nucleo-u575zi-q board
+ *
+ * @author      Nils Ollrogge <nils.ollrogge@mailbox.tu-dresden.de>
+ */
+
+#ifndef PERIPH_CONF_H
+#define PERIPH_CONF_H
+
+/* Add specific clock configuration (HSE, LSE) for this board here */
+#ifndef CONFIG_BOARD_HAS_LSE
+#define CONFIG_BOARD_HAS_LSE 1
+#endif
+
+#include "cfg_timer_tim5.h"
+#include "cfg_usb_otg_fs_u5.h"
+#include "clk_conf.h"
+#include "periph_cpu.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @name    UART configuration
+ * @{
+ */
+static const uart_conf_t uart_config[] = {
+    {
+        .dev = USART1,
+        .rcc_mask = RCC_APB2ENR_USART1EN,
+        .rx_pin = GPIO_PIN(PORT_A, 10),
+        .tx_pin = GPIO_PIN(PORT_A, 9),
+        .rx_af = GPIO_AF7,
+        .tx_af = GPIO_AF7,
+        .bus = APB2,
+        .irqn = USART1_IRQn,
+        .type = STM32_USART,
+        .clk_src = 0, /* Use APB clock */
+    },
+    {
+        .dev = LPUART1,
+        .rcc_mask = RCC_APB3ENR_LPUART1EN,
+        .rx_pin = GPIO_PIN(PORT_G, 8),
+        .tx_pin = GPIO_PIN(PORT_G, 7),
+        .rx_af = GPIO_AF8,
+        .tx_af = GPIO_AF8,
+        .bus = APB3,
+        .irqn = LPUART1_IRQn,
+        .type = STM32_LPUART,
+        .clk_src = 0, /* Use APB clock */
+    },
+};
+
+#define UART_0_ISR (isr_usart1)
+#define UART_1_ISR (isr_lpuart1)
+
+#define UART_NUMOF ARRAY_SIZE(uart_config)
+/** @} */
+
+/**
+ * @name   SPI configuration
+ * @{
+ */
+static const spi_conf_t spi_config[] = {
+    {
+        .dev = SPI1,
+        .mosi_pin = GPIO_PIN(PORT_A, 7),    /* Arduino D11 */
+        .miso_pin = GPIO_PIN(PORT_A, 6),    /* Arduino D12 */
+        .sclk_pin = GPIO_PIN(PORT_A, 5),    /* Arduino D13 */
+        .cs_pin = GPIO_UNDEF,
+        .mosi_af = GPIO_AF5,
+        .miso_af = GPIO_AF5,
+        .sclk_af = GPIO_AF5,
+        .cs_af = GPIO_AF5,
+        .rccmask = RCC_APB2ENR_SPI1EN,
+        .apbbus = APB2,
+    },
+};
+
+#define SPI_NUMOF ARRAY_SIZE(spi_config)
+/** @} */
+
+/**
+ * @name I2C configuration
+ * @{
+ */
+static const i2c_conf_t i2c_config[] = {
+    {
+        .dev = I2C1,
+        .speed = I2C_SPEED_NORMAL,
+        .scl_pin = GPIO_PIN(PORT_B, 8),
+        .sda_pin = GPIO_PIN(PORT_B, 9),
+        .scl_af = GPIO_AF4,
+        .sda_af = GPIO_AF4,
+        .bus = APB1,
+        .rcc_mask = RCC_APB1ENR1_I2C1EN,
+        .rcc_sw_mask = RCC_CCIPR1_I2C1SEL_1,
+        .irqn = I2C1_ER_IRQn,
+    },
+    {
+        .dev = I2C2,
+        .speed = I2C_SPEED_NORMAL,
+        .scl_pin = GPIO_PIN(PORT_F, 1),
+        .sda_pin = GPIO_PIN(PORT_F, 0),
+        .scl_af = GPIO_AF4,
+        .sda_af = GPIO_AF4,
+        .bus = APB1,
+        .rcc_mask = RCC_APB1ENR1_I2C2EN,
+        .rcc_sw_mask = RCC_CCIPR1_I2C2SEL_1,
+        .irqn = I2C2_ER_IRQn,
+    },
+};
+
+#define I2C_0_ISR isr_i2c1_er
+#define I2C_1_ISR isr_i2c2_er
+#define I2C_NUMOF ARRAY_SIZE(i2c_config)
+/** @} */
+
+/**
+ * @name    PWM configuration
+ *
+ * To find appriopate device and channel find in the MCU datasheet table
+ * concerning "Alternate function AF0 to AF7" a text similar to TIM[X]_CH[Y],
+ * where:
+ * TIM[X] - is device,
+ * [Y] - describes used channel (indexed from 0), for example TIM2_CH1 is
+ * channel 0 in configuration structure (cc_chan - field),
+ * Port column in the table describes connected port.
+ *
+ * For Nucleo-U575ZI-Q this information is in the datasheet, Table 27, page 127.
+ *
+ * @{
+ */
+static const pwm_conf_t pwm_config[] = {
+    { .dev = TIM2,
+      .rcc_mask = RCC_APB1ENR1_TIM2EN,
+      .chan = { { .pin = GPIO_PIN(PORT_A, 0) /* CN10 D32 */, .cc_chan = 0 },
+          { .pin = GPIO_PIN(PORT_A, 1) /* CN10  A8 */, .cc_chan = 1 },
+          { .pin = GPIO_PIN(PORT_A, 2) /*  CN9  A1 */, .cc_chan = 2 },
+          { .pin = GPIO_PIN(PORT_A, 3) /*  CN9  A0 */, .cc_chan = 3 } },
+      .af = GPIO_AF1,
+      .bus = APB1 },
+    { .dev = TIM3,
+      .rcc_mask = RCC_APB1ENR1_TIM3EN,
+      .chan = { { .pin = GPIO_PIN(PORT_B, 4) /*  CN7 D25 */, .cc_chan = 0 },
+          { .pin = GPIO_PIN(PORT_B, 5) /*  CN7 D22 */, .cc_chan = 1 },
+          { .pin = GPIO_PIN(PORT_B, 0) /*  CN9  A3 */, .cc_chan = 2 },
+          { .pin = GPIO_PIN(PORT_B, 1) /* CN10  A6 */, .cc_chan = 3 } },
+      .af = GPIO_AF2,
+      .bus = APB1 },
+    { .dev = TIM4,
+      .rcc_mask = RCC_APB1ENR1_TIM4EN,
+      .chan = { { .pin = GPIO_PIN(PORT_D, 12) /*  CN7 D19 */, .cc_chan = 0 },
+          { .pin = GPIO_PIN(PORT_B, 7) /* Blue LD2 */, .cc_chan = 1 },
+          { .pin = GPIO_PIN(PORT_D, 14) /*  CN7 D10 */, .cc_chan = 2 },
+          { .pin = GPIO_PIN(PORT_D, 15) /*  CN7  D9 */, .cc_chan = 3 } },
+      .af = GPIO_AF2,
+      .bus = APB1 },
+};
+
+#define PWM_NUMOF ARRAY_SIZE(pwm_config)
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* PERIPH_CONF_H */
+/** @} */

boards/rpi-pico/Kconfig

@@ -14,6 +14,7 @@ config BOARD_RPI_PICO
     select CPU_MODEL_RP2040
     select HAS_PERIPH_ADC
     select HAS_PERIPH_I2C
+    select HAS_PERIPH_PWM
     select HAS_PERIPH_UART
     select HAS_PERIPH_SPI
 

boards/rpi-pico/Makefile.features

@@ -4,5 +4,6 @@ CPU := rpx0xx
 FEATURES_PROVIDED += periph_adc
 FEATURES_PROVIDED += periph_i2c
 FEATURES_PROVIDED += periph_spi
+FEATURES_PROVIDED += periph_pwm
 FEATURES_PROVIDED += periph_timer
 FEATURES_PROVIDED += periph_uart

boards/rpi-pico/include/periph_conf.h

@@ -176,6 +176,23 @@ static const pio_i2c_conf_t pio_i2c_config[] = {
 #endif
 /** @} */
 
+/**
+ * @name   PWM configuration
+ * @{
+ */
+static const pwm_conf_t pwm_config[] = {
+    {
+        .pwm_slice   = 4,
+        .chan    = {
+            { .pin = GPIO_PIN(0, 25), .cc_chan = 1 },   /* rpi-pico onboard LED */
+            { .pin = GPIO_UNDEF,      .cc_chan = 0 },
+        },
+    },
+};
+
+#define PWM_NUMOF ARRAY_SIZE(pwm_config)
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

bootloaders/riotboot_common.mk

@@ -26,4 +26,4 @@ include $(RIOTBASE)/Makefile.include
 # limit riotboot bootloader size
 # TODO: Manage to set this variable for boards which already embed a
 # bootloader, currently it will be overwritten
-ROM_LEN := $(RIOTBOOT_LEN)
+FW_ROM_LEN := $(RIOTBOOT_LEN)

core/include/mbox.h

@@ -185,6 +185,17 @@ static inline size_t mbox_avail(mbox_t *mbox)
     return cib_avail(&mbox->cib);
 }
 
+/**
+ * @brief   Unset's the mbox, effectively deinitializing and invalidating it.
+ *
+ * @param[in] mbox  ptr to mailbox to operate on
+ */
+static inline void mbox_unset(mbox_t *mbox)
+{
+    mbox->msg_array = NULL;
+    mbox->cib.mask = 0;
+}
+
 #ifdef __cplusplus
 }
 #endif

core/lib/include/cib.h

@@ -107,7 +107,8 @@ static inline unsigned int cib_full(const cib_t *cib)
  *
  * @param[in,out] cib   corresponding *cib* to buffer.
  *                      Must not be NULL.
- * @return index of next item, -1 if the buffer is empty
+ * @return index of next item
+ * @retval -1 if the buffer is empty
  */
 static inline int cib_get(cib_t *__restrict cib)
 {
@@ -118,20 +119,75 @@ static inline int cib_get(cib_t *__restrict cib)
     return -1;
 }
 
+/**
+ * @brief Get the index of an item in the buffer without removing anything.
+ *
+ * Offset 0 is the next item in the buffer that would be returned by
+ * `cip_get()`, offset 1 would be the following, and so on.
+ *
+ * Unsafe version, *must not* pass an offset that is larger than the number of
+ * items currently in the buffer!
+ *
+ * @param[in,out] cib   corresponding *cib* to buffer.
+ *                      Must not be NULL.
+ * @param[in] offset    offset from front of buffer
+ *
+ * @return index of item
+ * @retval -1 if no item at @p offset exists in the buffer
+ */
+static inline int cib_peek_at_unsafe(cib_t *__restrict cib, unsigned offset)
+{
+    return (cib->read_count + offset) & cib->mask;
+}
+
+/**
+ * @brief Get the index of an item in the buffer without removing anything.
+ *
+ * Offset 0 is the next item in the buffer that would be returned by
+ * `cip_get()`, offset 1 would be the following, and so on.
+ *
+ * @param[in,out] cib   corresponding *cib* to buffer.
+ *                      Must not be NULL.
+ * @param[in] offset    offset from front of buffer
+ *
+ * @return index of item
+ * @retval -1 if no item at @p offset exists in the buffer
+ */
+static inline int cib_peek_at(cib_t *__restrict cib, unsigned offset)
+{
+    if (offset < cib_avail(cib)) {
+        return cib_peek_at_unsafe(cib, offset);
+    }
+
+    return -1;
+}
+
+/**
+ * @brief Get the index of the next item in buffer without removing it.
+ *
+ * Unsafe version, *must not* be called if buffer is empty!
+ *
+ * @param[in,out] cib   corresponding *cib* to buffer.
+ *                      Must not be NULL.
+ * @return index of next item
+ * @retval -1 if the buffer is empty
+ */
+static inline int cib_peek_unsafe(cib_t *__restrict cib)
+{
+    return cib_peek_at_unsafe(cib, 0);
+}
+
 /**
  * @brief Get the index of the next item in buffer without removing it.
  *
  * @param[in,out] cib   corresponding *cib* to buffer.
  *                      Must not be NULL.
- * @return index of next item, -1 if the buffer is empty
+ * @return index of next item
+ * @retval -1 if the buffer is empty
  */
 static inline int cib_peek(cib_t *__restrict cib)
 {
-    if (cib_avail(cib)) {
-        return (int)(cib->read_count & cib->mask);
-    }
-
-    return -1;
+    return cib_peek_at(cib, 0);
 }
 
 /**
@@ -153,7 +209,8 @@ static inline int cib_get_unsafe(cib_t *cib)
  *
  * @param[in,out] cib   corresponding *cib* to buffer.
  *                      Must not be NULL.
- * @return index of item to put to, -1 if the buffer is full
+ * @return index of item to put to
+ * @retval -1 if the buffer is full
  */
 static inline int cib_put(cib_t *__restrict cib)
 {

core/lib/init.c

@@ -74,6 +74,17 @@ static void *main_trampoline(void *arg)
     }
 #endif
 
+#ifdef CPU_NATIVE
+    extern unsigned _native_retval;
+    if (!_native_retval) {
+        _native_retval = res;
+    }
+#endif
+
+    if (IS_ACTIVE(CONFIG_CORE_EXIT_WITH_MAIN)) {
+        pm_off();
+    }
+
     return NULL;
 }
 

cpu/cortexm_common/Makefile.features

@@ -7,6 +7,7 @@ FEATURES_PROVIDED += cpu_core_cortexm
 FEATURES_PROVIDED += dbgpin
 FEATURES_PROVIDED += libstdcpp
 FEATURES_PROVIDED += newlib
+FEATURES_PROVIDED += periph_flashpage_aux
 FEATURES_PROVIDED += periph_pm
 FEATURES_PROVIDED += puf_sram
 FEATURES_PROVIDED += picolibc

cpu/cortexm_common/ldscripts/cortexm_base.ld

@@ -41,6 +41,7 @@ _backup_ram_len = DEFINED( _backup_ram_len ) ? _backup_ram_len : 0x0 ;
 MEMORY
 {
     bkup_ram (w!rx) : ORIGIN = _backup_ram_start_addr, LENGTH = _backup_ram_len
+    rom_aux  (rx)   : ORIGIN = _rom_start_addr + _slot_aux_offset, LENGTH = _slot_aux_len
 }
 
 /* Section Definitions */

cpu/cortexm_common/ldscripts/cortexm_rom_offset.ld

@@ -21,6 +21,8 @@
  */
 
 _rom_offset = DEFINED( _rom_offset ) ? _rom_offset : 0x0;
-_fw_rom_length = DEFINED( _fw_rom_length ) ? _fw_rom_length : _rom_length - _rom_offset;
+_slot_aux_len = DEFINED( _slot_aux_len ) ? _slot_aux_len  : 0x0;
+_fw_rom_length = DEFINED( _fw_rom_length ) ? _fw_rom_length : _rom_length - _rom_offset - _slot_aux_len;
 
-ASSERT((_fw_rom_length <= _rom_length - _rom_offset), "Specified firmware size does not fit in ROM");
+ASSERT(_fw_rom_length <= _rom_length - _rom_offset - _slot_aux_len, "Specified firmware size does not fit in ROM");
+ASSERT(_fw_rom_length <= _rom_length, "Specified firmware size does not fit in ROM");

cpu/gd32v/Makefile.include

@@ -17,7 +17,7 @@ else
   $(error CPU model $(CPU_MODEL) not supported)
 endif
 
-FW_ROM_LEN ?= $(shell printf "0x%x" $$(($(ROM_LEN:%K=%*1024))))
+ROM_LEN := $(shell printf "0x%x" $$(($(ROM_LEN:%K=%*1024))))
 
 RIOTBOOT_HDR_LEN ?= 0x400
 ifneq (,$(filter usbus_dfu tinyusb_dfu,$(USEMODULE)))

cpu/native/native_cpu.c

@@ -184,8 +184,9 @@ void cpu_switch_context_exit(void)
 {
 #ifdef NATIVE_AUTO_EXIT
     if (sched_num_threads <= 1) {
+        extern unsigned _native_retval;
         DEBUG("cpu_switch_context_exit: last task has ended. exiting.\n");
-        real_exit(EXIT_SUCCESS);
+        real_exit(_native_retval);
     }
 #endif
 

cpu/riscv_common/Makefile.features

@@ -8,6 +8,7 @@ FEATURES_PROVIDED += cpp
 FEATURES_PROVIDED += libstdcpp
 FEATURES_PROVIDED += newlib
 FEATURES_PROVIDED += periph_coretimer
+FEATURES_PROVIDED += periph_flashpage_aux
 FEATURES_PROVIDED += puf_sram
 FEATURES_PROVIDED += rust_target
 FEATURES_PROVIDED += ssp

cpu/riscv_common/Makefile.include

@@ -14,10 +14,8 @@ ifneq (,$(ROM_START_ADDR)$(RAM_START_ADDR)$(ROM_LEN)$(RAM_LEN))
   LINKFLAGS += $(LINKFLAGPREFIX)--defsym=_ram_start_addr=$(RAM_START_ADDR)
   LINKFLAGS += $(LINKFLAGPREFIX)--defsym=_rom_length=$(ROM_LEN)
   LINKFLAGS += $(LINKFLAGPREFIX)--defsym=_ram_length=$(RAM_LEN)
-  LINKFLAGS += $(if $(ROM_OFFSET),$(LINKFLAGPREFIX)--defsym=_rom_offset=$(ROM_OFFSET) \
-                                 ,$(LINKFLAGPREFIX)--defsym=_rom_offset=0x0)
-  LINKFLAGS += $(if $(FW_ROM_LEN),$(LINKFLAGPREFIX)--defsym=_fw_rom_length=$(FW_ROM_LEN) \
-                                 ,$(LINKFLAGPREFIX)--defsym=_fw_rom_length=$(ROM_LEN))
+  LINKFLAGS += $(if $(ROM_OFFSET),$(LINKFLAGPREFIX)--defsym=_rom_offset=$(ROM_OFFSET))
+  LINKFLAGS += $(if $(FW_ROM_LEN),$(LINKFLAGPREFIX)--defsym=_fw_rom_length=$(FW_ROM_LEN))
 endif
 
 ifneq (,$(ITIM_START_ADDR))

cpu/riscv_common/ldscripts/riscv.ld

@@ -25,6 +25,7 @@ MEMORY
   flash (rxai!w) : ORIGIN = _rom_start_addr + _rom_offset, LENGTH = _fw_rom_length
   ram   (wxa!ri) : ORIGIN = _ram_start_addr, LENGTH = _ram_length
   itim  (wxa!ri) : ORIGIN = _itim_start_addr, LENGTH = _itim_length
+  rom_aux (rx)   : ORIGIN = _rom_start_addr + _slot_aux_offset, LENGTH = _slot_aux_len
 }
 
 INCLUDE riscv_base.ld

cpu/riscv_common/ldscripts/riscv_vars.ld

@@ -21,3 +21,10 @@
 
 _itim_start_addr = DEFINED( _itim_start_addr ) ? _itim_start_addr : 0x0;
 _itim_length = DEFINED( _itim_length ) ? _itim_length : 0x0;
+
+_rom_offset = DEFINED( _rom_offset ) ? _rom_offset : 0x0;
+_slot_aux_len = DEFINED( _slot_aux_len ) ? _slot_aux_len  : 0x0;
+_fw_rom_length = DEFINED( _fw_rom_length ) ? _fw_rom_length : _rom_length - _rom_offset - _slot_aux_len;
+
+ASSERT(_fw_rom_length <= _rom_length - _rom_offset - _slot_aux_len, "Specified firmware size does not fit in ROM");
+ASSERT(_fw_rom_length <= _rom_length, "Specified firmware size does not fit in ROM");

cpu/rpx0xx/include/periph_cpu.h

@@ -399,6 +399,34 @@ typedef struct {
     uint8_t chan;           /**< CPU ADC channel connected to the pin */
 } adc_conf_t;
 
+/**
+ * @brief   Number of slices available per PWM device
+ */
+#define PWM_SLICE_NUMOF   (8)
+
+/**
+ * @brief   Number of channels available per slice
+ */
+#define PWM_CHANNEL_NUMOF (2)
+
+/**
+ * @brief   PWM channel
+ */
+typedef struct {
+    gpio_t pin;             /**< GPIO pin mapped to this channel */
+    uint8_t cc_chan;        /**< capture compare channel used */
+} pwm_chan_t;
+
+/**
+ * @brief   PWM device configuration data structure
+ */
+typedef struct {
+    uint8_t pwm_slice;                      /**< PWM slice instance,
+                                                must be < to PWM_SLICE_NUMOF */
+    pwm_chan_t chan[PWM_CHANNEL_NUMOF];     /**< channel mapping set to
+                                                 {GPIO_UNDEF, 0} if not used */
+} pwm_conf_t;
+
 /**
  * @brief   Configuration details for an UART interface needed by the RPX0XX peripheral
  */

cpu/rpx0xx/periph/pwm.c

@@ -0,0 +1,149 @@
+/*
+ * Copyright (C) 2023-2024 Mesotic SAS
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     cpu_rpx0xx
+ * @ingroup     drivers_periph_pwm
+ * @{
+ *
+ * @file
+ * @brief       Low-level PWM driver implementation
+ *
+ * @author      Dylan Laduranty <dylan.laduranty@mesotic.com>
+ *
+ * @}
+ */
+
+#include "cpu.h"
+#include "assert.h"
+#include "periph/pwm.h"
+#include "periph/gpio.h"
+#include "periph_conf.h"
+#include <stdio.h>
+
+#define ENABLE_DEBUG    0
+#include "debug.h"
+
+/* Vendor files don't offer a convenient way to access these registers
+   through a dedicated struct, thus create one for this purpose */
+typedef struct {
+    uint32_t csr;
+    uint32_t div;
+    uint32_t ctr;
+    uint32_t cc;
+    uint32_t top;
+} pwm_slice_reg_t;
+
+/* Structure holding all PWM slices registers */
+struct pwm_reg {
+    pwm_slice_reg_t slices[PWM_SLICE_NUMOF];
+};
+
+/* Start address of PWM slices */
+#define PWM_REG ((struct pwm_reg *)PWM_BASE)
+
+/* Helper to get slice register */
+static inline pwm_slice_reg_t *pwm_slice(unsigned slice_idx)
+{
+    return &PWM_REG->slices[slice_idx];
+}
+
+/* PWM block is feed by RP2040 sysclk (CLOCK_CORECLOCK) */
+uint32_t pwm_init(pwm_t pwm, pwm_mode_t mode, uint32_t freq, uint16_t res)
+{
+    uint8_t div_int;
+    uint8_t div_frac;
+    uint32_t val;
+    uint32_t ret;
+    uint8_t slice = pwm_config[pwm].pwm_slice;
+
+    (void)mode;
+
+    const gpio_io_ctrl_t pwm_io_config = {
+        .function_select = FUNCTION_SELECT_PWM,
+    };
+
+    /* Initialize associated GPIO pin */
+    if (pwm_config[pwm].chan[0].pin != GPIO_UNDEF) {
+        gpio_set_io_config(pwm_config[pwm].chan[0].pin, pwm_io_config);
+    }
+    if (pwm_config[pwm].chan[1].pin != GPIO_UNDEF) {
+        gpio_set_io_config(pwm_config[pwm].chan[1].pin, pwm_io_config);
+    }
+
+    /* Compute DIV register value to get closest match for
+       freq and res variables */
+    val = (((uint32_t)CLOCK_CORECLOCK) << 4) / (freq * res);
+    /* If the value is above 4095, we will not be able to reach the desired
+       frequency so set the divisor value to maximum to get to the closest
+       possible value for the PWM frequency */
+    if (val > 4095) {
+        div_frac = 0x0F;
+        div_int = 0xFF;
+    } else {
+        div_frac = val % 16;
+        div_int = val / 16;
+    }
+    /* Compute the real frequency we will get */
+    ret = CLOCK_CORECLOCK / (res * (div_int + (div_frac / 16)));
+
+    DEBUG("[pwm]: div_int:%d, div_frac:%d\n", div_int, div_frac);
+    /* Set the slice divider to reach the desired frequency */
+    pwm_slice(slice)->div = ((div_int << PWM_CH0_DIV_INT_Pos) | div_frac);
+
+    /* Let PWM slice run in free running mode */
+    pwm_slice(slice)->csr = PWM_CH0_CSR_DIVMODE_div;
+
+    /* Set PWM slice TOP value */
+    pwm_slice(slice)->top = res-1;
+
+    /* Enable PWM slice */
+    io_reg_atomic_set(&PWM->EN, 1 << slice);
+
+    DEBUG("[pwm]: Init done, frequency set to %ld\n", ret);
+    return ret;
+
+}
+
+uint8_t pwm_channels(pwm_t pwm)
+{
+    assert(pwm < PWM_NUMOF);
+    return PWM_CHANNEL_NUMOF;
+}
+
+void pwm_set(pwm_t pwm, uint8_t channel, uint16_t value)
+{
+    assert((pwm < PWM_NUMOF) && (channel < PWM_CHANNEL_NUMOF));
+    uint8_t slice = pwm_config[pwm].pwm_slice;
+
+    /* Set channel compare value */
+    if (channel) {
+        io_reg_write_dont_corrupt(&pwm_slice(slice)->cc,
+                                  (value << PWM_CH0_CC_B_Pos),
+                                  PWM_CH0_CC_B_Msk);
+    }
+    else {
+        io_reg_write_dont_corrupt(&pwm_slice(slice)->cc,
+                                  (value << PWM_CH0_CC_A_Pos),
+                                  PWM_CH0_CC_A_Msk);
+    }
+}
+
+void pwm_poweron(pwm_t pwm)
+{
+    assert(pwm < PWM_NUMOF);
+    uint8_t slice = pwm_config[pwm].pwm_slice;
+    io_reg_atomic_set(&PWM->EN, 1 << slice);
+}
+
+void pwm_poweroff(pwm_t pwm)
+{
+    assert(pwm < PWM_NUMOF);
+    uint8_t slice = pwm_config[pwm].pwm_slice;
+    io_reg_atomic_clear(&PWM->EN, 1 << slice);
+}

cpu/sam0_common/periph/rtc_rtt.c

@@ -330,6 +330,13 @@ static void _rtc_init(void)
     RTC->MODE2.CTRLA.reg = RTC_MODE2_CTRLA_PRESCALER_DIV1024   /* CLK_RTC_CNT = 1KHz / 1024 -> 1Hz */
                          | RTC_MODE2_CTRLA_CLOCKSYNC           /* Clock Read Synchronization Enable */
                          | RTC_MODE2_CTRLA_MODE_CLOCK;
+
+    /* RTC is all 0 after POR, avoid reading invalid date right after boot */
+    if (RTC->MODE2.CLOCK.reg == 0) {
+        RTC->MODE2.CLOCK.reg = RTC_MODE2_CLOCK_MONTH(1)
+                             | RTC_MODE2_CLOCK_DAY(1);
+    }
+
 #ifdef RTC_MODE2_CTRLB_GP2EN
     /* RTC driver does not use COMP[1] or ALARM[1] */
     /* Use second set of Compare registers as general purpose register */

cpu/sam0_common/periph/usbdev.c

@@ -191,8 +191,7 @@ static bool _ep_out_flags_set(UsbDeviceEndpoint *ep_reg)
 {
     return ep_reg->EPINTFLAG.reg  &
            ep_reg->EPINTENSET.reg &
-           (USB_DEVICE_EPINTENSET_TRFAIL0 |
-            USB_DEVICE_EPINTENSET_TRCPT0 |
+           (USB_DEVICE_EPINTENSET_TRCPT0 |
             USB_DEVICE_EPINTENSET_RXSTP |
             USB_DEVICE_EPINTENSET_STALL0);
 }
@@ -205,8 +204,7 @@ static bool _ep_in_flags_set(UsbDeviceEndpoint *ep_reg)
 {
     return ep_reg->EPINTFLAG.reg &
            ep_reg->EPINTENSET.reg &
-           (USB_DEVICE_EPINTENSET_TRFAIL1 |
-            USB_DEVICE_EPINTENSET_TRCPT1 |
+           (USB_DEVICE_EPINTENSET_TRCPT1 |
             USB_DEVICE_EPINTENSET_STALL1);
 }
 
@@ -741,10 +739,6 @@ static void _usbdev_ep_esr(usbdev_ep_t *ep)
             ep_reg->EPINTFLAG.reg = USB_DEVICE_EPINTFLAG_RXSTP;
             event = USBDEV_EVENT_TR_COMPLETE;
         }
-        else if (ep_reg->EPINTFLAG.bit.TRFAIL0) {
-            ep_reg->EPINTFLAG.reg = USB_DEVICE_EPINTFLAG_TRFAIL0;
-            event = USBDEV_EVENT_TR_FAIL;
-        }
         else if (ep_reg->EPINTFLAG.bit.STALL0) {
             ep_reg->EPINTFLAG.reg = USB_DEVICE_EPINTFLAG_STALL0;
             event = USBDEV_EVENT_TR_STALL;
@@ -760,10 +754,6 @@ static void _usbdev_ep_esr(usbdev_ep_t *ep)
             ep_reg->EPINTFLAG.reg = USB_DEVICE_EPINTFLAG_TRCPT1;
             event = USBDEV_EVENT_TR_COMPLETE;
         }
-        else if (ep_reg->EPINTFLAG.bit.TRFAIL1) {
-            ep_reg->EPINTFLAG.reg = USB_DEVICE_EPINTFLAG_TRFAIL1;
-            event = USBDEV_EVENT_TR_FAIL;
-        }
         else if (ep_reg->EPINTFLAG.bit.STALL1) {
             ep_reg->EPINTFLAG.reg = USB_DEVICE_EPINTFLAG_STALL1;
             event = USBDEV_EVENT_TR_STALL;

cpu/stm32/Makefile.dep

@@ -7,20 +7,26 @@ ifneq (,$(filter periph_usbdev,$(FEATURES_USED)))
   ifneq (,$(filter f2 f4 f7 h7 u5,$(CPU_FAM)))
     # Whole STM32 families F2, F4, F7, H7 and U5 use the Synopsys DWC2 USB OTG core
     USEMODULE += usbdev_synopsys_dwc2
+    USEMODULE += ztimer
+    USEMODULE += ztimer_msec
   else ifneq (,$(filter stm32f105% stm32f107%,$(CPU_MODEL)))
     # STM32F105xx and STM32F107xx also use the Synopsys DWC2 USB OTG core
     USEMODULE += usbdev_synopsys_dwc2
+    USEMODULE += ztimer
+    USEMODULE += ztimer_msec
   else ifneq (,$(filter stm32l47% stm32l48% stm32l49%,$(CPU_MODEL)))
     # STM32L475xx, STM32L476xx, STM32L485xx, STM32L486xx and STM32L496xx
     # also use the Synopsys DWC2 USB OTG core
     USEMODULE += usbdev_synopsys_dwc2
+    USEMODULE += ztimer
+    USEMODULE += ztimer_msec
   else ifneq (,$(filter stm32l4a% stm32l4p% stm32l4q% stm32l4r% stm32l4s%,$(CPU_MODEL)))
     # STM32L4Axxx, STM32L4Pxxx, STM32L4Qxxx, STM32L4Rxxx and STM32L4Sxxx
     # also use the Synopsys DWC2 USB OTG core
     USEMODULE += usbdev_synopsys_dwc2
+    USEMODULE += ztimer
+    USEMODULE += ztimer_msec
   endif
-  USEMODULE += ztimer
-  USEMODULE += ztimer_msec
 endif
 
 ifneq (,$(filter periph_uart_nonblocking,$(USEMODULE)))

cpu/stm32/cpu_init.c

@@ -161,6 +161,7 @@ static void _gpio_init_ain(void)
  * This very teniously avoids optimization, even optimized it's better than
  * nothing but periodic review should establish that it doesn't get optimized.
  */
+MAYBE_UNUSED
 __attribute__((always_inline))
 static inline uint32_t _multi_read_reg32(volatile uint32_t *addr, bool *glitch)
 {

cpu/stm32/periph/uart.c

@@ -332,6 +332,10 @@ static inline void uart_init_usart(uart_t uart, uint32_t baudrate)
 #define RCC_CCIPR_LPUART1SEL_0  RCC_CCIPR1_LPUART1SEL_0
 #define RCC_CCIPR_LPUART1SEL_1  RCC_CCIPR1_LPUART1SEL_1
 #define CCIPR                   CCIPR1
+#elif CPU_FAM_STM32U5
+#define RCC_CCIPR_LPUART1SEL_0  RCC_CCIPR3_LPUART1SEL_0
+#define RCC_CCIPR_LPUART1SEL_1  RCC_CCIPR3_LPUART1SEL_1
+#define CCIPR                   CCIPR3
 #endif
 #ifdef MODULE_PERIPH_LPUART
 static inline void uart_init_lpuart(uart_t uart, uint32_t baudrate)

cpu/stm32/periph/usbdev_fs.c

@@ -32,6 +32,7 @@
 #include "usbdev_stm32.h"
 #include "pm_layered.h"
 #include "ztimer.h"
+#include "busy_wait.h"
 
 #include <string.h>
 /**
@@ -218,7 +219,15 @@ static void _enable_gpio(const stm32_usbdev_fs_config_t *conf)
         gpio_init(conf->dp, GPIO_OUT);
         gpio_clear(conf->dp);
         /* wait a 1 ms */
-        ztimer_sleep(ZTIMER_MSEC, 1);
+        if (IS_USED(MODULE_ZTIMER_MSEC)) {
+            ztimer_sleep(ZTIMER_MSEC, 1);
+        }
+        else if(IS_USED(MODULE_ZTIMER_USEC)) {
+            ztimer_sleep(ZTIMER_USEC, 1 * US_PER_MS);
+        }
+        else {
+            busy_wait_us(1 * US_PER_MS);
+        }
         gpio_init(conf->dp, GPIO_IN);
     }
     if (conf->af != GPIO_AF_UNDEF) {

dist/tools/dhcpv6-pd_ia/pkg/__init__.py

@@ -27,9 +27,7 @@ __email__ = "m.lenders@fu-berlin.de"
 class PackageManagerFactory(object):
     @staticmethod
     def _get_linux_distro():
-        if hasattr(platform, "linux_distribution"):
-            return platform.linux_distribution()[0]
-        elif os.path.exists("/etc/os-release"):
+        if os.path.exists("/etc/os-release"):
             with open("/etc/os-release") as f:
                 for line in f:
                     m = re.match(r"^NAME=\"(.+)\"$", line)
@@ -42,7 +40,7 @@ class PackageManagerFactory(object):
         system = platform.system()
         if system == "Linux":
             system = cls._get_linux_distro()
-        if system in ["Debian", "Ubuntu", "Linux Mint"]:
+        if system.startswith(("Debian", "Ubuntu", "Linux Mint")):
             return Apt("Debian")
         if system in ["Arch Linux"]:
             return PacMan("Arch")

dist/tools/doccheck/exclude_simple

@@ -8423,3 +8423,4 @@ warning: Member LSM6DSXX_PARAM_ACC_FIFO_DEC (macro definition) of file lsm6dsxx_
 warning: Member LSM6DSXX_PARAM_GYRO_FIFO_DEC (macro definition) of file lsm6dsxx_params.h is not documented.
 warning: Member LSM6DSXX_PARAMS (macro definition) of file lsm6dsxx_params.h is not documented.
 warning: Member LSM6DSXX_SAUL_INFO (macro definition) of file lsm6dsxx_params.h is not documented.
+RIOTDoxygenLayout.xml:8: warning: the type 'topics' is not supported for the entry tag within a navindex! Check your layout file!

dist/tools/insufficient_memory/create_makefile.ci.sh

@@ -57,6 +57,7 @@ for BOARD in $(EXTERNAL_BOARD_DIRS="" make  --no-print-directory info-boards-sup
                 -e "not within region" \
                 -e "wraps around address space" \
                 -e "overlaps section" \
+                -e "does not fit in ROM" \
                 "$TMPFILE" > /dev/null; then
             printf "${CBIG}%s${CRESET}\n" "too big"
             BOARDS="${BOARDS} ${BOARD}"

doc/doxygen/RIOTDoxygenLayout.xml

@@ -5,6 +5,7 @@
     <tab type="mainpage" visible="yes" title=""/>
     <tab type="pages" visible="yes" title="" intro=""/>
     <tab type="user" url="@ref boards" title="Supported Boards"/>
+    <tab type="topics" visible="yes" title="" intro=""/>
     <tab type="modules" visible="yes" title="" intro=""/>
     <tab type="namespaces" visible="yes" title="">
       <tab type="namespacelist" visible="yes" title="" intro=""/>

doc/doxygen/riot.doxyfile

@@ -759,6 +759,7 @@ INPUT                  = ../../doc.txt \
                          ../../sys \
                          src/ \
                          src/mainpage.md \
+                         src/vision.md \
                          src/roadmap.md \
                          src/creating-modules.md \
                          src/creating-an-application.md \

doc/doxygen/src/getting-started.md

@@ -34,7 +34,12 @@ will also be fine - however, we rely on users to report bugs regarding tooling i
 here. So expect occasional issues for the development branch and please help testing during the
 feature freeze period, if you develop on macOS or BSD.
 
-Native development on Windows and macOS machines is not officially supported. What works well is using Linux
+Windows users can refer to [this guide][dev-setup-windows] to
+[setup the development environment][dev-setup-windows] on Windows.
+
+[dev-setup-windows]: https://github.com/RIOT-OS/RIOT/tree/master/doc/guides/setup-windows
+
+Native development on macOS machines is not officially supported. What works well is using Linux
 in a virtual machine, but at much lower performance than running Linux natively. We also offer Docker images.
 For development on Windows, using the
 [Windows Subsystem for Linux (WSL)](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)

doc/doxygen/src/mainpage.md

@@ -38,7 +38,7 @@ RIOT is developed by an open community that anyone is welcome to join:
  - Sign-up to our [forum](https://forum.riot-os.org/) to ask for help using RIOT
    or writing an application for RIOT, discuss kernel and network stack
    development as well as hardware support, or to show-case your latest project.
- - Follow us on [Twitter](https://twitter.com/RIOT_OS) for news from the RIOT
+ - Follow us on [Mastodon][mastodon-link] for news from the RIOT
    community.
  - Regarding critical vulnerabilities we would appreciate if you give us a
    90-days head-start by reporting to security@riot-os.org, before making your
@@ -46,6 +46,7 @@ RIOT is developed by an open community that anyone is welcome to join:
  - Contact us on Matrix for live support and discussions:
    [riot-os:matrix.org](https://matrix.to/#/#riot-os:matrix.org)
 
+[mastodon-link]: https://fosstodon.org/@RIOT_OS
 
 The quickest start                                        {#the-quickest-start}
 ==================

doc/doxygen/src/vision.md

@@ -0,0 +1,53 @@
+# RIOT Vision     {#vision}
+
+We expect an evolution in the software platforms powering Internet of Things
+devices that can be compared, to some extent, to the recent evolution of
+software platforms powering smartphones.
+
+In a few years time, software platforms powering smart handheld devices has
+speed-evolved from a state where dozens of closed-source, slow progress,
+proprietary solutions where used, to a state where a couple of major players
+have imposed new de facto standards in terms of software platform openness,
+interoperability, and automatic updating. On the bright side, this has led to
+much quicker paced progress, and to the development of billions of new
+applications built on top of these platforms, which interact in innovative ways
+with one another and with the cloud. At this point, let's make two remarks about
+the dark side of this evolution. First, while companies pushing iOS and Android
+use such software platforms as more tools to achieve profit-oriented goals
+(e.g., accumulating and monetizing personalized information), RIOT is developed
+and maintained by a non-profit, open source community of developers organized
+around principles that are mainly inspired by the Linux community or the IETF
+community. Second, while the true level of openness of iOS or Android is debatable,
+RIOT aims instead at a Linux-like openness.
+
+That said, we expect a revolution in the software platforms powering Internet of
+Things (IoT) devices, and we expect this revolution to be as game-changing as
+the aforementioned evolution of the software platforms powering smart handheld
+devices (retaining only its bright side, hopefully). It is yet unclear which IoT
+software platforms will emerge as dominant -- RIOT is a contender. It is however
+quite likely that new standards will be set in the near future, in terms of IoT
+software platform openness, API, automated software updates and other
+characteristics that are necessary to enable a modern, large scale, secure ecosystem.
+Such an IoT software evolution will quite likely fuel a new world of distributed
+applications developed by a large variety of actors, on top of the dominant open
+software platform(s). These applications will leverage both spontaneous wireless
+networks, the cloud and the denser, interconnected environment of heterogeneous
+devices that we will find ourselves in.
+
+Our vision is the emergence of an entirely new reality in which our interface to
+the Internet will no longer be predominantly a screen, but rather the objects of
+the cyber-physical system embodied by the Internet of Things itself. RIOT is an
+open source operating system that aims to power IoT devices in this new reality.
+RIOT aims to provide a powerful, but very low memory footprint software platform,
+that enables any programmer to develop applications on typical IoT devices with
+zero learning curve (assuming prior experience with POSIX and Linux for instance).
+RIOT aims for shortened development life-cycles, using standard languages, and
+well-known debugging tools. RIOT implements a micro-kernel architecture that provides
+built-in robustness, real-time capabilities and energy efficiency -- future-proof
+properties, required by many IoT applications to come.
+
+In this context RIOT aims to power a modern, large scale, evolutive, and secure
+cyber-physical ecosystem, comprising of heterogeneous IoT devices, distributed
+processes and applications, that can seamlessly interconnect with one another
+and with the cloud, leveraging standard network stacks (including IPv6
+interoperability) available in RIOT.

doc/guides/setup-windows/README.md

@@ -0,0 +1,496 @@
+# Getting Started on Windows
+
+> [!NOTE]
+> The documentation is quite verbose: The process is documented down to every
+> click. Because of this verbosity the setup may appear complex and long, but
+> in fact is rather straight forward. A novice user should be able to complete
+> all steps in less than 30 minutes.
+
+> [!NOTE]
+> Do not be afraid to ask for help e.g. in [our forum][riot-forum]
+
+[riot-forum]: https://forum.riot-os.org/
+
+## Install Ubuntu LTS
+
+![Searching Ubuntu LTS in the Windows Store](img/00-Install_Ubuntu-00.png)
+
+1. Open the Windows Store
+2. Type "Ubuntu LTS" in the search bar
+3. Click on the most recent version (highest number) of Ubuntu LTS found.
+   As of February 2024, this is version Ubuntu 22.04.3 LTS.
+
+![The Ubuntu LTS page in the Windows Store](img/00-Install_Ubuntu-01.png)
+
+1. Click on the button labeled "Get"
+
+
+![The Windows Store App is installing Ubuntu LTS](img/00-Install_Ubuntu-02.png)
+
+It will take a while for Ubuntu LTS to be installed.
+
+![The Windows Store App has completed installing Ubuntu LTS](img/00-Install_Ubuntu-03.png)
+
+Eventually, the installation completes.
+
+1. Click on the button labeled "Open"
+
+> [!WARNING]
+> If the Windows Subsystem for Linux (WSL) has not yet been enabled, an error
+> such as below will show. Not to worry, the next section got you covered.
+
+![Error message because WSL is not enabled](img/00-Install_Ubuntu-04.png)
+
+## Enabling WSL
+
+> [!NOTE]
+> If an Ubuntu terminal opened just fine, proceed directly to the next section.
+> This section will show how to enable WSL for those who hit the error.
+
+![Opening the PowerShell as administrator](img/01-Install_WSL-00.png)
+
+1. Search for "powershell" in the search field of the task bar
+2. ***Right***-click on the hit "Windows PowerShell"
+3. Click "Run as administrator"
+
+![Prompt asking for confirmation to run PowerShell as admin](img/01-Install_WSL-01.png)
+
+1. Click "Yes" to confirm running the PowerShell as administrator
+
+![PowerShell terminal opened as administrator](img/01-Install_WSL-02.png)
+
+- Type `wsl --install` and confirm with the return-key.
+- After a while, the following message should appear:
+
+![PowerShell after WSL has been enabled](img/01-Install_WSL-03.png)
+
+- Now reboot Windows to complete the installation
+
+![Windows installing WSL during reboot](img/01-Install_WSL-04.png)
+
+The reboot will take longer than usual due to the installation of WSL. You
+may see a screen like above for some time. Once the reboot is completed,
+an Ubuntu terminal should open automatically.
+
+## Setup Ubuntu LTS
+
+You should now see an Ubuntu terminal such as:
+
+![An Ubuntu terminal when first started](img/02-Setup_Ubuntu-00.png)
+
+<details><summary>If no Ubuntu terminal has opened, click here to see how to open it</summary>
+
+![Open Ubuntu in the start menu](img/02-Setup_Ubuntu-01.png)
+
+1. Click on the Start / Windows button in the task bar
+2. Click on the "Ubuntu" entry
+
+</details>
+
+- Enter a user name of your choice, memorize it, and confirm with the return-key
+- Enter a password of your choice, memorize it, and confirm with the return-key
+- Repeat the password and confirm with the return-key
+
+> [!WARNING]
+> When typing passwords in the Ubuntu terminal, the chars entered will not
+> appear on the screen and neither will appear `*`. You will have to type
+> "blindly". This is an intentional security feature.
+
+> [!NOTE]
+> If you fail to repeat the password correctly, the setup will just again. So
+> no need to worry.
+
+- Once you successfully have entered user name and password, you should see
+  something like this:
+
+![Ubuntu terminal after username and password are configured](img/02-Setup_Ubuntu-02.png)
+
+- now type (without quotation signs) "sudo apt update" and confirm with the return-key
+- you will be asked for you password. Enter it and confirm with the return key
+
+> [!WARNING]
+> When typing the password, you will no get any visible feedback such as the
+> typed password or `*` chars. This is an intentional security feature.
+
+- Once you successfully entered the password, something like this will show up:
+
+![Ubuntu terminal after running apt update](img/02-Setup_Ubuntu-03.png)
+
+> [!NOTE]
+> The command `sudo apt update` only updates the list of available software
+> packages in Ubuntu. Updating the installed software requires to additionally
+> run `sudo apt upgrade`
+
+- Now type `sudo apt upgrade` and confirm with the return-key
+
+> [!NOTE]
+> This time you likely will not need to confirm with your password again. The
+> `sudo` command that allows you to run administrative commands such as
+> `apt update` will skip the password entry, when heuristics indicate that
+> you have not left your machine since you last confirmed a command with your
+> password.
+
+- This command will list which packages are about to be updated. Confirm with
+  with the return-key
+- Eventually after all software packages in Ubuntu have been updated, you will
+  see something like this:
+
+![Ubuntu terminal after updating software](img/02-Setup_Ubuntu-05.png)
+
+
+> [!NOTE]
+> It is recommended to regularly update the installed software in Ubuntu
+> using `sudo apt update` followed by `sudo apt upgrade`
+
+## Installation of the required software packages in Ubuntu
+
+- Now, install the required software by typing the following and confirming it
+  with a return-key
+
+```
+sudo apt install make gcc-multilib python3-serial wget unzip git openocd gdb-multiarch esptool podman-docker clangd clang
+```
+
+- This will show something like this:
+
+![Ubuntu terminal waiting for confirmation for installation](img/03-Install_Base_Packages-01.png)
+
+- Confirm the installation by hitting the return-key
+- The installation process will take some time
+- Eventually the output will look like below (except for the `exit`)
+
+![Ubuntu terminal after installation completed](img/03-Install_Base_Packages-02.png)
+
+- Type `exit` and confirm with the return-key to close the Ubuntu terminal
+- The window should close
+
+## Installing VS Code
+
+![Windows Store page of VS Code](img/04-Install_VS_Code-00.png)
+
+1. Click on the Windows Store icon to open the Windows store
+2. Type `vs code` in the search bar
+3. Click on the "Visual Studio Code by Microsoft Corporation" search result
+   (not shown in the screenshot above)
+4. In the Windows Store page of VS Code (as shown in the screenshot above),
+   click on the button labeled "Install"
+
+![Windows Store installing VS Code](img/04-Install_VS_Code-01.png)
+
+- Downloading and installing VS Code by the Store App may take some time
+- Eventually, it should show something like this:
+
+![Windows Store completed installing VS Code](img/04-Install_VS_Code-02.png)
+
+- Now, launch VS Code via the start menu
+- On the first launch, VS code will look similar to this:
+
+![First Launch page of VS Code](img/04-Install_VS_Code-03.png)
+
+- You can select a theme of you liking
+- You might want to dial back the data collection by Microsoft by clicking on "opt out"
+
+![Installation of the WSL extension for VS Code](img/04-Install_VS_Code-04.png)
+
+1. Open the extension marketplace by clicking on the extensions icon in the
+   left menu bar
+2. Search for `wsl` in the search field
+3. Click on the "Install" button for the "WSL" extension by "Microsoft"
+
+> [!NOTE]
+> The installation of the WSL extension will complete the next time you open
+> Ubuntu terminal. If the Ubuntu terminal was still open, close it using the
+> `exit` comment and launch it again.
+
+## Cloning the RIOT Repository and First Steps in the Terminal
+
+> [!NOTE]
+> Even if you subsequently work only via VS Code, do **NOT** skip this step.
+> You will still need a "clone" of the RIOT Repository to work with.
+
+![Cloning of the RIOT Repo in the Ubuntu terminal](img/05-First_Steps-00.png)
+
+- Open the Ubuntu terminal.
+- (It may show some output regarding the VS Code WSL extension being installed.
+  Just wait for this to complete.)
+- Type `git clone https://github.com/RIOT-OS/RIOT` and confirm with the return-key
+- This may take some time. Eventually, it will print `done.` when it completed
+- Type `cd RIOT/examples/hello-world` and confirm with the return-key to enter
+  the folder `hello-world` example app in the RIOT repo
+- Type `make` and confirm with the return key to build the app for the board
+  `native`
+
+> [!NOTE]
+> The `native` board is a virtual board that will run an RIOT application as
+> regular Linux process. This can be useful for testing or during development.
+> The app should behave the same when run on real hardware.
+
+![The `hello-world` app running on the virtual `native` board](img/05-First_Steps-01.png)
+
+- Now run the application by executing `make term`
+- The output should look similar to the screenshot above
+- You can close the terminal by:
+    1. Press and hold the `Ctrl`-key
+    2. With the `Ctrl`-key still held, press the `C`-key
+    3. Release both keys
+
+## Using VS Code for Development
+
+![Ubuntu terminal running `make compile-commands` in the `hello-world` app](img/06-Use_VS_Code-00.png)
+
+- If not already open, open the Ubuntu terminal
+- Confirm that the terminal is pointed to the folder `~/RIOT/examples/hello-world`
+    - The blue part left of the prompt (the `$` sign in the terminal) shows
+      the current working directory for the terminal
+    - If the blue string is not `~/RIOT/examples/hello-world`, type
+      `cd ~/RIOT/examples/hello-world` to enter that path
+- Inside `~/RIOT/examples/hello-world` run the command `make compile-commands`
+- The output should look like above
+
+![Launching VS Code from Ubuntu](img/06-Use_VS_Code-01.png)
+
+- Navigate back to `~/RIOT` using the command `cd ~/RIOT`
+- run `code .` to launch VS Code
+    - This will take a bit longer on the first launch
+- Eventually, a VS Code Window should pop up that looks like this:
+
+![VS Code as opened from WSL](img/06-Use_VS_Code-02.png)
+
+1. Click on "Yes, I trust the authors"
+
+- Now, use the tree view in the left and open the `examples` folder
+- Open the `hello-world` folder inside the `examples` folder
+- Open the `main.c` file in the `hello-world` folder within `examples`
+- The file should open and look like this:
+
+![VS Code asking to install C/C++ Extension](img/06-Use_VS_Code-03.png)
+
+1. Click on the "Install" button when prompted to install the C/C++ Extension.
+
+> [!NOTE]
+> You can also install that extension via the extension marketplace just like
+> the WSL extension was installed, if that pop up does not show up.
+
+![VS Code asking to configure RIOT as CMake project](img/06-Use_VS_Code-04.png)
+
+> [!WARNING]
+> Do **NOT** configure RIOT as CMake project. VS Code will incorrectly detect
+> RIOT as CMake project, because it contains external packages that indeed are
+> using CMake.
+
+1. Click on "Not now" to not configure RIOT as CMake project
+2. Click on "Never" to never ask again whether RIOT should be configured as
+   CMake project (not shown in screenshot)
+
+![IntelliSense showing that `RIOT_BOARD` is `"native"`](img/06-Use_VS_Code-05.png)
+
+- Confirm that when hovering over `RIOT_BOARD` in the source code, IntelliSense
+  shows that it expands to `"native"`.
+
+> [!NOTE]
+> IntelliSense depends on information how to compile the source code to work
+> correctly, which is provided in the file `compile_commands.json`. You can
+> regenerate this file by running `make compile-commands` in the app you are
+> working on.
+
+> [!WARNING]
+> Re-run `make compile-commands` when:
+> 1. You create, delete or rename source files
+> 2. You change the set of modules or packages used
+> 3. You have updated the RIOT repository
+> 4. You are switching the board to compile for
+
+
+![Compiling via the Terminal in VS Code](img/06-Use_VS_Code-06.png)
+
+- Extend the message to be printed, e.g. by adding a `puts("...");` statement
+  in the source code
+- Save the modified source code (e.g. `Ctrl`+`S`)
+- Open the integrated terminal by clicking on the terminal tab at the bottom
+- Navigate to `~/RIOT/examples/hello-world` using `cd ~/RIOT/examples/hello-world`
+- Run the `make` command to build the code
+- Run make `make term` to launch the application
+- The result should look like:
+
+![Running the app in VS Code](img/06-Use_VS_Code-07.png)
+
+Congratulations! You just compiled your first RIOT application. To run RIOT
+on real hardware, proceed with the next to sections.
+
+## Installing `usbipd-win`
+
+![Release Page of usbipd-win](img/07-Install_USBIPd-01.png)
+
+0. Open the [release page of `usbipd-win`][usbipd-win-releases]
+1. Download the installer (file extension `.msi`) of the most recent release
+
+[usbipd-win-releases]: https://github.com/dorssel/usbipd-win/releases
+
+![Download of usbipd-win completed](img/07-Install_USBIPd-02.png)
+
+Once the download is completed:
+
+1. Open the downloaded installer
+
+![Confirmation to open the installer](img/07-Install_USBIPd-03.png)
+
+1. Confirm that you indeed want to execute the installer by clicking "OK".
+
+![Setup of usbipd-win](img/07-Install_USBIPd-04.png)
+
+The setup of `usbipd-win` opens.
+
+1. Click on the "Install" button to proceed with the installation.
+
+![Confirmation of installation](img/07-Install_USBIPd-05.png)
+
+1. Confirm the installation by clicking on "Yes".
+
+![Completion of the usbipd-win setup](img/07-Install_USBIPd-06.png)
+
+Eventually, the setup will inform you of the completion of the installation.
+
+1. Click the "Close" button to acknowledge.
+
+## Attach a USB device to WSL
+
+> [!NOTE]
+> Attaching a USB device to WSL needs to be repeated after any of the following
+> happens:
+>
+> 1. Windows has been restarted (or hibernated)
+> 2. WSL (the Ubuntu terminal window) has been restarted
+> 3. The USB device has been lost (e.g. unplugging and plugging back in)
+
+> [!NOTE]
+> You do not need to install the Windows USB drivers, Linux will use its own
+> anyway. All supported board run on Linux out of the box without the need of
+> drivers to be installed.
+
+![Running PowerShell as admin](img/08-Flash_Real_Hardware-00.png)
+
+1. Search for `powershell` in search field in the task bar
+2. ***Right***-click on the search result "Windows PowerShell"
+3. Select "Run as administrator"
+
+![Confirmation to run PowerShell as admin](img/08-Flash_Real_Hardware-01.png)
+
+1. Click on "Yes" to confirm running the PowerShell as admin
+
+![PowerShell terminal](img/08-Flash_Real_Hardware-02.png)
+
+1. Type the command `usbipd list` and confirm with the return-key
+2. Identify the USB device to share. In this guide we use an ESP32 development
+   board, which almost all use an USB to UART bridge (here the CP2104).
+3. Run `usbipd bin --busid <BUSID>`, but replace `<BUSID>` with the correct
+   BUSID. E.g. `2-5` for the CP2104 identified in step 2.
+4. Run `usbipd attach --wsl --busid <BUSID>`
+    - If an error (such as above in red) is shown that WSL is not running, just
+      start the Ubuntu terminal now and repeat (step 5.). If it worked the first
+      time, no need to run it again.
+
+> [!NOTE]
+> If you have trouble identifying the USB device to attach, unplug before
+> running `usbipd list`. Run it again with the USB device plugged in. The new
+> entry in the list is the device you want to attach to WSL.
+
+## Flash an ESP32 Development Board
+
+After all of the previous sections are completed, we can finally flash some
+real hardware. In this case, we use an `esp32-mh-et-live-minikit` development
+board. The guide should mostly apply to all other boards as well.
+
+> [!NOTE]
+> Some boards require extra steps to be flashed, such as pressing a button
+> to enter a bootloader or attaching an external programmer. Refer to the
+> documentation of the board to check if extra steps are required.
+
+This assumes that the USB UART bridge of the ESP32 development board has
+been attached to WSL and VS Code has been launched from within WSL by running
+`code .` inside the RIOT repository from the Ubuntu terminal.
+
+![VS Code in WSL](img/08-Flash_Real_Hardware-03.png)
+
+1. Open the `examples` folder
+2. Open the `default` folder within `examples`
+3. Open the `main.c` file in the `default` folder
+4. Select the "Terminal" tab at the bottom
+5. Enter `cd ~/RIOT/examples/default` to enter the `default` folder also in the terminal
+6. Run `make BOARD=esp32-mh-et-live-minikit compile-commands`
+    - You can replace `esp32-mh-et-live-minikit` with the name of any other supported board
+
+> [!NOTE]
+> Did you notice that IntelliSense did not find headers in `main.c` when you
+> opened it? This should be fixed after the command in 6 has completed.
+
+![Flashing from VS Code](img/08-Flash_Real_Hardware-04.png)
+
+1. Now run `make BOARD=esp32-mh-et-live-minikit BUILD_IN_DOCKER=1 flash term`
+
+> [!NOTE]
+> Tired of typing `BOARD=<NAME_OF_THE_BOARD>` and `BUILD_IN_DOCKER=1`? You can
+> add those to the `Makefile` of your app or run
+> `export BOARD=BUILD_IN_DOCKER=1` in the shell. The `export` will not persist
+> needs to be repeated for every new terminal window.
+
+![Pulling docker image](img/08-Flash_Real_Hardware-05.png)
+
+When compiling with `BUILD_IN_DOCKER=1`, the toolchains distributed in the
+[`riot/riotbuild`](https://hub.docker.com/r/riot/riotbuild/) docker image will
+be used for compilation. This image contains toolchains for all supported RIOT
+board and is extensively tested in our CI.
+
+The first time you build with `BUILD_IN_DOCKER=1`, the image is pulled
+automatically.
+
+![Still pulling docker image](img/08-Flash_Real_Hardware-06.png)
+
+This may take a while ...
+
+![Building the firmware](img/08-Flash_Real_Hardware-07.png)
+
+... until eventually the docker image is pulled and the build will start.
+Subsequent builds will no longer need to download the toolchain and be a lot
+quicker.
+
+![Interacting with the firmware](img/08-Flash_Real_Hardware-08.png)
+
+After building and flashing the firmware has succeeded, a shell will open.
+
+1. Wait for the boot message to appear.
+    - The board may boot faster than your PC is able to connect to the serial.
+      If you see nothing after "Welcome to pyterm!" for 5 seconds, try hitting
+      the reset button on the board to boot it again.
+2. You are now connected to the RIOT shell running on the board. Try running
+   the `help` command to get a list of commands supported by the board.
+3. You can drop out of the RIOT serial by pressing `Ctrl` + `C` and return
+   to the Linux shell.
+
+## Known Issues
+
+### Flashing Fails with Programmers using HID
+
+The Linux Kernel in WSL currently has
+[`CONFIG_USB_HIDDEV` disabled][wsl-hid-issue]. Hence, programmers using HID
+as transport do not work for now. The (non-conclusive) list of affected
+programmers is:
+
+- Atmel/Microchip eDBG
+- Atmel/Microchip ICE
+- Any ARM CMSIS DAP compatible programmers
+
+> [!NOTE]
+> It is possible to install a native Windows flash application and invoke that
+> from within WSL.
+
+The (non-conclusive) list of programmers that work with WSL out of the box is:
+
+- ST-Link (any version), including [cheap clones](https://www.aliexpress.com/wholesale?SearchText=ST-Link+V2)
+- Segger J-Link, including the [J-Link EDU Mini](https://www.segger.com/products/debug-probes/j-link/models/j-link-edu-mini/)
+- Any serial based bootloader (e.g. ESP boards, Arduino Bootloaders, ...)
+- [Black Magic Probe](https://black-magic.org)
+- [Jeff Probe](https://flirc.com/more/flirc-jeff-probe-bmp-jtag-black-magic-probe)
+- Any other non HID USB programmer
+
+
+[wsl-hid-issue]: https://github.com/microsoft/WSL/issues/10581