How to use the Arduino Uno R4 WiFi Debugger

This page replicates the debugger procedure from Prelab 3 for easy reference.

Basic debug procedure

Before uploading the code to the Arduino, make sure the “Optimize debugging” box is checked:

Also make sure that the Programmer is “ARM CMSIS-DAP Compatible” (note: if the menu doesn’t appear, first upload some code to the Arduino using the usual method. This will kick off the build process and allow the IDE to find any board-specific information, like the available programmers for our board.):

Upload the code to the Arduino as usual, and then use the “Start debugging” button to start debugging. You can add breakpoints at any point during this process by pressing in the gutter to the left of the line numbers in your code.

Important notes about debugging

• Always upload the code to the Arduino first, and then press the debug button. This allows for the compiled and uploaded binary to match up with the source code (otherwise, the behavior you observe may not correspond to the code you are stepping through)

• When the debugger first stops at a breakpoint, you may need to press continue/step over twice to advance past that line

• Always stop the debugger using the stop button before starting a new debug session. If you have a debug session open already, you will get a “GDB Server Quit Unexpectedly” message

Advanced: reading memory locations

The debugger uses a file format called “SVD” (System Viewer Description) to understand all of the addresses, bitfields, and valid field values of the various registers. If you find that the debugger isn’t showing a specific register that is described in the datasheet, this doesn’t mean the register doesn’t exist on the device. It just means that the SVD file is not comprehensive/up-to-date. The good news is that we can use the debug console to directly read in the register value. For example, you might find that HOCOCR2 is not under the SYSTEM peripheral tab in the registers list. However, in the datasheet, we can find the address of this register: as 0x4001e000, but this address is wrong (there is a reason we are using HOCOCR2 as an example in this guide…). This Renesas technical update (basically an errata or correction) says the offset address is 0x37, so the HOCOCR2 actual address is 0x4001e037:

We can use the GDB command x in the Debug Console to view the contents of this register. For example, since the datasheet says HOCOCR2 is 8 bits big, if we want to view its binary representation, we can use x/1bt 0x4001e037 (1b is the size of the value, or 1 byte, and t specifies that we want an output in binary):

This tells us that, for this run of the program the value of HOCOCR2 is 0b00010000 (note: this is not the default value! Watch out if you’re doing prelab 4 and run the command yourself). Using the datasheet, we know that the HCFRQ bits are b5 to b3, or 010 (we start counting from the rightmost bit at 0). From the datasheet, we can read off what that value means.

We’ve also found that some registers that are aligned on 2-byte boundaries (addresses ending in 2, 6, a, or e) don’t play nicely with the debugger, in that the values of two adjacent registers appear “swapped” in the debugger. If you are writing to a register and it looks like the next register up or down on the list is changing, this might be due to this issue – we’re pretty sure that this won’t happen for the registers we use for lab, but it might happen if you’re trying debug some registers we haven’t talked about. There is one github issue thread about this, but it wasn’t really resolved. For example, ADCER displays a value of 0, while ADADC displays an “unknown value” for the ADC field, but if we examine the values using the gdb console, we see that the values got flipped in the debugger display:

In this case, the gdb console output is the ground truth and the actual value of ADCER is 0b0000_0000_0010_0110 (and ADCAC is 0). Unfortunately, this is one of those things we have to deal with while trying to work with the complexities of real systems and one of those things that Milda wasted an entire afternoon on and was therefore inspired to write this note.