spi: docs: convert to ReST and add it to the kABI bookset

While there's one file there with briefily describes the uAPI,
the documentation was written just like most subsystems: focused
on kernel developers. So, add it together with driver-api books.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> # for iio
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/index.rst

@@ -116,6 +116,7 @@ needed).
    power/index
    target/index
    timers/index
+   spi/index
    watchdog/index
    virtual/index
    input/index

Documentation/spi/butterfly → Documentation/spi/butterfly.rst

+===================================================
 spi_butterfly - parport-to-butterfly adapter driver
 ===================================================
 
@@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP"
 connector pins (used also on non-Butterfly AVR boards).  On the parport
 side this is like "sp12" programming cables.
 
+	======	  =============	  ===================
 	Signal	  Butterfly	  Parport (DB-25)
-	------	  ---------	  ---------------
-	SCK	= J403.PB1/SCK	= pin 2/D0
-	RESET	= J403.nRST	= pin 3/D1
-	VCC	= J403.VCC_EXT	= pin 8/D6
-	MOSI	= J403.PB2/MOSI	= pin 9/D7
-	MISO	= J403.PB3/MISO	= pin 11/S7,nBUSY
-	GND	= J403.GND	= pin 23/GND
+	======	  =============	  ===================
+	SCK	  J403.PB1/SCK	  pin 2/D0
+	RESET	  J403.nRST	  pin 3/D1
+	VCC	  J403.VCC_EXT	  pin 8/D6
+	MOSI	  J403.PB2/MOSI	  pin 9/D7
+	MISO	  J403.PB3/MISO	  pin 11/S7,nBUSY
+	GND	  J403.GND	  pin 23/GND
+	======	  =============	  ===================
 
 Then to let Linux master that bus to talk to the DataFlash chip, you must
 (a) flash new firmware that disables SPI (set PRR.2, and disable pullups
 by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
 (c) cable in the chipselect.
 
+	======	  ============	  ===================
 	Signal	  Butterfly	  Parport (DB-25)
-	------	  ---------	  ---------------
-	VCC	= J400.VCC_EXT	= pin 7/D5
-	SELECT	= J400.PB0/nSS	= pin 17/C3,nSELECT
-	GND	= J400.GND	= pin 24/GND
+	======	  ============	  ===================
+	VCC	  J400.VCC_EXT	  pin 7/D5
+	SELECT	  J400.PB0/nSS	  pin 17/C3,nSELECT
+	GND	  J400.GND	  pin 24/GND
+	======	  ============	  ===================
 
 Or you could flash firmware making the AVR into an SPI slave (keeping the
 DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
@@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware,
 while letting either Linux or the AVR use the DataFlash.  There are plenty
 of spare parport pins to wire this one up, such as:
 
+	======	  =============	  ===================
 	Signal	  Butterfly	  Parport (DB-25)
-	------	  ---------	  ---------------
-	SCK	= J403.PE4/USCK	= pin 5/D3
-	MOSI	= J403.PE5/DI	= pin 6/D4
-	MISO	= J403.PE6/DO	= pin 12/S5,nPAPEROUT
-	GND	= J403.GND	= pin 22/GND
-
-	IRQ	= J402.PF4	= pin 10/S6,ACK
-	GND	= J402.GND(P2)	= pin 25/GND
+	======	  =============	  ===================
+	SCK	  J403.PE4/USCK	  pin 5/D3
+	MOSI	  J403.PE5/DI	  pin 6/D4
+	MISO	  J403.PE6/DO	  pin 12/S5,nPAPEROUT
+	GND	  J403.GND	  pin 22/GND
 
+	IRQ	  J402.PF4	  pin 10/S6,ACK
+	GND	  J402.GND(P2)	  pin 25/GND
+	======	  =============	  ===================

Documentation/spi/index.rst

+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Serial Peripheral Interface (SPI)
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   spi-summary
+   spidev
+   butterfly
+   pxa2xx
+   spi-lm70llp
+   spi-sc18is602
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`

Documentation/spi/pxa2xx → Documentation/spi/pxa2xx.rst

+==============================
 PXA2xx SPI on SSP driver HOWTO
-===================================================
+==============================
+
 This a mini howto on the pxa2xx_spi driver.  The driver turns a PXA2xx
 synchronous serial port into a SPI master controller
-(see Documentation/spi/spi-summary). The driver has the following features
+(see Documentation/spi/spi-summary.rst). The driver has the following features
 
 - Support for any PXA2xx SSP
 - SSP PIO and SSP DMA data transfers.
@@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers
 -----------------------------------
 Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
 "platform device".  The master configuration is passed to the driver via a table
-found in include/linux/spi/pxa2xx_spi.h:
+found in include/linux/spi/pxa2xx_spi.h::
 
-struct pxa2xx_spi_controller {
+  struct pxa2xx_spi_controller {
 	u16 num_chipselect;
 	u8 enable_dma;
-};
+  };
 
 The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
 slave device (chips) attached to this SPI master.
@@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller".
 
 NSSP MASTER SAMPLE
 ------------------
-Below is a sample configuration using the PXA255 NSSP.
+Below is a sample configuration using the PXA255 NSSP::
 
-static struct resource pxa_spi_nssp_resources[] = {
+  static struct resource pxa_spi_nssp_resources[] = {
 	[0] = {
 		.start	= __PREG(SSCR0_P(2)), /* Start address of NSSP */
 		.end	= __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
@@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = {
 		.end	= IRQ_NSSP,
 		.flags	= IORESOURCE_IRQ,
 	},
-};
+  };
 
-static struct pxa2xx_spi_controller pxa_nssp_master_info = {
+  static struct pxa2xx_spi_controller pxa_nssp_master_info = {
 	.num_chipselect = 1, /* Matches the number of chips attached to NSSP */
 	.enable_dma = 1, /* Enables NSSP DMA */
-};
+  };
 
-static struct platform_device pxa_spi_nssp = {
+  static struct platform_device pxa_spi_nssp = {
 	.name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
 	.id = 2, /* Bus number, MUST MATCH SSP number 1..n */
 	.resource = pxa_spi_nssp_resources,
@@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = {
 	.dev = {
 		.platform_data = &pxa_nssp_master_info, /* Passed to driver */
 	},
-};
+  };
 
-static struct platform_device *devices[] __initdata = {
+  static struct platform_device *devices[] __initdata = {
 	&pxa_spi_nssp,
-};
+  };
 
-static void __init board_init(void)
-{
+  static void __init board_init(void)
+  {
 	(void)platform_add_device(devices, ARRAY_SIZE(devices));
-}
+  }
 
 Declaring Slave Devices
 -----------------------
 Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
 using the "spi_board_info" structure found in "linux/spi/spi.h". See
-"Documentation/spi/spi-summary" for additional information.
+"Documentation/spi/spi-summary.rst" for additional information.
 
 Each slave device attached to the PXA must provide slave specific configuration
 information via the structure "pxa2xx_spi_chip" found in
@@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in
 will uses the configuration whenever the driver communicates with the slave
 device. All fields are optional.
 
-struct pxa2xx_spi_chip {
+::
+
+  struct pxa2xx_spi_chip {
 	u8 tx_threshold;
 	u8 rx_threshold;
 	u8 dma_burst_size;
 	u32 timeout;
 	u8 enable_loopback;
 	void (*cs_control)(u32 command);
-};
+  };
 
 The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
 used to configure the SSP hardware fifo.  These fields are critical to the
 performance of pxa2xx_spi driver and misconfiguration will result in rx
-fifo overruns (especially in PIO mode transfers). Good default values are
+fifo overruns (especially in PIO mode transfers). Good default values are::
 
 	.tx_threshold = 8,
 	.rx_threshold = 8,
@@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
 "spi_board_info.controller_data" field. Below is a sample configuration using
 the PXA255 NSSP.
 
-/* Chip Select control for the CS8415A SPI slave device */
-static void cs8415a_cs_control(u32 command)
-{
+::
+
+  /* Chip Select control for the CS8415A SPI slave device */
+  static void cs8415a_cs_control(u32 command)
+  {
 	if (command & PXA2XX_CS_ASSERT)
 		GPCR(2) = GPIO_bit(2);
 	else
 		GPSR(2) = GPIO_bit(2);
-}
+  }
 
-/* Chip Select control for the CS8405A SPI slave device */
-static void cs8405a_cs_control(u32 command)
-{
+  /* Chip Select control for the CS8405A SPI slave device */
+  static void cs8405a_cs_control(u32 command)
+  {
 	if (command & PXA2XX_CS_ASSERT)
 		GPCR(3) = GPIO_bit(3);
 	else
 		GPSR(3) = GPIO_bit(3);
-}
+  }
 
-static struct pxa2xx_spi_chip cs8415a_chip_info = {
+  static struct pxa2xx_spi_chip cs8415a_chip_info = {
 	.tx_threshold = 8, /* SSP hardward FIFO threshold */
 	.rx_threshold = 8, /* SSP hardward FIFO threshold */
 	.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
 	.timeout = 235, /* See Intel documentation */
 	.cs_control = cs8415a_cs_control, /* Use external chip select */
-};
+  };
 
-static struct pxa2xx_spi_chip cs8405a_chip_info = {
+  static struct pxa2xx_spi_chip cs8405a_chip_info = {
 	.tx_threshold = 8, /* SSP hardward FIFO threshold */
 	.rx_threshold = 8, /* SSP hardward FIFO threshold */
 	.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
 	.timeout = 235, /* See Intel documentation */
 	.cs_control = cs8405a_cs_control, /* Use external chip select */
-};
+  };
 
-static struct spi_board_info streetracer_spi_board_info[] __initdata = {
+  static struct spi_board_info streetracer_spi_board_info[] __initdata = {
 	{
 		.modalias = "cs8415a", /* Name of spi_driver for this device */
 		.max_speed_hz = 3686400, /* Run SSP as fast a possbile */
@@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
 		.controller_data = &cs8405a_chip_info, /* Master chip config */
 		.irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
 	},
-};
+  };
 
-static void __init streetracer_init(void)
-{
+  static void __init streetracer_init(void)
+  {
 	spi_register_board_info(streetracer_spi_board_info,
 				ARRAY_SIZE(streetracer_spi_board_info));
-}
+  }
 
 
 DMA and PIO I/O Support
@@ -210,26 +216,25 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure.  The
 mode supports both coherent and stream based DMA mappings.
 
 The following logic is used to determine the type of I/O to be used on
-a per "spi_transfer" basis:
+a per "spi_transfer" basis::
 
-if !enable_dma then
+  if !enable_dma then
 	always use PIO transfers
 
-if spi_message.len > 8191 then
+  if spi_message.len > 8191 then
 	print "rate limited" warning
 	use PIO transfers
 
-if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
+  if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
 	use coherent DMA mode
 
-if rx_buf and tx_buf are aligned on 8 byte boundary then
+  if rx_buf and tx_buf are aligned on 8 byte boundary then
 	use streaming DMA mode
 
-otherwise
+  otherwise
 	use PIO transfer
 
 THANKS TO
 ---------
 
 David Brownell and others for mentoring the development of this driver.
-

Documentation/spi/spi-lm70llp → Documentation/spi/spi-lm70llp.rst

+==============================================
 spi_lm70llp :  LM70-LLP parport-to-SPI adapter
 ==============================================
 
 Supported board/chip:
+
   * National Semiconductor LM70 LLP evaluation board
+
     Datasheet: http://www.national.com/pf/LM/LM70.html
 
 Author:
@@ -29,9 +32,10 @@ available (on page 4) here:
 
 The hardware interfacing on the LM70 LLP eval board is as follows:
 
+   ======== == =========   ==========
    Parallel                 LM70 LLP
-     Port      Direction   JP2 Header
-   ----------- --------- ----------------
+     Port   .  Direction   JP2 Header
+   ======== == =========   ==========
       D0     2      -         -
       D1     3     -->      V+   5
       D2     4     -->      V+   5
@@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows:
       D7     9     -->      SI/O 5
      GND    25      -       GND  7
     Select  13     <--      SI/O 1
-   ----------- --------- ----------------
+   ======== == =========   ==========
 
 Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
 is connected to both pin D7 (as Master Out) and Select (as Master In)
@@ -74,6 +78,7 @@ inverting the value read at pin 13.
 
 Thanks to
 ---------
-o David Brownell for mentoring the SPI-side driver development.
-o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
-o Nadir Billimoria for help interpreting the circuit schematic.
+
+- David Brownell for mentoring the SPI-side driver development.
+- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
+- Nadir Billimoria for help interpreting the circuit schematic.

Documentation/spi/spi-sc18is602 → Documentation/spi/spi-sc18is602.rst

+===========================
 Kernel driver spi-sc18is602
 ===========================
 
 Supported chips:
+
   * NXP SI18IS602/602B/603
+
     Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
 
 Author:

Documentation/spi/spidev → Documentation/spi/spidev.rst

+=================
+SPI userspace API
+=================
+
 SPI devices have a limited userspace API, supporting basic half-duplex
 read() and write() access to SPI slave devices.  Using ioctl() requests,
 full duplex transfers and device I/O configuration are also available.
 
+::
+
 	#include <fcntl.h>
 	#include <unistd.h>
 	#include <sys/ioctl.h>
@@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
 busybox; it's less featureful, but often enough.)  For a SPI device with
 chipselect C on bus B, you should see:
 
-    /dev/spidevB.C ... character special device, major number 153 with
+    /dev/spidevB.C ...
+	character special device, major number 153 with
 	a dynamically chosen minor device number.  This is the node
 	that userspace programs will open, created by "udev" or "mdev".
 
-    /sys/devices/.../spiB.C ... as usual, the SPI device node will
+    /sys/devices/.../spiB.C ...
+	as usual, the SPI device node will
 	be a child of its SPI master controller.
 
-    /sys/class/spidev/spidevB.C ... created when the "spidev" driver
+    /sys/class/spidev/spidevB.C ...
+	created when the "spidev" driver
 	binds to that device.  (Directory or symlink, based on whether
 	or not you enabled the "deprecated sysfs files" Kconfig option.)
 
@@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
 Several ioctl() requests let your driver read or override the device's current
 settings for data transfer parameters:
 
-    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
+    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
+	pass a pointer to a byte which will
 	return (RD) or assign (WR) the SPI transfer mode.  Use the constants
 	SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
 	(clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
@@ -88,22 +98,26 @@ settings for data transfer parameters:
 	Note that this request is limited to SPI mode flags that fit in a
 	single byte.
 
-    SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
+    SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
+	pass a pointer to a uin32_t
 	which will return (RD) or assign (WR) the full SPI transfer mode,
 	not limited to the bits that fit in one byte.
 
-    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
+    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
+	pass a pointer to a byte
 	which will return (RD) or assign (WR) the bit justification used to
 	transfer SPI words.  Zero indicates MSB-first; other values indicate
 	the less common LSB-first encoding.  In both cases the specified value
 	is right-justified in each word, so that unused (TX) or undefined (RX)
 	bits are in the MSBs.
 
-    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
+    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
+	pass a pointer to
 	a byte which will return (RD) or assign (WR) the number of bits in
 	each SPI transfer word.  The value zero signifies eight bits.
 
-    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
+    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
+	pass a pointer to a
 	u32 which will return (RD) or assign (WR) the maximum SPI transfer
 	speed, in Hz.  The controller can't necessarily assign that specific
 	clock speed.

drivers/iio/dummy/iio_simple_dummy.c

@@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
  * i2c:
  * Documentation/i2c/writing-clients.rst
  * spi:
- * Documentation/spi/spi-summary
+ * Documentation/spi/spi-summary.rst
  */
 static const struct iio_sw_device_ops iio_dummy_device_ops = {
 	.probe = iio_dummy_probe,

drivers/spi/Kconfig

@@ -543,7 +543,7 @@ config SPI_PXA2XX
 	help
 	  This enables using a PXA2xx or Sodaville SSP port as a SPI master
 	  controller. The driver can be configured to use any SSP port and
-	  additional documentation can be found a Documentation/spi/pxa2xx.
+	  additional documentation can be found a Documentation/spi/pxa2xx.rst.
 
 config SPI_PXA2XX_PCI
 	def_tristate SPI_PXA2XX && PCI && COMMON_CLK

drivers/spi/spi-butterfly.c

@@ -23,7 +23,7 @@
  * with a battery powered AVR microcontroller and lots of goodies.  You
  * can use GCC to develop firmware for this.
  *
- * See Documentation/spi/butterfly for information about how to build
+ * See Documentation/spi/butterfly.rst for information about how to build
  * and use this custom parallel port cable.
  */
 

drivers/spi/spi-lm70llp.c

@@ -34,7 +34,7 @@
  * available (on page 4) here:
  *  http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
  *
- * Also see Documentation/spi/spi-lm70llp.  The SPI<->parport code here is
+ * Also see Documentation/spi/spi-lm70llp.rst.  The SPI<->parport code here is
  * (heavily) based on spi-butterfly by David Brownell.
  *
  * The LM70 LLP connects to the PC parallel port in the following manner:

include/linux/platform_data/sc18is602.h

@@ -4,7 +4,7 @@
  *
  * Copyright (C) 2012 Guenter Roeck <linux@roeck-us.net>
  *
- * For further information, see the Documentation/spi/spi-sc18is602 file.
+ * For further information, see the Documentation/spi/spi-sc18is602.rst file.
  */
 
 /**