Merge #19606 #19753 #19757

19606: doc: add board selection guide r=benpicco a=maribu

### Contribution description

This adds a board selection guide to the documentation to aid new users picking good hardware for their use case.


19753: cpu/atmega8: new cpu r=benpicco a=hugueslarrive

### Contribution description
Splitted from:
- #19740

### Testing procedure
Tested on atmega8 with:
- #19755

### Issues/PRs references

Dependencies:
- #19752
- #19751


19757: core: fix null pointer dereference r=benpicco a=szsam

Check return values of following functions for null:
  - thread_get
  - thread_get_unchecked



Co-authored-by: Marian Buschsieweke <[email protected]>
Co-authored-by: Hugues Larrive <[email protected]>
Co-authored-by: Mingjie Shen <[email protected]>

Author: 4 people

boards/doc.txt

@@ -17,6 +17,68 @@
  * device drivers should go into this module.
  *
 
+Board Selection Guide {#board-selection-guide}
+=====================
+
+There is no single best board to buy for use with RIOT, as hardware design
+involves many trade-offs. The challenge is to clearly assess the use case and
+collect the requirements and to find the best match for those.
+
+With this in mind, it is still possible to give some hints and recommendations:
+
+1. During Development:
+    - An integrated programmer/debugger is immensely useful. At the very least
+      a standard JTAG/SWD connector for quick and fool-proof connection is
+      required
+    - If possible, pick an MCU with *more* RAM and flash than your target board.
+      This allows to spend the excess in memory for debug features such as
+      utility modules, verbose assert messages, etc. during development
+    - Standard connectors such as Arduino Headers, or Grove, STEMMA, STEMMA QT,
+      QUIIC connectors etc. make hardware prototyping easier
+2. Final Product:
+    - An integrated programmer/debugger is a waste of resources (money, power,
+      space, ...)
+    - ...
+
+Popular Boards
+--------------
+
+| Board                                 | Use Case              | Performance   | Integrated Debugger   | Integrated Networking             | Native USB    | Arduino Headers       | Other Connectors          | Integrated Sensors/...                                | Breadboard Friendly   | Costs     | Remarks                       |
+|:------------------------------------- |:--------------------- |:------------- |:--------------------- |:--------------------------------- |:------------- |:--------------------- |:------------------------- |:----------------------------------------------------- |:--------------------- |:--------- |:----------------------------- |
+| @ref boards_arduino-due               | Education             | `++`          | ✔                     | ✗                                 | ✔             | `+++` (Uno, Mega, ISP)| ✗                         | `-` (1 LED)                                           | `+`                   | `o`       | Better buy the nrf52840dk     |
+| @ref boards_arduino-mega2560          | You have them anyway  | `--`          | ✗                     | ✗                                 | ✗             | `+++` (Uno, Mega, ISP)| ✗                         | `-` (1 LED)                                           | `+`                   | `--`      | Better buy the nrf52840dk     |
+| @ref boards_arduino-uno               | You have them anyway  | `---`         | ✗                     | ✗                                 | ✗             | `++` (Uno, ISP)       | ✗                         | `-` (1 LED)                                           | `+`                   | `--`      | You like pain, don't you?     |
+| @ref boards_common_nucleo32           | Development           | `-/o/+/++`    | ✔                     | ✗                                 | ✗             | `o` (Nano)            | Custom                    | `o` (1 button, 1 LED)                                 | `+`                   | `++`      | Good bang for the buck        |
+| @ref boards_common_nucleo64           | Development           | `o/+/++`      | ✔                     | ✗                                 | ✗             | `+` (Uno)             | ST Morpho Headers         | `o` (1 button, 1 LED)                                 | `+`                   | `++`      | Good bang for the buck        |
+| @ref boards_common_nucleo144          | Development           | `+/++/+++`    | ✔                     | (✔) (some have Ethernet)          | ✔             | `++` (Uno, Mega)      | ST Morpho Headers         | `+` (1 button, 3 LEDs)                                | `+`                   | `++`      | Good bang for the buck        |
+| @ref boards_esp32_esp-ethernet-kit    | Development           | `+++`         | ✔                     | ✔ (WiFi, BLE, Ethernet, custom)   | ✗             | ✗                     | Custom                    | `-` (1 button)                                        | `+`                   | `o`       | Requires proprietary software |
+| @ref boards_esp32_wroom-32            | Prototyping           | `+++`         | ✗                     | ✔ (WiFi, BLE, custom)             | ✗             | ✗                     | Custom                    | `-` (1 button)                                        | `+++`                 | `+++`     | Requires proprietary software |
+| @ref boards_microbit_v2               | Education             | `++`          | ✔                     | ✔ (802.15.4, BLE, custom)         | ✗             | ✗                     | micro:bit edge connector  | `+++` (6 buttons, LED matrix, mic, speaker, IMO)      | `--`                  | `++`      | Good education board          |
+| @ref boards_nrf52840dk                | Development           | `++`          | ✔                     | ✔ (802.15.4, BLE, custom)         | ✔             | `+++`(Uno, Mega)      | Custom                    | `+` (4 buttons, 4 LEDs)                               | `+`                   | `+`       | Excellent border router       |
+| @ref boards_nrf52840dongle            | Prototyping           | `++`          | ✗                     | ✔ (802.15.4, BLE, custom)         | ✔             | ✗                     | Custom                    |  o  (1 button, 4 LEDs)                                | `++`                  | `++`      | Good wireless dev board       |
+| @ref boards_nucleo-wl55jc             | Development           | `++`          | ✔                     | ✔ (LoRa)                          | ✗             | `+` (Uno)             | ST Morpho Headers         | `+` (3 buttons, 3 LEDs)                               | `+`                   | `++`      | Good bang for the buck        |
+| @ref boards_pinetime                  | Gadget                | `++`          | ✗                     | ✔ (BLE)                           | ✗             | ✗                     | ✗                         | `+++` (LCD, button, touch screen, IMU, flash, ...)    | `---`                 | `+++`     | Buy two: One with SWD access  |
+| @ref boards_samr21-xpro               | Development           | `+`           | ✔                     | ✔ (802.15.4)                      | ✔             | ✗                     | XPRO Expansion Header     | `o` (1 button, 1 LED)                                 | `+`                   | `--`      | Quite expensive               |
+| @ref boards_samr34-xpro               | Development           | `++`          | ✔                     | ✔ (LoRa)                          | ✔             | ✗                     | XPRO Expansion Header     | `o` (1 button, 2 LEDs)                                | `+`                   | `---`     | Got a spare kidney to sell?   |
+| @ref boards_weact-f411ce              | Prototyping           | `++`          | ✗                     | ✗                                 | ✔             | ✗                     | Custom                    | `+` (1 button, 1 LED, SPI flash)                      | `+++`                 | `+++`     | Excellent bang for the buck   |
+
+@note       Only boards with mature RIOT support and decent documentation qualify for above list
+@details    This list was last updated in May 2023
+
+
+<!-- Add when doc is fixed
+| @ref boards_b-l072z-lrwan1            | Development           | `+`           | ✔                     | ✔ (LoRa)                          | ✗             | `++` (Uno, Mega)      | ST Morpho Headers         | `+` (1 button, 4 LEDs)                                | `+`                   | `++`      | Good bang for the buck        |
+-->
+
+### Notes on Arduino Compatibility
+
+- Perfect (`+++`) only if it is fully compatible with both Arduino Uno and Arduino Mega Shields (including SPI via ISP connector)
+- Good (`++`) if it is fully compatible with Arduino Uno shields (including SPI via ISP connector)
+- Good (`++`) if it is partially compatible with both Arduino Uno and Arduino Mega Shields (no SPI via ISP connector)
+- Decent (`+`) if it is partially compatible with Arduino Uno Shields (no SPI via ISP connector)
+- Decent (`+`) if it is fully compatible with Arduino Nano Shields (including SPI via ISP connector)
+- OK (`o`) if it is partially compatible with Arduino Nano Shields
+
 Guide to board pinouts {#pinout_guide}
 =====================================
 

core/msg.c

@@ -322,6 +322,9 @@ int msg_reply_int(msg_t *m, msg_t *reply)
 {
     thread_t *target = thread_get_unchecked(m->sender_pid);
 
+    /* msg_reply_int() can only be used to reply to existing threads */
+    assert(target != NULL);
+
     if (target->status != STATUS_REPLY_BLOCKED) {
         DEBUG("msg_reply_int(): %" PRIkernel_pid ": Target \"%" PRIkernel_pid
               "\" not waiting for reply.", thread_getpid(),
@@ -466,6 +469,9 @@ unsigned msg_queue_capacity(kernel_pid_t pid)
           pid);
 
     thread_t *thread = thread_get(pid);
+
+    assert(thread != NULL);
+
     int queue_cap = 0;
 
     if (thread_has_msg_queue(thread)) {

cpu/atmega8/Kconfig

@@ -0,0 +1,34 @@
+# Copyright (c) 2020 HAW Hamburg
+#
+# 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.
+#
+
+config CPU_FAM_ATMEGA8
+    bool
+    select CPU_COMMON_ATMEGA
+
+## CPU Models
+config CPU_MODEL_ATMEGA8
+    bool
+    select CPU_FAM_ATMEGA8
+    select HAS_CPU_ATMEGA8
+
+## Definition of specific features
+config HAS_CPU_ATMEGA8
+    bool
+    help
+        Indicates that a 'atmega8' cpu is being used.
+
+## Common CPU symbols
+config CPU_FAM
+    default "atmega8" if CPU_FAM_ATMEGA8
+
+config CPU_MODEL
+    default "atmega8" if CPU_MODEL_ATMEGA8
+
+config CPU
+    default "atmega8" if CPU_FAM_ATMEGA8
+
+source "$(RIOTCPU)/atmega_common/Kconfig"

cpu/atmega8/Makefile

@@ -0,0 +1,7 @@
+# define the module that is build
+MODULE = cpu
+
+# add a list of subdirectories, that should also be build
+DIRS = $(RIOTCPU)/atmega_common/
+
+include $(RIOTBASE)/Makefile.base

cpu/atmega8/Makefile.dep

@@ -0,0 +1 @@
+include $(RIOTCPU)/atmega_common/Makefile.dep

cpu/atmega8/Makefile.features

@@ -0,0 +1 @@
+include $(RIOTCPU)/atmega_common/Makefile.features

cpu/atmega8/Makefile.include

@@ -0,0 +1,7 @@
+RAM_LEN = 1K
+ROM_LEN = 8K
+
+LINKER_SCRIPT ?= avr4.ld
+
+# CPU depends on the atmega common module, so include it
+include $(RIOTCPU)/atmega_common/Makefile.include

cpu/atmega8/doc.txt

@@ -0,0 +1,10 @@
+/**
+ * @defgroup        cpu_atmega8 Atmel ATmega8
+ * @ingroup         cpu
+ * @brief           Implementation of Atmel's ATmega8 MCU
+ */
+
+/**
+ * @defgroup        cpu_atmega8_definitions Atmel ATmega8 Definitions
+ * @ingroup         cpu_atmega8
+ */

cpu/atmega8/include/cpu_conf.h

@@ -0,0 +1,93 @@
+/*
+ * Copyright (C) 2014 Freie Universität Berlin, Hinnerk van Bruinehsen
+ *               2017 RWTH Aachen, Josua Arndt
+ *               2018 Matthew Blue
+ *               2023 Hugues Larrive
+ *
+ * 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_atmega_common
+ * @{
+ *
+ * @file
+ * @brief           Implementation specific CPU configuration options
+ *
+ * @author          Hauke Petersen <[email protected]>
+ * @author          Hinnerk van Bruinehsen <[email protected]>
+ * @author          Josua Arndt <[email protected]>
+ * @author          Steffen Robertz <[email protected]>
+ * @author          Matthew Blue <[email protected]>
+ * @author          Hugues Larrive <[email protected]>
+ */
+
+#ifndef CPU_CONF_H
+#define CPU_CONF_H
+
+#include "atmega_regs_common.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef THREAD_EXTRA_STACKSIZE_PRINTF
+#define THREAD_EXTRA_STACKSIZE_PRINTF    (64)
+#endif
+
+/**
+ * @name           Kernel configuration
+ *
+ *                 Since printf seems to get memory allocated by the
+ *                 linker/avr-libc the stack size tested successfully
+ *                 even with pretty small stacks.
+ * @{
+ */
+#ifndef THREAD_STACKSIZE_DEFAULT
+#define THREAD_STACKSIZE_DEFAULT   (128)
+#endif
+
+/* keep THREAD_STACKSIZE_IDLE > THREAD_EXTRA_STACKSIZE_PRINTF
+ * to avoid not printing of debug in interrupts
+ */
+#ifndef THREAD_STACKSIZE_IDLE
+#if MODULE_XTIMER || MODULE_ZTIMER || MODULE_ZTIMER64
+/* For AVR no ISR stack is used, hence an IRQ will victimize the stack of
+ * whatever thread happens to be running with the IRQ kicks in. If more than
+ * trivial stuff is needed to be done in ISRs (e.g. when soft timers are used),
+ * the idle stack will overflow.
+ */
+#define THREAD_STACKSIZE_IDLE      (192)
+#else
+#define THREAD_STACKSIZE_IDLE      (96)
+#endif
+#endif
+/** @} */
+
+/**
+ * @brief   Attribute for memory sections required by SRAM PUF
+ */
+#define PUF_SRAM_ATTRIBUTES __attribute__((used, section(".noinit")))
+
+/**
+ * @brief   Declare the heap_stats function as available
+ */
+#define HAVE_HEAP_STATS
+
+/**
+ * @brief   This arch uses the inlined IRQ API.
+ */
+#define IRQ_API_INLINED     (1)
+
+#ifndef DOXYGEN
+#define HAS_FLASH_UTILS_ARCH    1
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CPU_CONF_H */
+/** @} */

cpu/atmega8/include/default_timer_config.h

@@ -0,0 +1,46 @@
+/*
+ * Copyright (C) 2015 HAW Hamburg
+ *               2016 Freie Universität Berlin
+ *               2023 Hugues Larrive
+ *
+ * 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_atmega8
+ * @{
+ *
+ * @file
+ * @brief           Default timer configuration
+ *
+ * @author          René Herthel <[email protected]>
+ * @author          Hauke Petersen <[email protected]>
+ * @author          Hugues Larrive <[email protected]>
+ */
+
+#ifndef DEFAULT_TIMER_CONFIG_H
+#define DEFAULT_TIMER_CONFIG_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef TIMER_NUMOF
+#define TIMER_NUMOF         (1U)
+#define TIMER_CHANNEL_NUMOF (2)
+
+#define TIMER_0             MEGA_TIMER1
+#define TIMER_0_MASK        &TIMSK
+#define TIMER_0_FLAG        &TIFR
+#define TIMER_0_ISRA        TIMER1_COMPA_vect
+#define TIMER_0_ISRB        TIMER1_COMPB_vect
+#endif /* TIMER_NUMOF */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* DEFAULT_TIMER_CONFIG_H */
+/** @} */

cpu/atmega8/include/periph_cpu.h

@@ -0,0 +1,98 @@
+/*
+ * Copyright (C) 2015 HAW Hamburg
+ *               2016 Freie Universität Berlin
+ *               2023 Hugues Larrive
+ *
+ * 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_atmega8
+ * @{
+ *
+ * @file
+ * @brief           CPU specific definitions for internal peripheral handling
+ *
+ * @author          René Herthel <[email protected]>
+ * @author          Hauke Petersen <[email protected]>
+ * @author          Hugues Larrive <[email protected]>
+ */
+
+#ifndef PERIPH_CPU_H
+#define PERIPH_CPU_H
+
+#include "periph_cpu_common.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   Define a CPU specific GPIO pin generator macro
+ */
+#define GPIO_PIN(x, y)          ((x << 4) | y)
+
+/**
+ * @brief   Available ports on the ATmega8 family
+ */
+enum {
+    PORT_B = 1,       /**< port B */
+    PORT_C = 2,       /**< port C */
+    PORT_D = 3        /**< port D */
+};
+
+/**
+ * @brief   Available external interrupt pins on the ATmega8 family
+ *
+ * In order of their interrupt number.
+ */
+#define CPU_ATMEGA_EXT_INTS    { GPIO_PIN(PORT_D, 2), \
+                                 GPIO_PIN(PORT_D, 3) }
+
+/**
+ * @brief   Get the interrupt vector number of the given GPIO pin
+ */
+static inline uint8_t atmega_pin2exti(uint8_t port_num, uint8_t pin_num)
+{
+    (void)port_num;
+    return pin_num - 2;
+}
+
+/**
+ * @brief   Check if the given pin can be used as external interrupt
+ */
+static inline bool atmega_has_pin_exti(uint8_t port_num, uint8_t pin_num)
+{
+    if (port_num == PORT_D) {
+        return ((pin_num == 2) || (pin_num == 3));
+    }
+
+    return false;
+}
+
+/**
+ * @name   Defines for the I2C interface
+ * @{
+ */
+#define I2C_PORT_REG            PORTC
+#define I2C_PIN_MASK            (1 << PORTC4) | (1 << PORTC5)
+/** @} */
+
+/**
+ * @name    EEPROM configuration
+ * @{
+ */
+#define EEPROM_SIZE                (512U)  /* 512B */
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#include "periph_conf.h"
+#include "default_timer_config.h"
+
+#endif /* PERIPH_CPU_H */
+/** @} */