UNO R4 WiFi Stack Trace Debug Runtime Errors
Learn how to get information from the Cortex-M4 processor on a runtime error.
The Arduino UNO R4 WiFi uses CmBacktrace to print useful information from the Arm Cortex-M4 processor as serial output when a runtime error occurs. The output includes an
addr2line
command that can used to produce a stack trace (also stack backtrace, or stack traceback), which can be used to find the source of the error.In this tutorial, we will show to enable this feature.
Hardware & Software Needed
View the Runtime Error
To get the runtime error information in the Serial Monitor, follow the steps below:
Ensure that a serial connection must be initiated before the error occurs, by calling Serial.begin() in your sketch. You can include this code inside the beginning of the
function:setup()
1Serial.begin(115200);2while (!Serial);Connect your UNO R4 WiFi board to your computer.
Open the Serial Monitor. Click the Serial Monitor button in the top-right corner or select Tools > Serial Monitor in the menu bar.
If you made any changes to your sketch, click the Upload button. Otherwise, you can simply press the RESET button on the board.
If an exception occurs on the board, information will be displayed in the Serial Monitor.
Following the "Registers information" table, the type of fault will be specified. You can read more about the types here.
The last line includes a command for the
utility. See Running addr2line for more information.addr2line
Generate a Stack Trace
You can use the
addr2line
tool to generate a stack trace. See the instructions below:Note:
is not available as a native Windows application, but can be run with Windows Subsystem for Linux (WSL).addr2line
The
addr2line
utility is included in the Arduino UNO R4 Boards boards package. However, running it in this way requires modifying the command included in the output. For convenience, you may want to install addr2line
on your system.To install
addr2line
(optional), use the OS specific instructions below:- Windows (WSL):
is not available as a native Windows application, but can be run with Windows Subsystem for Linux (WSL). The Ubuntu distribution of Linux is installed by default and should come withaddr2line
.addr2line
- macOS:
can be installed with Homebrew by runningaddr2line
in Terminal.brew install binutils
- Linux:
may already be installed on your system. Otherwise, runaddr2line
in Terminal (Ubuntu, Debian), or see command-not-found.com/addr2line for other distributions.apt-get install binutils
1. Copy the addr2line
Command
addr2line
Windows (WSL):
- Copy the command from the serial output.
- Paste the command into a text editor.
- Replace
withC:
and replace all backslashes (/mnt/c
) with forward slashes (\
)./
macOS:
Copy the command from the serial output (no modification required).
Linux:
Copy the command from the serial output (no modification required).
If you don't want to install
, you can use the addr2line
from the board package. See the instructions hereaddr2line
2. Running the addr2line
Command
addr2line
Note: The sketch needs to have been compiled on the same computer you are running
on.addr2line
Windows (WSL):
- Open Windows Powershell.
- Type
into Windows Powershell and press Enter.Ubuntu
- Paste the modified command into Windows Powershell by right-clicking on the window.
- Press Enter to run the command.
macOS:
- Open Terminal.
- Press ⌘ + V to paste the command.
- Press Enter to run the command.
Linux:
- Open Terminal.
- Press Ctrl + ⇧Shift + V to paste the command.
- Press Enter to run the command.
Optionally, you can add the
-p
flag to your command for a more readable format.3. Reading the addr2line
Output
addr2line
By default, the command outputs the following for each function call:
- address: "
", "0x00004188
", ... (remove the0x0000426e
flag if you don't want to include these)-a
- function name: "
", "_ZN4UART5writeEh
", ...loop
- line number "
, .../Users/sebastianwikstrom/Documents/Arduino/ErrorInducer/ErrorInducer.ino:67
Follow these steps:
Look for the topmost line in the output that's inside your sketch. The number following the path is the line number where the error occurred. For example,
indicates that the error occurred on line 67. By reading further down the output, you can step backward through the function calls that were made./Users/username/Documents/Arduino/ErrorInducer/ErrorInducer.ino:67
Open the sketch in Arduino IDE and find the line number from the previous step (the number is displayed to the left of each line).
Analyze the row where the error occurred and try to understand what may be triggering the error.
- If you're not sure, use the Serial.println() function to output the values of any variables being used. Then upload the sketch again, and use the serial output to see what the states of those variables were before the error occurred.
- To see from where the function was called, look at the preceding function call in the
output.addr2line
In this example, an out-of-bounds access of the
numbers
array occurs after a few iterations of the while(true)
loop:Additional Instructions
Copy the addr2line
Command (Board Package)
addr2line
These instructions replace the instructions in 1. Copy
Commandaddr2line
If you want to use the
addr2line
directly from the board package, follow the instructions belowWindows (WSL):
- Copy the command from the serial output.
- Paste the command into a text editor.
- Replace the word
withaddr2line
/mnt/c/Users/User/Appdata/Local/Arduino15/packages/arduino/tools/arm-none-eabi-gcc/7-2017q4/bin/arm-none-eabi-addr2line
- For the file path after the
flag, replace-e
withC:
and replace all backslashes (/mnt/c
) with forward slashes (\
)./
macOS:
- Copy the command from the serial output.
- Paste the command into a text editor.
- Replace the word
withaddr2line
.~/Library/Arduino15/packages/arduino/tools/arm-none-eabi-gcc/7-2017q4/bin/arm-none-eabi-addr2line
Linux:
- Copy the command from the serial output.
- Paste the command into a text editor.
- Replace the word
withaddr2line
..arduino15/packages/arduino/tools/arm-none-eabi-gcc/7-2017q4/bin/arm-none-eabi-addr2line
Suggest changes
The content on docs.arduino.cc is facilitated through a public GitHub repository. If you see anything wrong, you can edit this page here.
License
The Arduino documentation is licensed under the Creative Commons Attribution-Share Alike 4.0 license.