V1.3.9

felias-fogg · Feb 17, 2022 · 5797c8a · 5797c8a
1 parent 2f2da3b
commit 5797c8a
Show file tree

Hide file tree

Showing 5 changed files with 79 additions and 17 deletions.
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -661,3 +661,8 @@ enable debugging
 this is needed by the original Arduino Nano
 - added some explanations in the manual concerning communication speed
 - added the no optimization debug option in debugadd.py
+
+## Version 1.3.9 (17-Feb-22)
+
+- New `monitor help` command
+- Added some additional trouble shooting hints concerning debugging when lock-bits are set.
diff --git a/docs/manual.md b/docs/manual.md
@@ -4,7 +4,7 @@
 
 **Bernhard Nebel**
 
-**Version 1.6 - January 29, 2022**
+**Version 1.9 - February, 2022**
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
 
@@ -445,8 +445,7 @@ d[elete] d[display] | delete all auto-display commands(s)
 
 *address* in the above commands can be any numerical value or also the register names prefixed with a \$-sign, e.g., `$pc`. `display/i $pc`, for example, displays after each stop the machine instruction at the location where the program has stopped.
 
-<a name="controlcommands"></a>
-In addition to the commands above, you have to know a few more commands that control the execution of `avr-gdb`.
+<a name="controlcommands"></a>In addition to the commands above, you have to know a few more commands that control the execution of `avr-gdb`.
 
 command | action
 --- | ---
