Improve defaults and documentation of linuxspi

* avrdude.conf.in: use @HAVE_LINUXGPIO_BEGIN/END@ and
@HAVE_LINUXSPI_BEGIN/END@ brackets around respective config
snippets; values were already set in configure.ac.
* linuxspi.c (linuxspi_open): Provide a reasonable (for the
Raspberry Pi) default for the -P option
* avrdude.1: Extend linuxspi documentation
* doc/avrdude.texi: (Dito.)



git-svn-id: svn://svn.savannah.nongnu.org/avrdude/trunk/avrdude@1496 81a1dc3b-b13d-400b-aceb-764788c761c2

Author: dl8dtl

ChangeLog

@@ -1,3 +1,14 @@
+2021-11-27  Joerg Wunsch <[email protected]>
+
+	Improve defaults and documentation of linuxspi
+	* avrdude.conf.in: use @HAVE_LINUXGPIO_BEGIN/END@ and
+	@HAVE_LINUXSPI_BEGIN/END@ brackets around respective config
+	snippets; values were already set in configure.ac.
+	* linuxspi.c (linuxspi_open): Provide a reasonable (for the
+	Raspberry Pi) default for the -P option
+	* avrdude.1: Extend linuxspi documentation
+	* doc/avrdude.texi: (Dito.)
+
 2021-11-27  Joerg Wunsch <[email protected]>
 
 	Submitted by Alex Sverdlin:

NEWS

