Troubleshooting

Sometimes, things do not go according to plan, and it becomes necessary to debug the debugging setup. A first good step is to have a look at the logging output. If you spot a log entry marked [CRITICAL], it may tell you already what went wrong. If you see, for example, the message

[CRITICAL] Target is not powered

then it is very likely that you forgot to power the target board, or you made a wiring error.

In general, one can distinguish between problems that prohibit the start of the GDB server and problems appearing while debugging.

Debugging does not start

For most of the error messages, it should be obvious what to do. However, there are a few messages that look cryptic, and/or a solution is not apparent.

  • Apple could not verify “...” is free of malware that may harm your Mac or compromise your privacy. This is an error message you may get under macOS. It happens when you download executables with a browser or from e-mail, which sets a particular extended attribute. You can remove this extended attribute from the file FILE as follows. Afterward, macOS will start these executables without a hitch.
> xattr -d com.apple.quarantine FILE

  • No compatible tool discovered: This could mean that no debug tool is connected, but it also could mean that another process currently uses it, that the serial line the tool is attached to is busy, or that you have not yet installed the necessary udev rules under Linux.

  • [Errno 48] Address already in use: This error can happen after the GDB server was terminated before the debugger. If you are working in a CLI environment, you can start PyAvrOCD with a different port using the --port option and tell GDB about the port when connecting with the target remote command. However, waiting a few minutes will also resolve the problem.

  • ISP programming failed. Wrong connection or wrong MCU? This error message is displayed when, on a debugWIRE target, the DWEN fuse cannot be set because ISP/SPI programming cannot be initiated. It could be a wiring problem. It could also mean that the MCU is not accessible anymore by ISP programming. In this case, only high-voltage programming helps.
  • Debug session not started: debugWIRE not activated by power-cycling. Parasitic power supply? debugWIRE was not activated despite (automatic) power-cycling. Perhaps there is a parasitic power supply problem? This happens in particular on Xplained-Mini boards since the board power is not switched when an automatic power cycle is performed. A cure can be to power the application circuit connected to the board through the IOREF pin instead of using the 5V or 3.3V pin.

Problems while debugging

Loading code and/or debugging feels sluggish

When using debugWIRE, the communication speed is severely limited from the beginning. With Atmel-ICE, the upload speed is roughly one kByte/sec; with the Xplained-Mini boards, it is 0.3 kBytes/sec. Using the readbeforewrite option (which is the default), subsequent uploads may be faster. If the MCU clock frequency is lower than 16 MHz, upload speed is even slower, and below a clock frequency of 1 MHz, it is no fun at all. Similarly, debugging operations are also somewhat slow. With JTAG, the situation is much better. Default speed is 1 MHz for programming and 200 kHz for debugging. However, you can request higher values when starting PyAvrOCD. Programming speed is only limited by the MCU's maximal frequency (and the wiring). Debugging speed should be no more than a quarter of the actual clock frequency of the target MCU.

The debugger does not stop at a line with a set breakpoint, but only later

This happens when the line marked to be stopped at does not contain any machine code. The problem gets worse when the switch Optimize for Debugging in the Arduino IDE 2 is not activated or, if you are working in a CLI environment, you did not use the -Og compiler option.

Variables cannot be accessed in the debugger

Again, this might be because you forgot to activate the optimization option for debugging. Or, it can be that link time optimization has optimized away your variable.

The values of a local variable cannot be changed, or a wrong value is displayed in the debugger

This happened to me recently. The culprit is avr-gcc (version 7.3.0 as distributed with the Arduino IDE). The only way to fix that is to use a more recent compiler version. If you have one at hand, together with the binary utilities, you can put a file platform.local.txt into the platform folder of your core and write the line compiler.path=/path/to/bin-folder/ into it.

Signals and error messages

Sometimes, GDB commands fail, often showing a signal that has been received, an error code, and/or an error message. The following is a list of those. When using dw-link, error messages might be brief or missing.

