V4.0.0

core-mods/debugaddopt.py

@@ -118,18 +118,23 @@ def gatherextra(lines, boards):
 
 file.write("# Debugger configuration (general options)\n")
 file.write("# ----------------------------------------\n")
-file.write("# EXPERIMENTAL feature:\n")
-file.write("#  - this is alpha and may be subject to change without notice\n")
 file.write("debug.executable={build.path}/{build.project_name}.elf\n")
 file.write("debug.toolchain=gcc\n")
 file.write("debug.toolchain.path={runtime.tools.dw-link-tools.path}\n")
 file.write("\n")
 file.write("debug.server=openocd\n")
 file.write("debug.server.openocd.path={debug.toolchain.path}/dw-server\n")
 file.write("#doesn't matter, but should be specified so that cortex-debug is happy\n")
-file.write("debug.server.openocd.scripts_dir={debug.toolchain.path}/\n")
-file.write("#doesn't matter, but should be specified so that cortex-debug is happy\n")
-file.write("debug.server.openocd.script={debug.toolchain.path}/dw-server\n")
+file.write("debug.server.openocd.script=doesnotmatter\n")
+file.write("debug.cortex-debug.custom.gdbPath={debug.toolchain.path}/avr-gdb\n")
+file.write("debug.cortex-debug.custom.objdumpPath={runtime.tools.avr-gcc.path}/avr-objdump\n")
+file.write("debug.cortex-debug.custom.serverArgs.0=-s");
+file.write("debug.cortex-debug.custom.serverArgs.1=noop");
+file.write("debug.cortex-debug.custom.serverArgs.2=-p");
+file.write("debug.cortex-debug.custom.serverArgs.3=50000");
+file.write("debug.cortex-debug.custom.postLaunchCommands.0=monitor mcu {build.mcu}");
+file.write("debug.cortex-debug.custom.postLaunchCommands.1=break setup");
+
 
 print("Platform file successfully modified")
 

docs/changelog.md

@@ -7,10 +7,21 @@
   definition files, and the packing of tools. However, there are also
   a few changes in dw-link
 - Changed: In gdbConnect, connection failures are transmitted using an
-  O-record (with a ***-prefix), even if we have verbose=false. The transmission will be
-  captured by dw-server and displayed in the right window
+  O-record, even if we have verbose=false. The transmission will be
+  captured by dw-server and displayed in the right window in the Arduino IDE 2
 - Added: All fatal error messages transmitted using an O-record are
-  prefixed with "***" so that dw-server can capture and display this message
+  prefixed with "***" so that dw-server can capture and display the
+  message
+- Changed: Removed 'A' suffix from board names in MCU names
+- Changed: In gdbDetermineMonitorCommand, instead of determining the
+  option char, the index of the frist non-blank char after the monitor
+  command is dertermined and returned.
+- Changed: In gdbParseMonitorPacket, we switch now on cmdbuf[mooptix]
+  instead of moopt.
+- Added: New monitor command mcu that checks whether the mcu
+  type given in the command matches. If not, then a fatal error is
+  raised.
+
 
 ## Version 3.5.6 (17-Dec-2024)
 

docs/manual.md

@@ -304,11 +304,13 @@ You start by first verifying the sketch (which will also compile it) and then by
 
 ![ide0](/Users/nebel/Documents/GitHub/dw-link/docs/pics/ide0.png)
 
-Since starting the debugger will also begin the program's execution on the target, setting a first breakpoint at the start of the setup function is a good idea. After that, one can click the debug button in the upper row to start the debug process, as shown in the following picture.
+After that, one can click the debug button in the upper row to start the debug process, as shown in the following picture.
 
 ![ide1](/Users/nebel/Documents/GitHub/dw-link/docs/pics/ide1.png) 
 
-The debugger starts, and eventually, execution is stopped in line 8 (because line 7 does not contain any executable code). The yellow triangle signifies this. Now is a good time to familiarize oneself with the window's layout. On the right side, there is the source code. Below that, there is a console window, and to the left, we have the debug panes.
+The debugger starts, and eventually, execution is stopped in line 8 at an initial internal breakpoint, indicated by the yellow triangle left of line 8 in the following screenshot. It might take a while before we reach that point because the debugger also loads the program. 
+
+Now is a good time to familiarize yourself with the window's layout. The source code is on the right side. Below that is a console window, and to the left are the debug panes. If you want to set a breakpoint, you can do that by clicking to the left of the line numbers. Such breakpoints are displayed as red dots as the one left of line 12.
 
 ![ide2](/Users/nebel/Documents/GitHub/dw-link/docs/pics/ide2.png)
 
