docs: w1: convert to ReST and add to the kAPI group of docs

The 1wire documentation was written with w1 developers in
mind, so, it makes sense to add it together with the driver-api
set.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/ABI/stable/sysfs-bus-w1

@@ -6,6 +6,6 @@ Description:	Bus scanning interval, microseconds component.
 		control systems are attached/generate presence for as short as
 		100 ms - hence the tens-to-hundreds milliseconds scan intervals
 		are required.
-		see Documentation/w1/w1.generic for detailed information.
+		see Documentation/w1/w1-generic.rst for detailed information.
 Users:		any user space application which wants to know bus scanning
 		interval

Documentation/ABI/stable/sysfs-driver-w1_ds28e04

@@ -2,7 +2,7 @@ What:		/sys/bus/w1/devices/.../pio
 Date:		May 2012
 Contact:	Markus Franke <franm@hrz.tu-chemnitz.de>
 Description:	read/write the contents of the two PIO's of the DS28E04-100
-		see Documentation/w1/slaves/w1_ds28e04 for detailed information
+		see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
 Users:		any user space application which wants to communicate with DS28E04-100
 
 
@@ -11,5 +11,5 @@ What:		/sys/bus/w1/devices/.../eeprom
 Date:		May 2012
 Contact:	Markus Franke <franm@hrz.tu-chemnitz.de>
 Description:	read/write the contents of the EEPROM memory of the DS28E04-100
-		see Documentation/w1/slaves/w1_ds28e04 for detailed information
+		see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
 Users:		any user space application which wants to communicate with DS28E04-100

Documentation/ABI/stable/sysfs-driver-w1_ds28ea00

@@ -2,5 +2,5 @@ What:		/sys/bus/w1/devices/.../w1_seq
 Date:		Apr 2015
 Contact:	Matt Campbell <mattrcampbell@gmail.com>
 Description:	Support for the DS28EA00 chain sequence function
-		see Documentation/w1/slaves/w1_therm for detailed information
+		see Documentation/w1/slaves/w1_therm.rst for detailed information
 Users:		any user space application which wants to communicate with DS28EA00

Documentation/index.rst

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

Documentation/w1/index.rst