Signal or error code Error message Explanation
SIGHUP Enable debugWIRE first: 'monitor debugwire enable
or
JTAG pins are not enabled
or something similar		 If the debugger receives this signal, it means that there is no connection to the target's OCD. You need to enable debugging by setting a fuse or something similar, perhaps by issuing monitor debugwire enable.
SIGINT This is not an error signal. It rather signals that execution has been stopped by a keyboard interrupt (or something equivalent).
SIGILL Cannot execute because of BREAK instruction The debugger receives this signal when one tries to single-step or continue executing at a location where the user has placed a BREAK instruction. Alternatively, the BREAK instruction might be a leftover from a previously interrupted debugging session.
SIGTRAP This is not an error signal. Instead, it is issued when execution stops at a place where a breakpoint has been set.
SIGABRT See debug server log This signal is raised after an unrecoverable internal error or when execution shall be continued after such an error. Use the monitor info to get more information about the error.
SIGBUS Cannot execute because stack pointer is too low This signal is raised if the stack threatens to overwrite I/O registers when execution is about to start.
SIGSEGV No program loaded; cannot start execution This signal is raised when execution is about to start, but there is no prior load command. If this is done intentionally (because it is known that the flash memory has been programmed), one can disable the check by using the command monitor onlywhenloaded disable.
SISGSYS Too many breakpoints set Execution cannot continue because too many breakpoints have been set. You need to delete some in order to continue execution.
E01 Error code returned when attempting to read or write memory contents while there is no connection to the OCD.
E04 Error signaling that GDB requested a packet longer than the communicated maximal size.
E11 Error code returned when writing to flash memory was unsuccessful.
E13 Error code when writing to memory failed.
E14 Error code for a read memory failure.
E15 Error code when GDB sent a data package with the wrong size.

When using the dw-link debug probe, internal errors are reported directly by the dw-link firmware.

If the LED blinks furiously (0.1 seconds on/ 0.1 seconds off), then the debug server has hit an unrecoverable error. This might not be immediately reported by GDB, but one can get information about the specific error by using the monitor info command. The errors are only reported by number. If the error number is less than 100, then it is a connection error. Errors above 100 are serious internal debugger errors.

If you have encountered an internal debugger error, then please try to reproduce the problem and tell me how it happened.

After a reset or a power cycle of the hardware debugger, everything usually works again. If not, you need to unplug everything and put it together again.

Error # Meaning
1 Connection error: Could not communicate by ISP; check wiring
2 Connection error: Could not activate debugWIRE
3 Connection error: MCU type is not supported
4 Connection error: Lock bits or BOOTRST could not be cleared
5 Connection error: MCU has PC with stuck-at-one bits
6 Connection error: RESET line has a capacitive load
7 Connection error: Target not powered or RESET shortened to GND
8 MCU type does not match
9 Unknown connection error
101 No free slot in breakpoint table
102 Packet length too large
103 Wrong memory type
104 Packet length is negative
105 Reset operation failed
106 Memory address in flash read operation does not point to page start
107 Could not complete flash read operation
108 Could not complete RAM read operation
109 Memory address in flash write operation does not point to page start
110 Could not complete flash page erase operation
111 Could not load data into the flash buffer for writing
112 Error when programming flash page from buffer
113 Error verifying flashed page while loading program
114 Assignment of hardware breakpoint is inconsistent
115 BREAK inserted by debugger at a point where a step or execute operation is required
116 Trying to read flash word at an uneven address
117 Error when single-stepping
118 A relevant breakpoint has disappeared
119 Input buffer overflow
120 Wrong fuse
121 Breakpoint update while flash programming is active
122 Timeout while reading from debugWIRE line
123 Timeout while reading general register
124 Timeout while reading IO register
125 Could not reenable RWW
126 Failure while reading from EEPROM
127 Bad interrupt