@@ -324,11 +326,19 @@ Pane A contains the debug controls. From left to right:
 
 Pane B shows the active threads, but there is just one in our case. Pane C displays the call stack starting from the bottom, i.e., the current frame is the topmost. Pane D displays variable values. Unfortunately, global variables are not shown. Pane E can be populated with watch expressions. This can be used to display relevant global variables. Finally, in pane F, the active breakpoints are listed. The panes below that are useless in our case.
 
+Some more information about debugging can be found in the [debugging tutorial](https://piolabs.com/blog/insights/debugging-introduction.html) for the PlatformIO IDE. Although it was written for PlatoformIO, it also applies to the Arduino IDE 2 to a large extent. 
+
+### 5.4 Some "Pro" Tips
+
+Global variables are, for some reason, not displayed. However, you can set a watch expression in the Watch pane to display a global variable's value.
+
+If you select the Debug Console, you can type GDB commands (see Section 6.6) in the bottom line. This can be useful for changing the value of global variables, which cannot be accessed otherwise. 
+
 <a name="section6"></a>
 
 ## 6. Arduino IDE and avr-gdb
 
-If you are not comfortable using Arduino IDE 2, a more minimalistic approach might be better. The GNU Debugger GDB provides console-based interactions and can be easily configured to work with dw-link. You only have to install the avr-gdb debugger and the appropriate board manager files. Note that this works only with Arduino IDE versions at least 1.8.13. 
+A more minimalistic approach might be better if you are uncomfortable using Arduino IDE 2. The GNU Debugger GDB provides console-based interactions and can be easily configured to work with dw-link. You only must install the avr-gdb debugger and the appropriate board manager files. Note that this works only with Arduino IDE versions at least 1.8.13. 
 
 ### 6.1 Installing board manager files
 
@@ -366,7 +376,7 @@ If the avr-gdb version is not there, all of the versions are incompatible with y
   sudo apt-get install gdb-avr 
   ```
 
-* Windows: You can download the AVR-toolchain from the [Microchip website](https://www.microchip.com/en-us/development-tools-tools-and-software/gcc-compilers-avr-and-arm) or Zak's Electronic Blog\~\*](https://blog.zakkemble.net/avr-gcc-builds/). This includes avr-gdb. You have to copy `avr-gdb.exe` (which you find in the `bin` folder) to some place (e.g., to C:\ProgramFiles\bin) and set the `PATH` variable to point to this folder. Afterward, you can execute the debugger by simply typing `avr-gdb.exe` into a terminal window (e.g. Windows Powershell).
+* Windows: You can download the AVR-toolchain from the [Microchip website](https://www.microchip.com/en-us/development-tools-tools-and-software/gcc-compilers-avr-and-arm) or [Zak's Electronic Blog](https://blog.zakkemble.net/avr-gcc-builds/). This includes avr-gdb. You have to copy `avr-gdb.exe` (which you find in the `bin` folder) to some place (e.g., to C:\ProgramFiles\bin) and set the `PATH` variable to point to this folder. Afterward, you can execute the debugger by simply typing `avr-gdb.exe` into a terminal window (e.g. Windows Powershell).
 
 ### 6.3 Compiling the sketch
 
@@ -461,7 +471,7 @@ Quit anyway? (y or n) y
 
 ### 6.5 Disabling debugWIRE mode explicitly
 
-Exiting GDB should disable debugWIRE mode. However, if something went wrong or you killed the debug session, the ATtiny MCU might still be in debugWIRE mode and the RESET pin cannot be used to reset the chip and you cannot use ISP programming. In this case, you can explicitly disable debugWIRE, as shown below. 
+Exiting GDB should disable debugWIRE mode. However, if something went wrong, you set the [`AutoDW` jumper](#jumper) to `off`, or you killed the debug session, the ATtiny MCU might still be in debugWIRE mode, the RESET pin cannot be used to reset the chip, and you cannot use ISP programming. In this case, you can explicitly disable debugWIRE, as shown below. 
 
 ```
 > avr-gdb
@@ -477,6 +487,8 @@ debugWIRE is now disabled
 (gdb) quit
 >
 ```
+<a name="#section66"></a>
+
 ### 6.6 GDB commands
 
 In the example session above, we saw several relevant commands already. If you really want to debug using GDB, you need to know a few more commands, though. Let me just give a brief overview of the most relevant commands (anything between square brackets can be omitted, a vertical bar separates alternative forms, and arguments are in italics). For the most common commands, it is enough to just type the first character (shown in boldface). In general, you only have to type as many characters as are necessary to make the command unambiguous. You also find a good reference card and a very extensive manual on the [GDB website](https://sourceware.org/gdb/current/onlinedocs/). I also recommend these [tips on using GDB](https://interrupt.memfault.com/blog/advanced-gdb) by [Jay Carlson](https://jaycarlson.net/). 
@@ -486,7 +498,7 @@ command | action
 **h**elp [*command*] | get help on a specific command
 **s**tep [*number*] | single step statement, descending into functions (step in), *number* times 
 **n**ext [*number*] | single step statement without descending into functions (step over)
-finish | finish current function and return from call (step out)
+finish | finish the current function and return from call (step out) 
 **c**ontinue [*number*] | continue from current position and stop after *number* breakpoints have been hit. 
 **r**un | reset MCU and restart program at address 0x0000
 **b**reak *function* \| [*file*:]*number* | set breakpoint at beginning of *function* or at line *number* in *file* 
@@ -735,6 +747,8 @@ I have turned the modified prototype into an Arduino Shield, which you can buy [
 
 ![dw-link probe](/Users/nebel/Documents/GitHub/dw-link/docs/pics/dw-probe.jpg)
 
+<a name="jumper"></a>
+
 Before you start, you have to configure three jumpers. Then you are all set.
 
 Label | Left | Middle | Right 
@@ -1021,7 +1035,8 @@ Error #  | Meaning
 2 | Connection error: MCU type is not supported
 3 | Connection error: Lock bits are set 
 4 | Connection error: MCU has PC with stuck-at-one bits 
-5 | Unknown connection error
+5 | MCU type does not match 
+6 | Unknown connection error 
 101 | No free slot in breakpoint table
 102 | Packet length too large
 103 | Wrong memory type
@@ -1146,3 +1161,4 @@ Initial version
 #### V 4.0
 
 * Integration of Arduino IDE 2
+* New fatal error: Wrong MCU type (caused by monitor mcu command)

docs/quickstart-Arduino-IDE2.md

@@ -25,7 +25,7 @@ If you want to debug your classic AVR chips without using Arduino IDE 2, consult
 
 You probably already have installed the Arduino IDE 2. If not, download and install it from https://arduino.cc. 
 
-**Check:** Start IDE and check the `About Arduino` entry under the `Arduino` or `Help` menu for the version number.
+**Check:** Start IDE and check the `About Arduino` entry under the `Arduino` or `Help` menu for the version number. It should be >= 2.3.0.
 
 ## Step 2: Install new board definition files
 
@@ -46,7 +46,7 @@ Close the `Preference` dialog with `OK`. Now, we want to install the two cores,
 
 ## Step 3: Install *dw-link* firmware
 
-Download the dw-link firmware into a place inside the *Arduino sketchbook*. This means, you should 
+Download the dw-link firmware. This means you should 
 
 * open the webpage https://github.com/felias-fogg/dw-link, 
 * click on `Latest` in the field **Releases**,
@@ -112,10 +112,9 @@ Note that state 2 (power-cycling) will be skipped in our configuration, where th
 - In the `Sketch` menu, select `Optimize for Debugging`.
 - Compile the code by clicking on the `Verify` button in the upper left corner.  
 - Open the debug panes by clicking the debug symbol (bug with triangle) in the left sidebar. 
-- Now, you can set breakpoints by left-clicking the left of the line numbers of the source code file. 
 - Click the debug symbol in the top row to start debugging. This will start the debugger and the debug server. The activities are logged in the `Debug Console` and the `gdb-server` console in the bottom right part of the window. 
-- After the debugger and debug-server have been started, the debugger will start executing the program on the target. Execution will either stop at a breakpoint or, if no breakpoint has been set, you must stop execution by clicking the Pause button in the debug row (upper left in the window).
-- Now, you are in business and can set breakpoints, inspect and change values, and examine different stack frames. To terminate your debugging session, click the red box in the debug row.
+- After the debugger and debug-server have been started, the debugger will start executing the program on the target. Execution will stop at the first line of the `setup` function.
+- Now, you are in business and can set breakpoints, continue executing, stop the program asynchronously, inspect and change values, and examine different stack frames. To terminate your debugging session, click the red box in the debug row.
 
 ## What can go wrong?
 

dw-link/dw-link.h

@@ -108,6 +108,7 @@ void DWreadSramBytes(unsigned int, byte *, byte);
 byte DWreadEepromByte(unsigned int);
 void DWwriteEepromByte(unsigned int, byte);
 void DWreadFlash(unsigned int, byte *, unsigned int);
+void ispDelay(boolean);
 void DWeraseFlashPage(unsigned int);
 void DWprogramFlashPage(unsigned int);
 void DWloadFlashPageBuffer(unsigned int, byte *);
@@ -118,11 +119,10 @@ unsigned int DWgetChipId();
 void DWsetWPc(unsigned int);
 void DWsetWBp(unsigned int);
 void DWexecOffline(unsigned int);
-byte DWflushInput();
 void enableSpiPins();
 void disableSpiPins();
 byte ispTransfer(byte);
-void ispDelay(boolean);
+byte DWflushInput();
 byte ispSend(byte, byte, byte, byte, boolean);
 boolean enterProgramMode();
 void leaveProgramMode();