@@ -458,16 +457,15 @@ fil[e] *name*.elf | load the symbol table from the specified ELF file (should be
 lo[ad] | load the ELF file into flash memory (should be done every time after the `target remote` command; it will only change the parts of the flash memory that needs to be changed)
 q[uit] | exit from GDB 
 
-<a name="monitor-commands"></a>
-
-Finally, there are commands that control the settings of the debugger and the MCU, which are particular to dw-link. They all start with the keyword `monitor`.
+<a name="monitor-commands"></a>Finally, there are commands that control the settings of the debugger and the MCU, which are particular to dw-link. They all start with the keyword `monitor`.
 
 command | action
 --- | ---
+mo[nitor] he[lp] | give a help message on monitor commands 
 mo[nitor] dwc[onnect] | establishes the debugWIRE link to the target (is already executed by the `target remote` command); will report MCU type and communication speed (even when already connected)
 mo[nitor] dwo[ff] | disable debugWIRE mode in the target
 mo[nitor] re[set] | resets the MCU
-mo[onitor] er[ase] | erases the flash memory 
+mo[onitor] er[ase] | erases chip (i.e., flash memory, EEPROM, and lock bits) 
 mo[nitor] ck8[prescaler] | program the CKDIV8 fuse (i.e., set MCU clock to 1MHz if running on internal oscillator)
 mo[nitor] ck1[prescaler] | un-program the CKDIV8 fuse (i.e., set MCU to 8MHz if running on internal oscillator)
 mo[nitor] rc[osc] | set clock source to internal RC oscillator
@@ -816,15 +814,33 @@ Something in the `platformio.ini` file is not quite right. Perhaps a missing dec
 
 One common problem is that the debug environment is not the first environment or the default environment. In this case, the wrong environment is used to configure the debug session and probably some environment variables are not set at all or set to the wrong values. So, you need to edit the `platformio.ini` file accordingly.
 
+Another common problem is that the connection to the target cannot be established. If you want to get some diagnostics, you can start `avr-gdb` stand-alone (under Windows search for the program name and then select it for execution). Then type the the following sequence of commands (*serialport* being the serial port to the debugger):
+
+```
+set serial baud 115200
+target remote serialport
+monitor dwconnect
+```
+
+This should show you the connection problem. If the error message is *Connection error: Lock bits are set*, then you can erase the chip by issuing the command `monitor erase`.
+
 #### Problem: When connecting to the target using the *target remote* command, it takes a long time and then you get the message *Remote replied unexpectedly to 'vMustReplyEmpty': timeout*
 
 The serial connection to the hardware debugger could not be established. The most likely reason for that is that there is a mismatch of the bit rates. The Arduino tries out 115200, 230400, 9600, 19200, 38400, and 57600 bps when connecting. If you specified something differently, either as the argument to the `-b` option when starting `avr-gdb` or as an argument to the GDB command `set serial baud ...`, you should change that. 230400 bps works only with the Uno boards. The Arduino Nano cannot  communicate at that speed. 
 
 A further (unlikely) reason might be that a different communication format was chosen (parity, two stop bits, ...). 
 
-#### Problem: It is not possible to connect to an ATmega48 or ATmega88 using the *target remote* command
+#### Problem: In response to the `monitor dwconnect` command, you get the error message *Cannot connect: ...*
+
+Depending on the concrete error message, the problem fix varies.
+
+- *Cannot connect: Check wiring*: The debugger can neither establish an ISP nor debugWIRE connection. Check wiring. It could also be a problem with the RESET line (see [Section 3.3](#section33)).
+- *Cannot connect: Unsupported MCU*: This MCU is not supported by dw-link. It most probably has no debugWIRE connectivity. 
+- *Cannot connect: Lock bits are set*: In this case you need to erase the entire chip before you can debug it. You can do that by issuing `monitor erase`. 
+- *Cannot connect: PC with stuck-at-one bits*: This is most probably an MCU with stuck-at-one bits in the program counter (see [Section 8.9](#section89)). These MCUs cannot be debugged with GDB. 
+- *Cannot connect for unknown reasons:* This error message should not be shown at all. If it does, please tell me!
+
 
-This is most probably an MCU with stuck-at-one bits in the program counter (see [Section 8.9](#section89)). These MCUs cannot be debugged with GDB. 
 
 #### Problem: You receive the message *Protocol error with Rcmd* 
 
@@ -987,3 +1003,12 @@ Initial version
 - Changes in 8.7 
 - Section 9, Problem 'vMustReplyEmpty': timeout - explanation of what problems I encountered
 - Section 5.1-5.3 have been reworked, in particular concerning ATTinyCore 2.0.0 and the new Python script for extending the boards.txt files.
+
+#### V 1.8
+
+- New help command for monitor commands in 5.7
+
+#### V 1.9
+
+- Additional trouble shooting help when lockouts are set
+
diff --git a/docs/manual.pdf b/docs/manual.pdf
diff --git a/dw-link/dw-link.ino b/dw-link/dw-link.ino
@@ -39,7 +39,7 @@
 // For the latter, I experienced non-deterministic failures of unit tests.
 // So, it might be worthwhile to investigate both, but not now.
 
-#define VERSION "1.3.8"
+#define VERSION "1.3.9"
 
 #ifndef NANOVERSION
 #define NANOVERSION 3
@@ -61,6 +61,7 @@
 // #define UNITDW 1           // enable debugWIRE unit tests
 // #define UNITTG 1           // enable target unit tests
 // #define UNITGDB 1          // enable gdb function unit tests
+// #define NOMONINTORHELP 1   // disable monitor help function 
 
 #if UNITALL == 1
 #undef  UNITDW
@@ -958,13 +959,18 @@ void gdbParseMonitorPacket(const byte *buf)
   //DEBPR(F("clen=")); DEBLN(clen);
   //DEBLN((const char *)buf);
 
+
   if (memcmp_P(buf, (void *)PSTR("64776f666600"), max(6,min(12,clen))) == 0)                  
     gdbStop();                                                              /* dwo[ff] */
   else if (memcmp_P(buf, (void *)PSTR("6477636f6e6e65637400"), max(6,min(20,clen))) == 0)
     if (gdbConnect(true)) gdbSendReply("OK");                               /* dwc[onnnect] */
     else gdbSendReply("E03");
+#if NOMONITORHELP == 0
+  else if (memcmp_P(buf, (void *)PSTR("68656c7000"), max(4,min(10,clen))) == 0)                  
+    gdbHelp();                                                              /* he[lp] */
+#endif
   else if (memcmp_P(buf, (void *)PSTR("73657269616c00"), max(6,min(14,clen))) == 0)
-    gdbReportRSPbps();
+    gdbReportRSPbps();                                                       /* serial */
   else if (memcmp_P(buf, (void *)PSTR("666c617368636f756e7400"), max(6,min(22,clen))) == 0)
     gdbReportFlashCount();                                                  /* fla[shcount] */
   else if (memcmp_P(buf, (void *)PSTR("72616d757361676500"), max(6,min(18,clen))) == 0)
@@ -981,8 +987,8 @@ void gdbParseMonitorPacket(const byte *buf)
     gdbSetFuses(CkXtal);                                                     /* xt[alosc] */
   else if (memcmp_P(buf, (void *)PSTR("736c6f776f736300"), max(4,min(16,clen))) == 0)
     gdbSetFuses(CkSlow);                                                     /* sl[owosc] */
-  else if (memcmp_P(buf, (void *)PSTR("6572617365666c61736800"), max(4,min(22,clen))) == 0)
-    gdbSetFuses(Erase);                                                     /*er[aseflash]*/
+  else if (memcmp_P(buf, (void *)PSTR("657261736500"), max(4,min(12,clen))) == 0)
+    gdbSetFuses(Erase);                                                     /*er[ase]*/
   else if (memcmp_P(buf, (void *)PSTR("6877627000"), max(4,min(10,clen))) == 0)
     gdbSetMaxBPs(1);                                                        /* hw[bp] */
   else if (memcmp_P(buf, (void *)PSTR("7377627000"), max(4,min(10,clen))) == 0)
@@ -1021,6 +1027,32 @@ void gdbParseMonitorPacket(const byte *buf)
   } else gdbSendReply("");
 }
 
+// help function (w/o unit tests)
+inline void gdbHelp(void) {
+  gdbDebugMessagePSTR(PSTR("monitor help         - help function"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor dwconnect    - connect to target and show parameters (*)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor dwoff        - disconnect from target and disable DWEN (*)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor eraseflash   - erase flash memory (*)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor reset        - reset target (*)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor ck1prescaler - unprogram CK8DIV (*)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor ck8prescaler - program CK8DIV (*)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor extosc       - use external clock source (*)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor xtalosc      - use XTAL as clock source (*)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor rcosc        - use internal RC oscillator as clock source (*)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor slosc        - use internal 128kHz oscillator as clock source (*)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor swbp         - allow 32 software breakpoints (default)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor hwbp         - allow only 1 breakpoint, i.e., the hardware bp"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor safestep     - prohibit interrupts while single-stepping(default)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor unsafestep   - allow interrupts while single-stepping"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor speed [h|l]  - speed limit is h (=250kbps) (def.) or l (=125kbps)"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor serial       - report host communication speed"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor flashcount   - report number of flash pages written since start"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor timeouts     - report timeouts"), -1);
+  gdbDebugMessagePSTR(PSTR("monitor version      - report version number"), -1);
+  gdbDebugMessagePSTR(PSTR("All commands with (*) lead to a reset of the target"), -1);
+  gdbSendReply("OK");
+}
+
 // return timeout counter
 inline void gdbTimeoutCounter(void)
 {
@@ -1176,7 +1208,7 @@ boolean gdbConnect(boolean verbose)
     switch (conncode) {
     case -1: gdbDebugMessagePSTR(PSTR("Cannot connect: Check wiring"),-1); break;
     case -2: gdbDebugMessagePSTR(PSTR("Cannot connect: Unsupported MCU"),-1); break;
-    case -3: gdbDebugMessagePSTR(PSTR("Cannot connect: Lock bits set"),-1); break;
+    case -3: gdbDebugMessagePSTR(PSTR("Cannot connect: Lock bits are set"),-1); break;
     case -4: gdbDebugMessagePSTR(PSTR("Cannot connect: PC with stuck-at-one bits"),-1); break;
     default: gdbDebugMessagePSTR(PSTR("Cannot connect for unknown reasons"),-1); conncode = -CONNERR_UNKNOWN; break;
     }
@@ -1293,7 +1325,7 @@ void gdbSetFuses(Fuses fuse)
   case CkExt: gdbDebugMessagePSTR(PSTR("Using EXTernal oscillator"),-1); break;
   case CkXtal: gdbDebugMessagePSTR(PSTR("Using XTAL oscillator"),-1); break;
   case CkSlow: gdbDebugMessagePSTR(PSTR("Using 128 kHz oscillator"),-1); break;
-  case Erase: gdbDebugMessagePSTR(PSTR("Flash memory erased"),-1); break;
+  case Erase: gdbDebugMessagePSTR(PSTR("Chip erased"),-1); break;
   default: reportFatalError(WRONG_FUSE_SPEC_FATAL, false); gdbDebugMessagePSTR(PSTR("Fatal Error: Wrong fuse!"),-1); break;
   }
   if (!offline) gdbDebugMessagePSTR(PSTR("Reconnecting ..."),-1);

diff --git a/tests/tests.py b/tests/tests.py
@@ -462,6 +462,6 @@ def run_all_tests(port):
 
 #print(run_script(tictactoe_script, "/dev/cu.usbmodem1442101", "rc", "ck1"))
 
-print(test_mcu("/dev/cu.usbmodem1442101", attiny48))
+#print(test_mcu("/dev/cu.usbmodem1442101", attiny48))
 
-#run_all_tests("/dev/cu.usbmodem1442101")
+run_all_tests("/dev/cu.usbmodem1442101")