@@ -20,6 +20,7 @@ Current:
     - New configure option: -disable-libusb_1_0
     - extended UPDI device context (> 64 Ki flash)
     - major overhaul of ft245r driver (patch #9327/#9328)
+    - some improvements in linuxspi driver
 
   * New devices supported:
 
@@ -122,6 +123,7 @@ Current:
     patch #10029: linuxspi: Report GPIO_GET_LINEHANDLE_IOCTL errors
     patch #10030: linuxspi: Support inverted GPIO pin
     patch #10031: linuxspi: Support GPIO uAPI v2
+    (no-id): Improve documentation of linuxspi driver, provide portname default
 
   * Internals:
     - New avrdude.conf keyword "family_id", used to verify SIB attributes

avrdude.1

@@ -129,13 +129,10 @@ should be connected between the AVR's reset pin and Vcc. If Vcc is not
 the same as the SPI voltage, this should be done on the AVR side of
 the level translator to protect the hardware from damage.
 .Pp
-A commented-out template for this programmer is provided in the
-avrdude configuration file.  To use it, clone that entry into the
-per-user configuration file, and configure the
-.Li reset
-GPIO
-number accordingly. Linuxspi can be used as follows:
-.Dl avrdude -c linuxspi -P /dev/spidev:/dev/gpiochip[:resetpin]
+The
+.Fl P Ar portname
+option for this programmer defaults to
+.Li /dev/spidev0.0:/dev/gpiochip0 .
 .Pp
 Atmel's STK500 programmer is also supported and connects to a serial
 port.

avrdude.conf.in

@@ -1519,6 +1519,7 @@ programmer
 
 @HAVE_PARPORT_END@
 
+@HAVE_LINUXGPIO_BEGIN@
 #This programmer bitbangs GPIO lines using the Linux sysfs GPIO interface
 #
 #To enable it set the configuration below to match the GPIO lines connected to the
@@ -1540,23 +1541,22 @@ programmer
 #  mosi  = ?;
 #  miso  = ?;
 #;
+@HAVE_LINUXGPIO_END@
 
 
+@HAVE_LINUXSPI_BEGIN@
 # This programmer uses the built in linux SPI bus devices to program an
-# attached AVR. A GPIO accessed through the sysfs GPIO interface needs to
-# be specified for a reset pin since the linux SPI userspace functions do
-# not allow for control over the slave select/chip select signal.
+# attached AVR. The reset pin must be attached to a GPIO pin that
+# is otherwise unused (see gpioinfo(1)); the SPI bus CE pins are not
+# suitable since they would release /RESET too early.
 #
-# To use it, copy this snippet into your ~/.avrduderc, make sure the
-# 'reset' entry is configured correctly.
-#
-# programmer
-#   id = "linuxspi";
-#   desc = "Use Linux SPI device in /dev/spidev*";
-#   type = "linuxspi";
-#   reset = 25;
-#   baudrate=400000;
-# ;
+programmer
+   id = "linuxspi";
+   desc = "Use Linux SPI device in /dev/spidev*";
+   type = "linuxspi";
+   reset = 25;    # Pi GPIO number - this is J8:22
+;
+@HAVE_LINUXSPI_END@
 
 # some ultra cheap programmers use bitbanging on the 
 # serialport.

doc/avrdude.texi

@@ -198,14 +198,30 @@ should be connected between the AVR's reset pin and Vcc. If Vcc is not
 the same as the SPI voltage, this should be done on the AVR side of
 the level translator to protect the hardware from damage.
 
-A commented-out template for this programmer is provided in the
-avrdude configuration file.  To use it, clone that entry into the
-per-user configuration file, and configure the @code{reset} GPIO
-number accordingly. Linuxspi can be used as follows:
+On a Raspberry Pi, header J8 provides access to the SPI and GPIO
+lines.
+
+Typically, pins 19, 21, and 23 are SPI MOSI, MISO, and SCK, while
+pins 24 and 26 would serve as CE outputs. So, close to these pins
+is pin 22 as GPIO25 which can be used as /RESET, and pin 25 can
+be used as GND.
+
+A typical programming cable would then look like:
+
+@multitable @columnfractions .15 .15 .3
+@item @code{J8 pin} @tab @code{ISP pin} @tab @code{Name}
+@item @code{21}     @tab @code{1}   @tab @code{MISO}
+@item @code{-}      @tab @code{2}   @tab @code{Vcc - leave open}
+@item @code{23}     @tab @code{3}   @tab @code{SCK}
+@item @code{19}     @tab @code{4}   @tab @code{MOSI}
+@item @code{22}     @tab @code{5}   @tab @code{/RESET}
+@item @code{25}     @tab @code{6}   @tab @code{GND}
+@end multitable
 
-@smallexample
-avrdude -c linuxspi -P /dev/spidev:/dev/gpiochip[:resetpin]
-@end smallexample
+(Mind the 3.3 V voltage level of the Raspberry Pi!)
+
+The @code{-P @var{portname}} option defaults to
+@code{/dev/spidev0.0:/dev/gpiochip0} for this programmer.
 
 The STK500, JTAG ICE, avr910, and avr109/butterfly use the serial port to communicate with the PC.
 The STK600, JTAG ICE mkII/3, AVRISP mkII, USBasp, avrftdi (and derivatives), and USBtinyISP

linuxspi.c

@@ -131,14 +131,16 @@ static int linuxspi_reset_mcu(PROGRAMMER *pgm, bool active)
 
 static int linuxspi_open(PROGRAMMER *pgm, char *port)
 {
-    const char *port_error = "%s: error: Unknown port specification. Please use the format /dev/spidev:/dev/gpiochip[:resetno]\n";
+    const char *port_error =
+      "%s: error: Unknown port specification. "
+      "Please use the format /dev/spidev:/dev/gpiochip[:resetno]\n";
+    char port_default[] = "/dev/spidev0.0:/dev/gpiochip0";
     char *spidev, *gpiochip, *reset_pin;
     struct gpiohandle_request req;
     int ret;
 
-    if (!port || !strcmp(port, "unknown")) {
-        avrdude_message(MSG_INFO, "%s: error: No port specified. Port should point to an spidev device.\n", progname);
-        return -1;
+    if (!strcmp(port, "unknown")) {
+        port = port_default;
     }
 
     spidev = strtok(port, ":");