Debugging AVR microcontrollers via debugWire on GNU/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
Bloom possesses the ability to manage the DWEN fuse bit. This function can be enabled via the manageDwenFuseBit 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"
manageDwenFuseBit: 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 manageDwenFuseBit 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.
This section was written before the release of version 0.10.0, which introduced the ability to
program the target via GDB's load command.
Bloom can program debugWire targets via the debugWire interface. This removes the need to switch to the ISP interface when uploading any code changes.
Users are advised to use GDB's load command to update the target's
program memory with the latest binary. See
Programming the AVR target for more.
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.
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.
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
manageDwenFuseBit: 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 or 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.