Merge pull request #1139 from steelman/isp-clock-error-message

Mention -B in the error message and document -F better

src/avrdude.1

@@ -507,6 +507,8 @@ actual connection to a target controller), this option can be used
 together with
 .Fl t
 to continue in terminal mode.
+Moreover, the option allows to continue despite failed initialization
+of connection between a programmer and a target.
 .It Fl i Ar delay
 For bitbang-type programmers, delay for approximately
 .Ar delay

src/doc/avrdude.texi

@@ -598,6 +598,8 @@ Also, for programmers like the Atmel STK500 and STK600 which can
 adjust parameters local to the programming tool (independent of an
 actual connection to a target controller), this option can be used
 together with @option{-t} to continue in terminal mode.
+Moreover, the option allows to continue despite failed initialization
+of connection between a programmer and a target.
 
 @item -i @var{delay}
 For bitbang-type programmers, delay for approximately
@@ -3047,14 +3049,15 @@ See also: @url{http://www.libusb.org/ticket/6}
 @item
 Problem: after flashing a firmware that reduces the target's clock
 speed (e.g. through the @code{CLKPR} register), further ISP connection
-attempts fail.
+attempts fail.  Or a programmer cannot initialize communication with
+a brand new chip.
 
 Solution: Even though ISP starts with pulling @var{/RESET} low, the
-target continues to run at the internal clock speed as defined by the
-firmware running before.  Therefore, the ISP clock speed must be
-reduced appropriately (to less than 1/4 of the internal clock speed)
-using the -B option before the ISP initialization sequence will
-succeed.
+target continues to run at the internal clock speed either as defined by
+the firmware running before or as set by the factory.  Therefore, the
+ISP clock speed must be reduced appropriately (to less than 1/4 of the
+internal clock speed) using the -B option before the ISP initialization
+sequence will succeed.
 
 As that slows down the entire subsequent ISP session, it might make
 sense to just issue a @emph{chip erase} using the slow ISP clock

src/main.c

@@ -1220,9 +1220,10 @@ int main(int argc, char * argv [])
   init_ok = (rc = pgm->initialize(pgm, p)) >= 0;
   if (!init_ok) {
     pmsg_error("initialization failed, rc=%d\n", rc);
+    imsg_error("- double check the connections and try again\n");
+    imsg_error("- use -B to set lower ISP clock frequency, e.g. -B 200kHz\n");
     if (!ovsigck) {
-      imsg_error("double check connections and try again or use -F to override\n");
-      imsg_error("this check\n\n");
+      imsg_error("- use -F to override this check\n\n");
       exitrc = 1;
       goto main_exit;
     }