Home Getting Started Download Discussions Source Report An Issue

Debugging AVR microcontrollers via debugWire on Linux

The debugWire physical interface enables debugging operations by means of a single wire connection to the target. The RESET pin is used for debugWire connections. This means that the RESET pin will be unavailable for standard operation during debug sessions.

Many 8-bit AVR targets employ the debugWire physical interface for on-chip debugging. Bloom supports the debugWire physical interface - users can select the physical interface via their target configuration.

The "debugWire enable" (DWEN) fuse bit

The debugWire and ISP interfaces both require access to the target's RESET pin. All AVR targets with support for the debugWire physical interface provide the ability to enable/disable the debugWire module, via the "debugWire enable" (DWEN) fuse bit. The debugWire module must be enabled (the DWEN must be "programmed") in order to use the debugWire physical interface to perform on-chip debugging operations.

Once the debugWire module has been enabled, the target's ISP interface will become unavailable until the debugWire module is disabled.

The DWEN fuse bit is typically located in the target's HIGH fuse byte. A cleared bit (0b0) means the fuse is "programmed" and a set bit (0b1) means the fuse is "unprogrammed".

Managing the DWEN fuse bit via Bloom

Since version 0.7.0, Bloom possesses the ability to update the DWEN fuse bit. This function can be enabled via the updateDwenFuseBit target configuration parameter. When set to true, Bloom will automatically attempt to update the DWEN fuse bit upon initial debugWire connection failure. After updating the fuse bit, Bloom will make another attempt to connect to the target via debugWire.

"target": { "name": "atmega328p", "physicalInterface": "debug-wire", "updateDwenFuseBit": true }

CAUTION: Updating target fuses is a potentially dangerous operation. If done incorrectly, the target may become inaccessible for programming and may require high-voltage programming to recover. Whilst Bloom can manage the DWEN fuse bit, there is no guarantee that such an operation will be successful and not result in any damage to the target. Bloom is provided "AS IS", without warranty of any kind. You are using Bloom at your own risk. In no event shall Bloom's copyright owner or contributors be liable for any damage caused as a result of using Bloom. For more details, see the Bloom license.

The updateDwenFuseBit function cannot be used in conjunction with the generic "avr8" target name. The specific target name must be specified in the target configuration, in order for Bloom to manage the DWEN fuse bit.

In order for Bloom to manage the DWEN fuse bit, it must be able to connect to the target via the ISP interface. For this reason, the target must be connected to the debug tool via an ISP connection. The ISP connection accommodates the single wire debugWire connection, so it can be used for both interfaces without the need for modification when switching between ISP and debugWire.

Debugging with debugWire and programming with ISP

Currently, Bloom does not possess the ability to program the connected target. Programming must be done via other software tools such as MPLAB IPE or AVRDUDE.

Support for programming targets via Bloom is currently in consideration. Work will not begin on this until evidence of demand emerges. Users can express demand for this by adding a reaction or comment to the corresponding GitHub issue.

Most programming software can only program AVR targets via the ISP interface. For this reason, users are required to switch to the ISP interface when they wish to upload any code changes to the target. After programming the target, the debugWire module will need to be enabled, again, in order to start a new debug session and continue debugging with the applied code changes.

Both MPLAB IPE and AVRDUDE can perform the switch automatically, without any action being required from the user.

NOTE: There is a known bug in AVRDUDE, where the programmer (debug tool) fails to establish an ISP connection to the target. The duration of the failed connection attempt exceeds an internal AVRDUDE timeout, which results in AVRDUDE reporting "Short read, read only X out of Y bytes" errors. See the issue on GitHub for more.

After programming the target via ISP (using MPLAB IPE or AVRDUDE), the user must cycle the power to the target in order to be able to use the debugWire interface. Once the power has been cycled, Bloom will be able to establish a connection to the target in preparation for another debug session.

Cycling the target power is required as a result of the debugWire interface being disabled by the programming software.

NOTE: Some debug tools possess the ability to cycle the target power without user intervention. This is typically the case for evaluation boards. In this case, Bloom will automatically attempt to cycle the target power after updating the DWEN fuse bit. This function was introduced in version 0.8.0.

Ideal target configuration

The following is the ideal target configuration for debugging via debugWire and programming via ISP:

"target": { "name": "atmega328p", "physicalInterface": "debug-wire", "disableDebugWirePreDisconnect": false, "updateDwenFuseBit": true }

With the above configuration, Bloom will manage the DWEN fuse bit and leave the debugWire module enabled. The module will only be disabled when the user attempts to program the target via ISP, after which, Bloom will enable the module again, upon the start of a new debug session (assuming the target power has been cycled).

Questions/feedback?

Questions can be raised on Bloom's GitHub discussions page (GitHub account required). Please feel free to submit any questions or feedback via a new discussion.