From 163b82528907543571dd0c5412557bc5fd72b2e9 Mon Sep 17 00:00:00 2001
From: Martino Facchin <m.facchin@arduino.cc>
Date: Wed, 8 Jun 2022 14:57:32 +0200
Subject: [PATCH 1/6] mbed-os-to-arduino: add -g flag to restore gdb debug info
---
mbed-os-to-arduino | 11 ++++++++++-
1 file changed, 10 insertions(+), 1 deletion(-)
diff --git a/mbed-os-to-arduino b/mbed-os-to-arduino
index 2f01d4906..1c077227a 100755
--- a/mbed-os-to-arduino
+++ b/mbed-os-to-arduino
@@ -112,6 +112,12 @@ apply_patches () {
cd -
fi
echo " done."
+ if [ "$RESTORE_GDB_INFO" -eq 1 ]; then
+ echo "Restoring gdb info (this increases libmbed binary size, not suitable for release)"
+ cd mbed-os
+ git checkout tools/profiles/develop.json
+ cd -
+ fi
fi
}
@@ -277,11 +283,12 @@ patch_spi_h () {
# MAIN LOOP #
#############
-while getopts "cuar:b:p:" opt; do
+while getopts "cuagr:b:p:" opt; do
case $opt in
c ) export MBED_CLEAN=1 ;;
u ) export MBED_UPDATE=1 ;;
a ) export APPLY_PATCHES=1 ;;
+ g ) export RESTORE_GDB_INFO=1 ;;
r ) export LOCAL_REPO="$OPTARG" ;;
b ) export REMOTE_BRANCH="$OPTARG" ;;
p )
@@ -329,6 +336,7 @@ export MBED_CORE_LOCATION=${MBED_CORE_LOCATION:-$PWD}
export MBED_CLEAN=${MBED_CLEAN:-0}
export MBED_UPDATE=${MBED_UPDATE:-0}
export APPLY_PATCHES=${APPLY_PATCHES:-0}
+export RESTORE_GDB_INFO=${RESTORE_GDB_INFO:-0}
export LOCAL_REPO=${LOCAL_REPO:-""}
export REMOTE_BRANCH=${REMOTE_BRANCH:-""}
@@ -336,6 +344,7 @@ echo
echo MBED_CLEAN=$MBED_CLEAN
echo MBED_UPDATE=$MBED_UPDATE
echo APPLY_PATCHES=$APPLY_PATCHES
+echo RESTORE_GDB_INFO=$RESTORE_GDB_INFO
echo LOCAL_REPO="$LOCAL_REPO"
echo REMOTE_BRANCH="$REMOTE_BRANCH"
echo MBED_CORE_LOCATION="$MBED_CORE_LOCATION"
From 33b5b28d0a306ca7f7b18dfaae7d29ae852af1e3 Mon Sep 17 00:00:00 2001
From: Martino Facchin <m.facchin@arduino.cc>
Date: Wed, 8 Jun 2022 15:25:23 +0200
Subject: [PATCH 2/6] Modernize readme
---
README.md | 67 +++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 50 insertions(+), 17 deletions(-)
diff --git a/README.md b/README.md
index 905ab0a2f..38627adf3 100644
--- a/README.md
+++ b/README.md
@@ -37,30 +37,63 @@ fork/exec /bin/arm-none-eabi-g++: no such file or directory
```
To install ARM build tools, use the `Boards Manager` option in the Arduino IDE to add the `Arduino mbed-enabled Boards` package.
+## mbed-os-to-arduino script
-## Adding an mbed target
+The backbone of the packaging process is https://github.com/arduino/ArduinoCore-mbed/blob/master/mbed-os-to-arduino script. It basically compiles a blank mbed-os project for any supported target board, recovering the files that will be needed at compile time and copying them to the right location.
-Adding a target is a mostly automatic procedure that involves running https://github.com/arduino/ArduinoCore-mbed/blob/master/mbed-os-to-arduino after setting the `BOARDNAME` and `ARDUINOCORE` env variables.
-Actions marked as TODO must be executed manually.
+It can be used for a variety of tasks including:
+
+**Recompiling libmbed with source level debug support**
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+./mbed-os-to-arduino -a -g PORTENTA_H7_M7:PORTENTA_H7_M7
+```
+
+In this case `-a` applies all the patches from `patches` folder into a mainline `mbed-os` tree, and `-g` restores the debug info.
+
+**Selecting a different optimization profile**
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+PROFILE=release ./mbed-os-to-arduino -a NANO_RP2040_CONNECT:NANO_RP2040_CONNECT
+```
+
+The `PROFILE` environment variable tunes the compilation profiles (defaults to `DEVELOP`). Other available profiles are `DEBUG` and `RELEASE`.
+
+**Selecting a different mbed-os tree**
-**Minimum Example**:
```
cd $sketchbook/hardware/arduino-git/mbed
-./mbed-os-to-arduino -r /home/alex/projects/arduino/cores/mbed-os-h747 PORTENTA_H7_M7:PORTENTA_H7_M7
+./mbed-os-to-arduino -r /path/to/my/mbed-os-fork NICLA_VISION:NICLA_VISION
```
-### How to build a debug version of the Arduino mbed libraries
-* Modify `mbed-os-to-arduino `
-```diff
-mbed_compile () {
-- PROFILE_FLAG=""
- if [ x"$PROFILE" != x ]; then
- PROFILE_FLAG=--profile="$ARDUINOVARIANT"/conf/profile/$PROFILE.json
- export PROFILE=-${PROFILE^^}
-+ else
-+ export PROFILE="-DEBUG"
-+ PROFILE_FLAG="--profile=debug"
- fi
+`-r` flag allows using a custom `mbed-os` fork in place of the mainline one; useful during new target development.
+
+**Adding a new target (variant)**
+
+Adding a target is a mostly automatic procedure.
+
+For boards already supported by `mbed-os` , the bare minimum is
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+mkdir -p variants/$ALREADY_SUPPORTED_BOARD_NAME/{libs,conf}
+./mbed-os-to-arduino $ALREADY_SUPPORTED_BOARD_NAME:$ALREADY_SUPPORTED_BOARD_NAME
+# for example, to create a core for LPC546XX
+# mkdir -p variants/LPC546XX/{libs,conf}
+# ./mbed-os-to-arduino LPC546XX:LPC546XX
+```
+
+This will produce almost all the files needed. To complete the port, add the board specifications to `boards.txt` (giving it an unique name) and provide `pins_arduino.h` and `variants.cpp` in `variants/$ALREADY_SUPPORTED_BOARD_NAME` folder.
+Feel free to take inspirations from the existing variants :)
+
+For boards not supported by mainline `mbed-os`, the same applies but you should provide the path of your `mbed-os` fork
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+mkdir -p variants/$BRAND_NEW_BOARD_NAME/{libs,conf}
+./mbed-os-to-arduino -r /path/to/mbed-os/fork/that/supports/new/board $BRAND_NEW_BOARD_NAME:$BRAND_NEW_BOARD_NAME
```
## Using this core as an mbed library
From 1587cae1438938c4611c2bba864d88532167bae0 Mon Sep 17 00:00:00 2001
From: Martino Facchin <m.facchin@arduino.cc>
Date: Thu, 9 Jun 2022 09:21:59 +0200
Subject: [PATCH 3/6] Update README.md
Co-authored-by: per1234 <accounts@perglass.com>
---
README.md | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/README.md b/README.md
index 38627adf3..09f6058e5 100644
--- a/README.md
+++ b/README.md
@@ -39,11 +39,11 @@ To install ARM build tools, use the `Boards Manager` option in the Arduino IDE t
## mbed-os-to-arduino script
-The backbone of the packaging process is https://github.com/arduino/ArduinoCore-mbed/blob/master/mbed-os-to-arduino script. It basically compiles a blank mbed-os project for any supported target board, recovering the files that will be needed at compile time and copying them to the right location.
+The backbone of the packaging process is the https://github.com/arduino/ArduinoCore-mbed/blob/master/mbed-os-to-arduino script. It basically compiles a blank Mbed OS project for any supported target board, recovering the files that will be needed at compile time and copying them to the right location.
It can be used for a variety of tasks including:
-**Recompiling libmbed with source level debug support**
+### Recompiling libmbed with source level debug support
```
cd $sketchbook/hardware/arduino-git/mbed
@@ -52,7 +52,7 @@ cd $sketchbook/hardware/arduino-git/mbed
In this case `-a` applies all the patches from `patches` folder into a mainline `mbed-os` tree, and `-g` restores the debug info.
-**Selecting a different optimization profile**
+### Selecting a different optimization profile
```
cd $sketchbook/hardware/arduino-git/mbed
@@ -61,7 +61,7 @@ PROFILE=release ./mbed-os-to-arduino -a NANO_RP2040_CONNECT:NANO_RP2040_CONNECT
The `PROFILE` environment variable tunes the compilation profiles (defaults to `DEVELOP`). Other available profiles are `DEBUG` and `RELEASE`.
-**Selecting a different mbed-os tree**
+### Selecting a different Mbed OS tree
```
cd $sketchbook/hardware/arduino-git/mbed
@@ -70,11 +70,11 @@ cd $sketchbook/hardware/arduino-git/mbed
`-r` flag allows using a custom `mbed-os` fork in place of the mainline one; useful during new target development.
-**Adding a new target (variant)**
+### Adding a new target ([core variant](https://arduino.github.io/arduino-cli/latest/platform-specification/#core-variants))
Adding a target is a mostly automatic procedure.
-For boards already supported by `mbed-os` , the bare minimum is
+For boards already supported by Mbed OS, the bare minimum is:
```
cd $sketchbook/hardware/arduino-git/mbed
@@ -85,10 +85,10 @@ mkdir -p variants/$ALREADY_SUPPORTED_BOARD_NAME/{libs,conf}
# ./mbed-os-to-arduino LPC546XX:LPC546XX
```
-This will produce almost all the files needed. To complete the port, add the board specifications to `boards.txt` (giving it an unique name) and provide `pins_arduino.h` and `variants.cpp` in `variants/$ALREADY_SUPPORTED_BOARD_NAME` folder.
+This will produce almost all the files needed. To complete the port, add the board specifications to [`boards.txt`](https://arduino.github.io/arduino-cli/latest/platform-specification/#boardstxt) (giving it a unique ID) and provide `pins_arduino.h` and `variants.cpp` in `variants/$ALREADY_SUPPORTED_BOARD_NAME` folder.
Feel free to take inspirations from the existing variants :)
-For boards not supported by mainline `mbed-os`, the same applies but you should provide the path of your `mbed-os` fork
+For boards not supported by mainline Mbed OS, the same applies but you should provide the path of your Mbed OS fork
```
cd $sketchbook/hardware/arduino-git/mbed
From 1e05037fc08e8f574a60a1512beeac36762fc6f4 Mon Sep 17 00:00:00 2001
From: Alexander Entinger <consulting@lxrobotics.com>
Date: Thu, 9 Jun 2022 09:58:13 +0200
Subject: [PATCH 4/6] Adding easily reachable information on top on how to
create enable source-code-level-debugging.
---
README.md | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/README.md b/README.md
index 09f6058e5..1595b88ce 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,12 @@
The repository contains the Arduino APIs and IDE integration files targeting a generic mbed-enabled board
+## FAQ
+### Source-Code Level Debugging
+**Question**: "I want to debug my ArduinoCore-mbed based sketch using traditional debugging tools, i.e. gdb via SWD interface. However, the debugger is unable to locate the sources for all files, particular the mbed-os files."
+
+**Answer**: This is due to the fact that we pre-compile the mbed-os code into a static library `libmbed.a`. Information on how to recompile `libmbed.a` for source code debugging can be found [here](#recompiling-libmbed-with-source-level-debug-support).
+
## Installation
### Clone the repository in `$sketchbook/hardware/arduino-git`
From 6035783791fe1ac67bbf6caf29becd3996bef1d3 Mon Sep 17 00:00:00 2001
From: Martino Facchin <m.facchin@arduino.cc>
Date: Thu, 9 Jun 2022 10:13:57 +0200
Subject: [PATCH 5/6] Add info on mbed_app.json
---
README.md | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/README.md b/README.md
index 1595b88ce..5899c21bc 100644
--- a/README.md
+++ b/README.md
@@ -102,6 +102,12 @@ mkdir -p variants/$BRAND_NEW_BOARD_NAME/{libs,conf}
./mbed-os-to-arduino -r /path/to/mbed-os/fork/that/supports/new/board $BRAND_NEW_BOARD_NAME:$BRAND_NEW_BOARD_NAME
```
+### Customizing Mbed OS build without modifying the code
+
+Most Mbed OS defines can be tuned using a project file called `mbed_app.json` . In case you need to tune a build you can add that file to your variant's `conf` folder. One example is https://github.com/arduino/ArduinoCore-mbed/blob/master/variants/PORTENTA_H7_M7/conf/mbed_app.json .
+Providing an invalid json or replacing a non-existing property will make the build fail silently, so it's always better to validate that file with a standard Mbed OS project.
+
+
## Using this core as an mbed library
You can use this core as a standard mbed library; all APIs are under `arduino` namespace (so they must be called like `arduino::digitalWrite()` )
From b54cfbf27835f13ff412f33e155bdc84c79bd638 Mon Sep 17 00:00:00 2001
From: Alexander Entinger <consulting@lxrobotics.com>
Date: Thu, 9 Jun 2022 10:34:53 +0200
Subject: [PATCH 6/6] Let's add some cross-links to docs.arduino.cc .
People arriving at the README can then follow the bread-crumbs to the more comprehensive documentation.
---
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 5899c21bc..381bad637 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ The repository contains the Arduino APIs and IDE integration files targeting a g
### Source-Code Level Debugging
**Question**: "I want to debug my ArduinoCore-mbed based sketch using traditional debugging tools, i.e. gdb via SWD interface. However, the debugger is unable to locate the sources for all files, particular the mbed-os files."
-**Answer**: This is due to the fact that we pre-compile the mbed-os code into a static library `libmbed.a`. Information on how to recompile `libmbed.a` for source code debugging can be found [here](#recompiling-libmbed-with-source-level-debug-support).
+**Answer**: This is due to the fact that we pre-compile the mbed-os code into a static library `libmbed.a`. Information on how to recompile `libmbed.a` for source code debugging can be found [here](#recompiling-libmbed-with-source-level-debug-support). The [Arduino Documentation](https://docs.arduino.cc/) also contains articles explaining how to debug via [Segger J-Link](https://docs.arduino.cc/tutorials/portenta-breakout/breakout-jlink-setup) and [Lauterbach TRACE32](https://docs.arduino.cc/tutorials/portenta-h7/lauterbach-debugger).
## Installation