Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
4 people authored Jul 5, 2023
4 parents 3ec62a2 + e13b3c4 + 0401d55 + 3fad959 commit f0dc0e7
Show file tree
Hide file tree
Showing 11 changed files with 365 additions and 0 deletions.
62 changes: 62 additions & 0 deletions boards/doc.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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}
=====================================

Expand Down
6 changes: 6 additions & 0 deletions core/msg.c
Original file line number Diff line number Diff line change
Expand Up @@ -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(),
Expand Down Expand Up @@ -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)) {
Expand Down
34 changes: 34 additions & 0 deletions cpu/atmega8/Kconfig
Original file line number Diff line number Diff line change
@@ -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"
7 changes: 7 additions & 0 deletions cpu/atmega8/Makefile
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions cpu/atmega8/Makefile.dep
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
include $(RIOTCPU)/atmega_common/Makefile.dep
1 change: 1 addition & 0 deletions cpu/atmega8/Makefile.features
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
include $(RIOTCPU)/atmega_common/Makefile.features
7 changes: 7 additions & 0 deletions cpu/atmega8/Makefile.include
Original file line number Diff line number Diff line change
@@ -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
10 changes: 10 additions & 0 deletions cpu/atmega8/doc.txt
Original file line number Diff line number Diff line change
@@ -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
*/
93 changes: 93 additions & 0 deletions cpu/atmega8/include/cpu_conf.h
Original file line number Diff line number Diff line change
@@ -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 */
/** @} */
46 changes: 46 additions & 0 deletions cpu/atmega8/include/default_timer_config.h
Original file line number Diff line number Diff line change
@@ -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 */
/** @} */
98 changes: 98 additions & 0 deletions cpu/atmega8/include/periph_cpu.h
Original file line number Diff line number Diff line change
@@ -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 */
/** @} */

0 comments on commit f0dc0e7

Please sign in to comment.