Skip to content

Commit 7feaae4

Browse files
fpistmfpistm
committed
docs: add Tools menu options page
Document U(S)ART, USB, optimization, debug and C runtime library options of the Arduino Tools menu. Fixes #3108. Signed-off-by: Frederic Pillon <frederic.pillon@st.com> Assisted-by: GitHub Copilot: Claude Sonnet 5.5
1 parent fe3abb7 commit 7feaae4

3 files changed

Lines changed: 97 additions & 0 deletions

File tree

‎docs/Getting-Started.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,11 @@ See [Upload methods](Upload-methods.md) for more details.
112112

113113
![Upload Method](img/v2/UploadMethod.png)
114114

115+
### Other options
116+
Other options (U(S)ART, USB, optimization, debug, ...) are available in the "**Tools**" menu.
117+
118+
See [Tools menu options](Tools-menu.md) for more details.
119+
115120
## Examples
116121
* [Blink example](examples/Blink-example.md)
117122

‎docs/Tools-menu.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Tools menu options
2+
3+
Depending on the selected board, some of the following options are available in the "**Tools**" menu.
4+
5+
For the upload method, see [Upload methods](Upload-methods.md).
6+
7+
## U(S)ART support
8+
Menu: "**Tools > U(S)ART support**"
9+
10+
| Option | Description |
11+
|--------|-------------|
12+
| Enabled (generic 'Serial') | U(S)ART support is enabled and the generic `Serial` object is available. It is mapped to the board's default serial interface (e.g. the ST-LINK virtual COM port on Nucleo boards). |
13+
| Enabled (no generic 'Serial') | U(S)ART support is enabled (`-DHAL_UART_MODULE_ENABLED -DHWSERIAL_NONE`) but the generic `Serial` is not defined. Instances have to be created by the user (e.g. `HardwareSerial Serial2(PA3, PA2);`). |
14+
| Disabled (No Serial support) | U(S)ART support is disabled. Reduces the code size when serial is not used. |
15+
16+
## USB support
17+
Menu: "**Tools > USB support (if available)**"
18+
19+
| Option | Description |
20+
|--------|-------------|
21+
| None | USB is not enabled. |
22+
| CDC (generic 'Serial' supersede U(S)ART) | USB CDC (virtual COM port) is enabled (`-DUSBD_USE_CDC`) and the generic `Serial` is mapped to USB instead of the U(S)ART. |
23+
| CDC (no generic 'Serial') | USB CDC is enabled (`-DUSBD_USE_CDC -DDISABLE_GENERIC_SERIALUSB`) and the generic `Serial` is not mapped to USB. Use the `SerialUSB` object instead. |
24+
| HID (keyboard and mouse) | USB HID composite device is enabled (`-DUSBD_USE_HID_COMPOSITE`). |
25+
26+
> [!WARNING]
27+
> When USB is enabled, the USB pins (e.g. `PA11`/`PA12`, and potentially others such as `PA13`) are configured by the USB initialization. This may conflict with the SWD/JTAG pins and prevent debug from being functional.
28+
> See the [Debug](FAQ.md#debug) section of the FAQ for more details and how to avoid it.
29+
30+
### USB speed
31+
Menu: "**Tools > USB speed (if available)**"
32+
33+
Only available on boards with a High Speed capable USB peripheral.
34+
35+
| Option | Description |
36+
|--------|-------------|
37+
| Low/Full Speed | USB runs in Low/Full Speed mode (default). |
38+
| High Speed | USB runs in High Speed mode (`-DUSE_USB_HS`). |
39+
| High Speed in Full Speed mode | High Speed peripheral used in Full Speed mode (`-DUSE_USB_HS -DUSE_USB_HS_IN_FS`). |
40+
41+
## Virtual serial support
42+
Menu: "**Tools > Virtual serial support**"
43+
44+
Only available for STM32MP1 boards.
45+
46+
| Option | Description |
47+
|--------|-------------|
48+
| Disabled (no SerialVirtIO nor /dev/ttyRPMSG0 available) | VirtIO serial is disabled. |
49+
| SerialVirtIO (= generic 'Serial') <=> /dev/ttyRPMSG0 | VirtIO serial is enabled and the generic `Serial` is mapped to it. |
50+
| SerialVirtIO <=> /dev/ttyRPMSG0 | VirtIO serial is enabled (`-DDISABLE_GENERIC_SERIALVIRTIO`), the generic `Serial` is not mapped to it. |
51+
52+
## Optimize
53+
Menu: "**Tools > Optimize**"
54+
55+
Sets the compiler optimization level. The `LTO` variants enable link time optimization (`-flto`), which can reduce the code size and improve performance but increases the build time.
56+
57+
| Option | Compiler flags |
58+
|--------|----------------|
59+
| Smallest (-Os default) | `-Os` |
60+
| Smallest (-Os) with LTO | `-Os -flto` |
61+
| Fast (-O1) | `-O1` |
62+
| Fast (-O1) with LTO | `-O1 -flto` |
63+
| Faster (-O2) | `-O2` |
64+
| Faster (-O2) with LTO | `-O2 -flto` |
65+
| Fastest (-O3) | `-O3` |
66+
| Fastest (-O3) with LTO | `-O3 -flto` |
67+
| Debug (-Og) | `-Og` |
68+
| No Optimization (-O0) | `-O0` |
69+
70+
## Debug symbols and core logs
71+
Menu: "**Tools > Debug symbols and core logs**"
72+
73+
| Option | Compiler flags | Description |
74+
|--------|----------------|-------------|
75+
| None | `-DNDEBUG` (default) | No debug symbols, core logs disabled. |
76+
| Symbols Enabled (-g) | `-g -DNDEBUG` | Debug symbols are generated, needed to debug with a debugger (e.g. through SWD). Core logs are disabled. |
77+
| Core logs Enabled | _(`NDEBUG` not defined)_ | Core logs are enabled. No debug symbols. |
78+
| Core Logs and Symbols Enabled (-g) | `-g` | Debug symbols are generated and core logs are enabled. |
79+
80+
## C Runtime Library
81+
Menu: "**Tools > C Runtime Library**"
82+
83+
Selects the Newlib C library variant used at link time. By default the size optimized "nano" version is used, which does not support floating point in `printf()`/`scanf()` family functions.
84+
85+
| Option | Linker flags | Description |
86+
|--------|--------------|-------------|
87+
| Newlib Nano (default) | `--specs=nano.specs` | Size optimized C library, no float support in `printf`/`scanf`. |
88+
| Newlib Nano + Float Printf | `--specs=nano.specs -u _printf_float` | Adds float support to `printf`. |
89+
| Newlib Nano + Float Scanf | `--specs=nano.specs -u _scanf_float` | Adds float support to `scanf`. |
90+
| Newlib Nano + Float Printf/Scanf | `--specs=nano.specs -u _printf_float -u _scanf_float` | Adds float support to both `printf` and `scanf`. |
91+
| Newlib Standard | _(none)_ | Standard C library, full featured but larger. |

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ nav:
1111
- Arduino IDE 2: Getting-Started.md
1212
- Legacy IDE 1.8.x: Getting-Started_V1.md
1313
- Upload Methods: Upload-methods.md
14+
- Tools Menu Options: Tools-menu.md
1415
- Examples:
1516
- Overview: examples/Examples.md
1617
- Blink: examples/Blink-example.md

0 commit comments

Comments
 (0)