rtfm-app
Real Time For the Masses (RTFM) framework for ARM Cortex-M microcontrollers
Documentation
Features
This is a minimalistic crate useful as a template for your own projects. It comprises:
- an
app!
system configuration with three task with two shared resources. - the use of the
cortex-m-debug
crate for simple tracing overitm
andsemihosting
-
vscode
integration:- Task configurations:
ctrl-shift-b
for building (Debug/Release) - Launch configurations:
ctrl-shift-d
for entering Debug. Select (Debug/Release) and press arrow to start.
- Task configurations:
- a file
r
demonstratinggdb
automation.
Requirements
- The
Native Debug
extension. - A running
gdb
server (e.g.,openocd
), connecting on port 3333. -
ITM
tracing truogh the file/tmp/itm.log
. - Access to
arm-none-eabi-gdb
.
Openocd
Start openocd
in a terminal window. (Status and semihosting output is visible here.)
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg
The configuration broken down:
-
stlink.cfg
defines the specifics for the STMicroelectronics ST-LINK/V1, ST-LINK/V2, ST-LINK/V2-1 in-circuit debugger/programmer interface.
interface hla
hla_layout stlink
hla_device_desc "ST-LINK"
hla_vid_pid 0x0483 0x3744 0x0483 0x3748 0x0483 0x374b
hla
relates to the interface driver (low level transport in between openocd
and the st-link programmer).
-
stm32f4x.cfg
is a script for the stm32f4x family, defining memory areas etc. It also defines the handling ofevents
, e.g.,-
trace-config
- enbling tracing. -
reset-start
- requesting adapter speed to a (conservative) 2000kHz (actual speed will be negotiated). -
reset-init
- setting the CPU to 64MHz (its 16MHz by default), and requesting adapter speed to 8000kHz (actual speed will be negotiated). -
examine-end
- debug behavior:- Enable debug during low power modes (uses more power).
- Stop watchdog counters during halt.
-
Launch configuration
{
"type": "gdb",
"request": "attach",
"name": "Debug",
"gdbpath": "/usr/bin/arm-none-eabi-gdb",
"executable": "./target/thumbv7em-none-eabihf/debug/app",
"target": ":3333",
"remote": true,
"autorun": [
"monitor reset init",
"monitor arm semihosting enable",
"monitor tpiu config internal /tmp/itm.log uart off 64000000",
"monitor itm port 0 on",
"load",
"monitor reset init"
],
"cwd": "${workspaceRoot}"
},
...
}
The autorun script broken down:
-
monitor reset init
Halts the processor and applies the
reset-init
configuration. -
monitor arm semihosting enable
Enables
semihosting
(breakpoint
handling for semihosting). -
monitor tpiu config internal /tmp/itm.log uart off 64000000
-
monitor itm port 0 on
Enables
itm
debugging assuming a clock speed of 64MHz. -
load
Loads the binary (set in "executable": "./target/thumbv7em-none-eabihf/debug/app") to the target.
load
performs areset-start
after finishing. -
monitor reset init
Set the MCU to 64MHz (again).
GDB
The gdb
tool allows to program and debug the target, e.g., set breakpoints, inspect memory, etc. gdb
can be highly automated through scripting. In the DEBUG
console you can interact directly with gdb
. The integration between the console and vscode
is rudimentary. The vscode
Native Debug
view is in general not notified/updated (by stepping/continuing through vscode
icons/shortcuts the view gets in synch). Even so, manual interaction with gdb
can be very useful, an example is to restart the program without reloading it (there is no shortcut/icon for this functionality in the Native Debug
extension). Enter in the DEBUG
console:
source() r
or simply:
so r
gdb
commands can typically be abbreviated, in this case so
for source
. Notice, you may run gdb
(arm-none-eabi-gdb
) directly in a terminal, in this case you get a both tabbing of commands and history (e.g., pressing enter repeats the last command).
The content of the file r
is simply:
monitor reset init
License
Licensed under either of
-
Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
-
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.