Skip to content

Commit 8c6e9a5

Browse files
committed
Add board configuration tutorial
1 parent 8269d60 commit 8c6e9a5

1 file changed

Lines changed: 89 additions & 0 deletions

File tree

  • _docs/tutorials/advanced/microros_nuttx_bsp
Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
title: Adding Micro-ROS to a NuttX BSP
3+
permalink: /docs/tutorials/advanced/microros_nuttx_bsp/
4+
---
5+
6+
# Introduction
7+
8+
**If you want to use Micro-ROS on a board that is not yet supported, this tutorial is for you.**
9+
10+
However, we can only explain what you have to do on a board which is supported by NuttX already, that is, a board that has a board configuration. Writing a completely new board support package and configuration is beyond the scope of what the Micro-ROS project can teach.
11+
12+
## Caveats
13+
14+
1. The instructions in this tutorial have been tested on Linux only and since they use Linux shell commands, they will probably not work on Windows.
15+
1. We have only ever used ARM-based boards. Boards using different microcontrollers might needs a different approach.
16+
1. Our approach to adding C++ atomic swap instructions is problematic and needs further work, but it'll get you started.
17+
18+
## Basics
19+
20+
Compiling Micro-ROS for NuttX requires that the Board Configuration has a few C++ settings enabled. This tutorial explains what has to be added to an existing NuttX board configuration.
21+
22+
## Background: NuttX Board Configurations
23+
24+
**Note** This section is just for background, you don't need to create a board configuration yourself!
25+
26+
Microcontrollers are very diverse, and very versatile. The type and number of peripherals included differs a lot, and moreover, each specific board offers uses just a subset of them.
27+
28+
Therefore, the RTOS needs to be told which peripherals are used on a given board, and which pins the board has connected them to. In some cases, the board also requires custom initialization.
29+
30+
This is what we call the "board *configuration*". It differs from the so-called "Board Support *Package* (BSP)" which would contain the drivers for the micro-controller and its peripherals.
31+
32+
## Directory Structure
33+
34+
In NuttX up to version 7.x (which Micro-ROS currently uses), the configurations are stored in the `configs/` subdirectory.
35+
36+
In there are subdirectories for each board. The naming scheme differs, but often starts with the vendor, and then the name of the board. For example, the Olimex STM32-E407 reference board has its configuration in `configs/olimex-stm32e407`. We call this the *board base directory*.
37+
38+
Within the board base directory, there are two things:
39+
1) Board configuration directories, specifically `include`, `scripts`, and `src`.
40+
2) Predefined NuttX *build configurations*. These directories only have a `defconfig` file in them, and they are the directories you can pass to `scripts/configure.sh`.
41+
42+
# Adding Micro-ROS support
43+
44+
To add Micro-ROS build support, have two to 2 things:
45+
46+
1) Enable the right C++ settings
47+
1) Add C++ atomics builtins
48+
49+
A good example of the necessary modifications can be found in commit [26917196](https://github.com/micro-ROS/NuttX/commit/26917196e744b22433e699af71da1fcb86a96623).
50+
51+
## Enabling the right C++ settings
52+
53+
All the compiler configuration is found in `scripts/Make.defs`.
54+
55+
**Important**: Since this is a .defs file, it will only be evaluated by NuttX *during configuration*. Therefore, if you make changes, you have to do a `make distclean` and then a `tools/configure.sh` invocation!
56+
57+
1) Add C++ standard library includes
58+
59+
This basically means you have to add
60+
`ARCHXXINCLUDES+=-isystem $(TOPDIR)/include/uClibc++`
61+
after the block in which that variable is first defined.
62+
63+
2) Enable exceptions and RTTI
64+
65+
By default, the board configurations disable exceptions.
66+
67+
What we do is that we check whether UCLIBCXX_EXCEPTION is set, and if yes, we enable exceptions and RTTI. See [line 80 to 84 of commit 26917196](https://github.com/micro-ROS/NuttX/commit/26917196e744b22433e699af71da1fcb86a96623#diff-0199bac3041e59fbc59a9abd1492151eR80) for an example.
68+
```makefile
69+
ifeq ($(CONFIG_UCLIBCXX_EXCEPTION),y)
70+
ARCHCXXFLAGS = -fno-builtin -fcheck-new
71+
else
72+
ARCHCXXFLAGS = -fno-builtin -fno-exceptions -fcheck-new -fno-rtti
73+
endif
74+
```
75+
76+
3) Add libsupc++ to the build. This library is part of the toolchain, but there are multiple versions and you need the right one. The following snippet of Make code does that:
77+
```makefile
78+
LIBSUPXX = ${shell $(CC) $(CXXFLAGS) --print-file-name=libsupc++.a}
79+
EXTRA_LIBPATHS = -L "${shell dirname "$(LIBSUPXX)"}"
80+
EXTRA_LIBS = -lsupc++
81+
```
82+
83+
## Add C++ atomics builtins
84+
85+
C++11 and up requires that the toolchain provides atomic swap operations. These are hardware specific and in the toolchain version we currently use, they are not yet available for ARM. Therefore, we add a compatibility file called `libatomic.c`
86+
87+
1. Copy `libatomic.c` from `configs/olimex-stm32e407/src/libatomic.c` to your board configuration `src` directory.-
88+
89+
1. Add `libatomic.c` to the `CSRCS` line of `src/Makefile`.

0 commit comments

Comments
 (0)