@@ -0,0 +1,21 @@
+. SPDX-License-Identifier: GPL-2.0
+
+================
+1-Wire Subsystem
+================
+
+.. toctree::
+   :maxdepth: 1
+
+
+   w1-generic.rst
+   w1-netlink.rst
+   masters/index
+   slaves/index
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`

Documentation/w1/masters/ds2482.rst

@@ -1,13 +1,19 @@
+====================
 Kernel driver ds2482
 ====================
 
 Supported chips:
+
   * Maxim DS2482-100, Maxim DS2482-800
+
     Prefix: 'ds2482'
+
     Addresses scanned: None
+
     Datasheets:
-        http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
-        http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
+
+        - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
+        - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
 
 Author: Ben Gardner <bgardner@wabtec.com>
 
@@ -23,9 +29,11 @@ General Remarks
 ---------------
 
 Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
+
 However, the device cannot be detected without writing to the i2c bus, so no
 detection is done. You should instantiate the device explicitly.
 
-$ modprobe ds2482
-$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
+::
 
+  $ modprobe ds2482
+  $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device

Documentation/w1/masters/ds2490.rst

@@ -1,7 +1,9 @@
+====================
 Kernel driver ds2490
 ====================
 
 Supported chips:
+
   * Maxim DS2490 based
 
 Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
@@ -18,6 +20,7 @@ which has 0x81 family ID integrated chip and DS2490
 low-level operational chip.
 
 Notes and limitations.
+
 - The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
 - The 5V strong pullup is supported with a minimum of 5.9mA and a
   maximum of 30.4 mA.  (From DS2490.pdf)
@@ -65,4 +68,5 @@ Notes and limitations.
   reattaching would clear the problem.  usbmon output in the guest and
   host did not explain the problem.  My guess is a bug in either qemu
   or the host OS and more likely the host OS.
--- 03-06-2008 David Fries <David@Fries.net>
+
+03-06-2008 David Fries <David@Fries.net>

Documentation/w1/masters/index.rst

@@ -0,0 +1,14 @@
+. SPDX-License-Identifier: GPL-2.0
+
+=====================
+1-wire Master Drivers
+=====================
+
+.. toctree::
+   :maxdepth: 1
+
+   ds2482
+   ds2490
+   mxc-w1
+   omap-hdq
+   w1-gpio

Documentation/w1/masters/mxc-w1

@@ -1,12 +0,0 @@
-Kernel driver mxc_w1
-====================
-
-Supported chips:
-  * Freescale MX27, MX31 and probably other i.MX SoCs
-    Datasheets:
-        http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
-	http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=
-	Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
-
-Author: Originally based on Freescale code, prepared for mainline by
-	Sascha Hauer <s.hauer@pengutronix.de>

Documentation/w1/masters/mxc-w1.rst

@@ -0,0 +1,17 @@
+====================
+Kernel driver mxc_w1
+====================
+
+Supported chips:
+
+  * Freescale MX27, MX31 and probably other i.MX SoCs
+
+    Datasheets:
+
+        - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
+	- http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
+
+Author:
+
+	Originally based on Freescale code, prepared for mainline by
+	Sascha Hauer <s.hauer@pengutronix.de>

Documentation/w1/masters/omap-hdq.rst

@@ -1,9 +1,10 @@
-Kernel driver for omap HDQ/1-wire module.
+========================================
+Kernel driver for omap HDQ/1-wire module
 ========================================
 
 Supported chips:
 ================
-	HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
+HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
 
 A useful link about HDQ basics:
 ===============================
@@ -40,9 +41,10 @@ driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1.
 Please note to load both the modules with a different ID if required, but note
 that the ID used should be same for both master and slave driver loading.
 
-e.g:
-insmod omap_hdq.ko W1_ID=2
-inamod w1_bq27000.ko F_ID=2
+e.g::
+
+  insmod omap_hdq.ko W1_ID=2
+  inamod w1_bq27000.ko F_ID=2
 
 The driver also supports 1-wire mode. In this mode, there is no need to
 pass slave ID as parameter. The driver will auto-detect slaves connected

Documentation/w1/masters/w1-gpio.rst

@@ -1,3 +1,4 @@
+=====================
 Kernel driver w1-gpio
 =====================
 
@@ -16,28 +17,30 @@ Documentation/devicetree/bindings/w1/w1-gpio.txt
 Example (mach-at91)
 -------------------
 
-#include <linux/gpio/machine.h>
-#include <linux/w1-gpio.h>
+::
 
-static struct gpiod_lookup_table foo_w1_gpiod_table = {
+  #include <linux/gpio/machine.h>
+  #include <linux/w1-gpio.h>
+
+  static struct gpiod_lookup_table foo_w1_gpiod_table = {
 	.dev_id = "w1-gpio",
 	.table = {
 		GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
 			GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
 	},
-};
+  };
 
-static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
+  static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
 	.ext_pullup_enable_pin	= -EINVAL,
-};
+  };
 
-static struct platform_device foo_w1_device = {
+  static struct platform_device foo_w1_device = {
 	.name			= "w1-gpio",
 	.id			= -1,
 	.dev.platform_data	= &foo_w1_gpio_pdata,
-};
+  };
 
-...
+  ...
 	at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
 	at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
 	gpiod_add_lookup_table(&foo_w1_gpiod_table);

Documentation/w1/slaves/index.rst

@@ -0,0 +1,16 @@
+. SPDX-License-Identifier: GPL-2.0
+
+====================
+1-wire Slave Drivers
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   w1_ds2406
+   w1_ds2413
+   w1_ds2423
+   w1_ds2438
+   w1_ds28e04
+   w1_ds28e17
+   w1_therm

Documentation/w1/slaves/w1_ds2406.rst

@@ -1,7 +1,9 @@
+=======================
 w1_ds2406 kernel driver
 =======================
 
 Supported chips:
+
   * Maxim DS2406 (and other family 0x12) addressable switches
 
 Author: Scott Alfter <scott@alfter.us>
@@ -9,7 +11,7 @@ Author: Scott Alfter <scott@alfter.us>
 Description
 -----------
 
-The w1_ds2406 driver allows connected devices to be switched on and off. 
+The w1_ds2406 driver allows connected devices to be switched on and off.
 These chips also provide 128 bytes of OTP EPROM, but reading/writing it is
 not supported.  In TSOC-6 form, the DS2406 provides two switch outputs and
 can be provided with power on a dedicated input.  In TO-92 form, it provides

Documentation/w1/slaves/w1_ds2413.rst

@@ -1,11 +1,16 @@
+=======================
 Kernel driver w1_ds2413
 =======================
 
 Supported chips:
+
   * Maxim DS2413 1-Wire Dual Channel Addressable Switch
 
 supported family codes:
+
+        ================        ====
         W1_FAMILY_DS2413        0x3A
+        ================        ====
 
 Author: Mariusz Bialonczyk <manio@skyboo.net>
 
@@ -20,11 +25,13 @@ Reading state
 The "state" file provides one-byte value which is in the same format as for
 the chip PIO_ACCESS_READ command (refer the datasheet for details):
 
+======== =============================================================
 Bit 0:   PIOA Pin State
 Bit 1:   PIOA Output Latch State
 Bit 2:   PIOB Pin State
 Bit 3:   PIOB Output Latch State
 Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+======== =============================================================
 
 This file is readonly.
 
@@ -34,9 +41,11 @@ You can set the PIO pins using the "output" file.
 It is writable, you can write one-byte value to this sysfs file.
 Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
 
+======== ======================================
 Bit 0:   PIOA
 Bit 1:   PIOB
 Bit 2-7: No matter (driver will set it to "1"s)
+======== ======================================
 
 
 The chip has some kind of basic protection against transmission errors.

Documentation/w1/slaves/w1_ds2423

@@ -1,47 +0,0 @@
-Kernel driver w1_ds2423
-=======================
-
-Supported chips:
-  * Maxim DS2423 based counter devices.
-
-supported family codes:
-	W1_THERM_DS2423	0x1D
-
-Author: Mika Laitio <lamikr@pilppa.org>
-
-Description
------------
-
-Support is provided through the sysfs w1_slave file. Each opening and
-read sequence of w1_slave file initiates the read of counters and ram
-available in DS2423 pages 12 - 15.
-
-Result of each page is provided as an ASCII output where each counter
-value and associated ram buffer is outpputed to own line.
-
-Each lines will contain the values of 42 bytes read from the counter and
-memory page along the crc=YES or NO for indicating whether the read operation
-was successful and CRC matched.
-If the operation was successful, there is also in the end of each line
-a counter value expressed as an integer after c=
-
-Meaning of 42 bytes represented is following:
- - 1 byte from ram page
- - 4 bytes for the counter value
- - 4 zero bytes
- - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
- - 31 remaining bytes from the ram page
- - crc=YES/NO indicating whether read was ok and crc matched
- - c=<int> current counter value
-
-example from the successful read:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
-00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
-
-example from the read with crc errors:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO

Documentation/w1/slaves/w1_ds2423.rst

@@ -0,0 +1,54 @@
+Kernel driver w1_ds2423
+=======================
+
+Supported chips:
+
+  * Maxim DS2423 based counter devices.
+
+supported family codes:
+
+        ===============	====
+	W1_THERM_DS2423	0x1D
+        ===============	====
+
+Author: Mika Laitio <lamikr@pilppa.org>
+
+Description
+-----------
+
+Support is provided through the sysfs w1_slave file. Each opening and
+read sequence of w1_slave file initiates the read of counters and ram
+available in DS2423 pages 12 - 15.
+
+Result of each page is provided as an ASCII output where each counter
+value and associated ram buffer is outpputed to own line.
+
+Each lines will contain the values of 42 bytes read from the counter and
+memory page along the crc=YES or NO for indicating whether the read operation
+was successful and CRC matched.
+If the operation was successful, there is also in the end of each line
+a counter value expressed as an integer after c=
+
+Meaning of 42 bytes represented is following:
+
+ - 1 byte from ram page
+ - 4 bytes for the counter value
+ - 4 zero bytes
+ - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
+ - 31 remaining bytes from the ram page
+ - crc=YES/NO indicating whether read was ok and crc matched
+ - c=<int> current counter value
+
+example from the successful read::
+
+  00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+  00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+  00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
+  00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+
+example from the read with crc errors::
+
+  00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+  00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+  00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+  00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO

Documentation/w1/slaves/w1_ds2438.rst

@@ -2,10 +2,13 @@ Kernel driver w1_ds2438
 =======================
 
 Supported chips:
+
   * Maxim DS2438 Smart Battery Monitor
 
 supported family codes:
+        ================        ====
         W1_FAMILY_DS2438        0x26
+        ================        ====
 
 Author: Mariusz Bialonczyk <manio@skyboo.net>
 
@@ -56,8 +59,11 @@ Opening and reading this file initiates the CONVERT_V (voltage conversion)
 command of the chip.
 
 Depending on a sysfs filename a different input for the A/D will be selected:
-vad: general purpose A/D input (VAD)
-vdd: battery input (VDD)
+
+vad:
+    general purpose A/D input (VAD)
+vdd:
+    battery input (VDD)
 
 After the voltage conversion the value is returned as decimal ASCII.
 Note: To get a volts the value has to be divided by 100.

Documentation/w1/slaves/w1_ds28e04.rst

@@ -1,11 +1,16 @@
+========================
 Kernel driver w1_ds28e04
 ========================
 
 Supported chips:
+
   * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
 
 supported family codes:
+
+        =================	====
 	W1_FAMILY_DS28E04	0x1C
+        =================	====
 
 Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
 

Documentation/w1/slaves/w1_ds28e17.rst

@@ -1,11 +1,16 @@
+========================
 Kernel driver w1_ds28e17
 ========================
 
 Supported chips:
+
   * Maxim DS28E17 1-Wire-to-I2C Master Bridge
 
 supported family codes:
+
+        =================  ====
 	W1_FAMILY_DS28E17  0x19
+        =================  ====
 
 Author: Jan Kandziora <jjj@gmx.de>
 
@@ -20,11 +25,11 @@ a DS28E17 can be accessed by the kernel or userspace tools as if they were
 connected to a "native" I2C bus master.
 
 
-An udev rule like the following
--------------------------------------------------------------------------------
-SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
-        SYMLINK+="i2c-$attr{name}"
--------------------------------------------------------------------------------
+An udev rule like the following::
+
+  SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
+          SYMLINK+="i2c-$attr{name}"
+
 may be used to create stable /dev/i2c- entries based on the unique id of the
 DS28E17 chip.
 
@@ -65,4 +70,3 @@ structure is created.
 
 
 See https://github.com/ianka/w1_ds28e17 for even more information.
-