docs: serial: convert docs to ReST and rename to *.rst

The converted files are focused at the Kernel internal API,
so, this is a good candidate for the kernel API set of books.

The conversion is actually:
  - add blank lines and identation in order to identify paragraphs;
  - fix tables markups;
  - add some lists markups;
  - mark literal blocks;
  - adjust title markups.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

Documentation/serial/README.cycladesZ → Documentation/serial/cyclades_z.rst

+================
+Cyclades-Z notes
+================
 
 The Cyclades-Z must have firmware loaded onto the card before it will
 operate.  This operation should be performed during system startup,
 
 The firmware, loader program and the latest device driver code are
 available from Cyclades at
-    ftp://ftp.cyclades.com/pub/cyclades/cyclades-z/linux/
 
+    ftp://ftp.cyclades.com/pub/cyclades/cyclades-z/linux/

Documentation/serial/driver → Documentation/serial/driver.rst

-
-			Low Level Serial API
-			--------------------
+====================
+Low Level Serial API
+====================
 
 
 This document is meant as a brief overview of some aspects of the new serial
@@ -44,7 +44,7 @@ are described in the uart_ops listing below.)
 There are two locks.  A per-port spinlock, and an overall semaphore.
 
 From the core driver perspective, the port->lock locks the following
-data:
+data::
 
 	port->mctrl
 	port->icount
@@ -75,41 +75,51 @@ hardware.
 	return TIOCSER_TEMT.
 
 	Locking: none.
+
 	Interrupts: caller dependent.
+
 	This call must not sleep
 
   set_mctrl(port, mctrl)
 	This function sets the modem control lines for port described
 	by 'port' to the state described by mctrl.  The relevant bits
 	of mctrl are:
+
 		- TIOCM_RTS	RTS signal.
 		- TIOCM_DTR	DTR signal.
 		- TIOCM_OUT1	OUT1 signal.
 		- TIOCM_OUT2	OUT2 signal.
 		- TIOCM_LOOP	Set the port into loopback mode.
+
 	If the appropriate bit is set, the signal should be driven
 	active.  If the bit is clear, the signal should be driven
 	inactive.
 
 	Locking: port->lock taken.
+
 	Interrupts: locally disabled.
+
 	This call must not sleep
 
   get_mctrl(port)
 	Returns the current state of modem control inputs.  The state
 	of the outputs should not be returned, since the core keeps
 	track of their state.  The state information should include:
+
 		- TIOCM_CAR	state of DCD signal
 		- TIOCM_CTS	state of CTS signal
 		- TIOCM_DSR	state of DSR signal
 		- TIOCM_RI	state of RI signal
+
 	The bit is set if the signal is currently driven active.  If
 	the port does not support CTS, DCD or DSR, the driver should
 	indicate that the signal is permanently active.  If RI is
 	not available, the signal should not be indicated as active.
 
 	Locking: port->lock taken.
+
 	Interrupts: locally disabled.
+
 	This call must not sleep
 
   stop_tx(port)
@@ -121,14 +131,18 @@ hardware.
 	possible.
 
 	Locking: port->lock taken.
+
 	Interrupts: locally disabled.
+
 	This call must not sleep
 
   start_tx(port)
 	Start transmitting characters.
 
 	Locking: port->lock taken.
+
 	Interrupts: locally disabled.
+
 	This call must not sleep
 
   throttle(port)
@@ -144,6 +158,7 @@ hardware.
 	Notify the serial driver that characters can now be sent to the serial
 	port without fear of overrunning the input buffers of the line
 	disciplines.
+
 	This will be called only if hardware assisted flow control is enabled.
 
 	Locking: serialized with .throttle() and termios modification by the
@@ -159,6 +174,7 @@ hardware.
 	Do not transmit if ch == '\0' (__DISABLED_CHAR).
 
 	Locking: none.
+
 	Interrupts: caller dependent.
 
   stop_rx(port)
@@ -166,7 +182,9 @@ hardware.
 	being closed.
 
 	Locking: port->lock taken.
+
 	Interrupts: locally disabled.
+
 	This call must not sleep
 
   enable_ms(port)
@@ -177,7 +195,9 @@ hardware.
 	called.
 
 	Locking: port->lock taken.
+
 	Interrupts: locally disabled.
+
 	This call must not sleep
 
   break_ctl(port,ctl)
@@ -196,6 +216,7 @@ hardware.
 	This method will only be called when the port is initially opened.
 
 	Locking: port_sem taken.
+
 	Interrupts: globally disabled.
 
   shutdown(port)
@@ -210,6 +231,7 @@ hardware.
 	this port.
 
 	Locking: port_sem taken.
+
 	Interrupts: caller dependent.
 
   flush_buffer(port)
@@ -220,7 +242,9 @@ hardware.
 	buffer is cleared.
 
 	Locking: port->lock taken.
+
 	Interrupts: locally disabled.
+
 	This call must not sleep
 
   set_termios(port,termios,oldtermios)
@@ -228,29 +252,46 @@ hardware.
 	bits.  Update read_status_mask and ignore_status_mask to indicate
 	the types of events we are interested in receiving.  Relevant
 	termios->c_cflag bits are:
-		CSIZE	- word size
-		CSTOPB	- 2 stop bits
-		PARENB	- parity enable
-		PARODD	- odd parity (when PARENB is in force)
-		CREAD	- enable reception of characters (if not set,
+
+		CSIZE
+			- word size
+		CSTOPB
+			- 2 stop bits
+		PARENB
+			- parity enable
+		PARODD
+			- odd parity (when PARENB is in force)
+		CREAD
+			- enable reception of characters (if not set,
 			  still receive characters from the port, but
 			  throw them away.
-		CRTSCTS	- if set, enable CTS status change reporting
-		CLOCAL	- if not set, enable modem status change
+		CRTSCTS
+			- if set, enable CTS status change reporting
+		CLOCAL
+			- if not set, enable modem status change
 			  reporting.
+
 	Relevant termios->c_iflag bits are:
-		INPCK	- enable frame and parity error events to be
+
+		INPCK
+			- enable frame and parity error events to be
 			  passed to the TTY layer.
-		BRKINT
-		PARMRK	- both of these enable break events to be
+		BRKINT / PARMRK
+			- both of these enable break events to be
 			  passed to the TTY layer.
 
-		IGNPAR	- ignore parity and framing errors
-		IGNBRK	- ignore break errors,  If IGNPAR is also
+		IGNPAR
+			- ignore parity and framing errors
+		IGNBRK
+			- ignore break errors,  If IGNPAR is also
 			  set, ignore overrun errors as well.
+
 	The interaction of the iflag bits is as follows (parity error
 	given as an example):
+
+	=============== ======= ======  =============================
 	Parity error	INPCK	IGNPAR
+	=============== ======= ======  =============================
 	n/a		0	n/a	character received, marked as
 					TTY_NORMAL
 	None		1	n/a	character received, marked as
@@ -258,16 +299,19 @@ hardware.
 	Yes		1	0	character received, marked as
 					TTY_PARITY
 	Yes		1	1	character discarded
+	=============== ======= ======  =============================
 
 	Other flags may be used (eg, xon/xoff characters) if your
 	hardware supports hardware "soft" flow control.
 
 	Locking: caller holds tty_port->mutex
+
 	Interrupts: caller dependent.
+
 	This call must not sleep
 
   set_ldisc(port,termios)
-	Notifier for discipline change. See Documentation/serial/tty.txt.
+	Notifier for discipline change. See Documentation/serial/tty.rst.
 
 	Locking: caller holds tty_port->mutex
 
@@ -283,6 +327,7 @@ hardware.
 	will occur even if CONFIG_PM is not set.
 
 	Locking: none.
+
 	Interrupts: caller dependent.
 
   type(port)
@@ -291,6 +336,7 @@ hardware.
 	substituted.
 
 	Locking: none.
+
 	Interrupts: caller dependent.
 
   release_port(port)
@@ -298,6 +344,7 @@ hardware.
 	the port.
 
 	Locking: none.
+
 	Interrupts: caller dependent.
 
   request_port(port)
@@ -306,6 +353,7 @@ hardware.
 	returns, and it should return -EBUSY on failure.
 
 	Locking: none.
+
 	Interrupts: caller dependent.
 
   config_port(port,type)
@@ -321,6 +369,7 @@ hardware.
 	internally hard wired (eg, system on a chip implementations).
 
 	Locking: none.
+
 	Interrupts: caller dependent.
 
   verify_port(port,serinfo)
@@ -328,6 +377,7 @@ hardware.
 	suitable for this port type.
 
 	Locking: none.
+
 	Interrupts: caller dependent.
 
   ioctl(port,cmd,arg)
@@ -335,6 +385,7 @@ hardware.
 	using the standard numbering system found in <asm/ioctl.h>
 
 	Locking: none.
+
 	Interrupts: caller dependent.
 
   poll_init(port)
@@ -343,6 +394,7 @@ hardware.
 	this should not request interrupts.
 
 	Locking: tty_mutex and tty_port->mutex taken.
+
 	Interrupts: n/a.
 
   poll_put_char(port,ch)
@@ -350,7 +402,9 @@ hardware.
 	port.  It can and should block until there is space in the TX FIFO.
 
 	Locking: none.
+
 	Interrupts: caller dependent.
+
 	This call must not sleep
 
   poll_get_char(port)
@@ -359,7 +413,9 @@ hardware.
 	the function should return NO_POLL_CHAR immediately.
 
 	Locking: none.
+
 	Interrupts: caller dependent.
+
 	This call must not sleep
 
 Other functions
@@ -370,6 +426,7 @@ uart_update_timeout(port,cflag,baud)
 	number of bits, parity, stop bits and baud rate.
 
 	Locking: caller is expected to take port->lock
+
 	Interrupts: n/a
 
 uart_get_baud_rate(port,termios,old,min,max)
@@ -385,6 +442,7 @@ uart_get_baud_rate(port,termios,old,min,max)
 	Note: min..max must always allow 9600 baud to be selected.
 
 	Locking: caller dependent.
+
 	Interrupts: n/a
 
 uart_get_divisor(port,baud)
@@ -395,6 +453,7 @@ uart_get_divisor(port,baud)
 	custom divisor instead.
 
 	Locking: caller dependent.
+
 	Interrupts: n/a
 
 uart_match_port(port1,port2)
@@ -402,6 +461,7 @@ uart_match_port(port1,port2)
 	uart_port structures describe the same port.
 
 	Locking: n/a
+
 	Interrupts: n/a
 
 uart_write_wakeup(port)
@@ -409,6 +469,7 @@ uart_write_wakeup(port)
 	characters in the transmit buffer have dropped below a threshold.
 
 	Locking: port->lock should be held.
+
 	Interrupts: n/a
 
 uart_register_driver(drv)
@@ -419,6 +480,7 @@ uart_register_driver(drv)
 	registered using uart_add_one_port after this call has succeeded.
 
 	Locking: none
+
 	Interrupts: enabled
 
 uart_unregister_driver()
@@ -427,15 +489,16 @@ uart_unregister_driver()
 	uart_remove_one_port() if it registered them with uart_add_one_port().
 
 	Locking: none
+
 	Interrupts: enabled
 
-uart_suspend_port()
+**uart_suspend_port()**
 
-uart_resume_port()
+**uart_resume_port()**
 
-uart_add_one_port()
+**uart_add_one_port()**
 
-uart_remove_one_port()
+**uart_remove_one_port()**
 
 Other notes
 -----------
@@ -444,7 +507,7 @@ It is intended some day to drop the 'unused' entries from uart_port, and
 allow low level drivers to register their own individual uart_port's with
 the core.  This will allow drivers to use uart_port as a pointer to a
 structure containing both the uart_port entry with their own extensions,
-thus:
+thus::
 
 	struct my_port {
 		struct uart_port	port;
@@ -459,14 +522,14 @@ Some helpers are provided in order to set/get modem control lines via GPIO.
 mctrl_gpio_init(port, idx):
 	This will get the {cts,rts,...}-gpios from device tree if they are
 	present and request them, set direction etc, and return an
-	allocated structure. devm_* functions are used, so there's no need
+	allocated structure. `devm_*` functions are used, so there's no need
 	to call mctrl_gpio_free().
 	As this sets up the irq handling make sure to not handle changes to the
 	gpio input lines in your driver, too.
 
 mctrl_gpio_free(dev, gpios):
 	This will free the requested gpios in mctrl_gpio_init().
-	As devm_* functions are used, there's generally no need to call
+	As `devm_*` functions are used, there's generally no need to call
 	this function.
 
 mctrl_gpio_to_gpiod(gpios, gidx)

Documentation/serial/index.rst

+:orphan:
+
+==========================
+Support for Serial devices
+==========================
+
+.. toctree::
+    :maxdepth: 1
+
+
+    driver
+    tty
+
+Serial drivers
+==============
+
+.. toctree::
+    :maxdepth: 1
+
+    cyclades_z
+    moxa-smartio
+    n_gsm
+    rocket
+    serial-iso7816
+    serial-rs485
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`

Documentation/serial/n_gsm.txt → Documentation/serial/n_gsm.rst

-n_gsm.c GSM 0710 tty multiplexor HOWTO
-===================================================
+==============================
+GSM 0710 tty multiplexor HOWTO
+==============================
 
 This line discipline implements the GSM 07.10 multiplexing protocol
-detailed in the following 3GPP document :
-http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
+detailed in the following 3GPP document:
+
+	http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
 
 This document give some hints on how to use this driver with GPRS and 3G
 modems connected to a physical serial port.
 
 How to use it
 -------------
-1- initialize the modem in 0710 mux mode (usually AT+CMUX= command) through
-its serial port. Depending on the modem used, you can pass more or less
-parameters to this command,
-2- switch the serial line to using the n_gsm line discipline by using
-TIOCSETD ioctl,
-3- configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl,
+1. initialize the modem in 0710 mux mode (usually AT+CMUX= command) through
+   its serial port. Depending on the modem used, you can pass more or less
+   parameters to this command,
+2. switch the serial line to using the n_gsm line discipline by using
+   TIOCSETD ioctl,
+3. configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl,
 
 Major parts of the initialization program :
-(a good starting point is util-linux-ng/sys-utils/ldattach.c)
-#include <linux/gsmmux.h>
-#define N_GSM0710	21	/* GSM 0710 Mux */
-#define DEFAULT_SPEED	B115200
-#define SERIAL_PORT	/dev/ttyS0
+(a good starting point is util-linux-ng/sys-utils/ldattach.c)::
+
+  #include <linux/gsmmux.h>
+  #define N_GSM0710	21	/* GSM 0710 Mux */
+  #define DEFAULT_SPEED	B115200
+  #define SERIAL_PORT	/dev/ttyS0
 
 	int ldisc = N_GSM0710;
 	struct gsm_config c;
@@ -60,37 +63,41 @@ Major parts of the initialization program :
 	daemon(0,0);
 	pause();
 
-4- create the devices corresponding to the "virtual" serial ports (take care,
-each modem has its configuration and some DLC have dedicated functions,
-for example GPS), starting with minor 1 (DLC0 is reserved for the management
-of the mux)
+4. create the devices corresponding to the "virtual" serial ports (take care,
+   each modem has its configuration and some DLC have dedicated functions,
+   for example GPS), starting with minor 1 (DLC0 is reserved for the management
+   of the mux)::
 
-MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}`
-for i in `seq 1 4`; do
+     MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}`
+     for i in `seq 1 4`; do
 	mknod /dev/ttygsm$i c $MAJOR $i
-done
+     done
+
+5. use these devices as plain serial ports.
 
-5- use these devices as plain serial ports.
-for example, it's possible :
-- and to use gnokii to send / receive SMS on ttygsm1
-- to use ppp to establish a datalink on ttygsm2
+   for example, it's possible:
 
-6- first close all virtual ports before closing the physical port.
+   - and to use gnokii to send / receive SMS on ttygsm1
+   - to use ppp to establish a datalink on ttygsm2
 
-Note that after closing the physical port the modem is still in multiplexing
-mode. This may prevent a successful re-opening of the port later. To avoid
-this situation either reset the modem if your hardware allows that or send
-a disconnect command frame manually before initializing the multiplexing mode
-for the second time. The byte sequence for the disconnect command frame is:
-0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9.
+6. first close all virtual ports before closing the physical port.
+
+   Note that after closing the physical port the modem is still in multiplexing
+   mode. This may prevent a successful re-opening of the port later. To avoid
+   this situation either reset the modem if your hardware allows that or send
+   a disconnect command frame manually before initializing the multiplexing mode
+   for the second time. The byte sequence for the disconnect command frame is::
+
+      0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9.
 
 Additional Documentation
 ------------------------
 More practical details on the protocol and how it's supported by industrial
 modems can be found in the following documents :
-http://www.telit.com/module/infopool/download.php?id=616
-http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf
-http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx
-http://wm.sim.com/sim/News/photo/2010721161442.pdf
+
+- http://www.telit.com/module/infopool/download.php?id=616
+- http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf
+- http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx
+- http://wm.sim.com/sim/News/photo/2010721161442.pdf
 
 11-03-08 - Eric Bénard - <eric@eukrea.com>

Documentation/serial/rocket.txt → Documentation/serial/rocket.rst

+================================================
 Comtrol(tm) RocketPort(R)/RocketModem(TM) Series
-Device Driver for the Linux Operating System
+================================================
 
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+Device Driver for the Linux Operating System
+============================================
 
-PRODUCT OVERVIEW
+Product overview
 ----------------
 
 This driver provides a loadable kernel driver for the Comtrol RocketPort
@@ -29,22 +31,24 @@ information on how to set the DIP switches.
 
 You pass the I/O port to the driver using the following module parameters:
 
-board1 :	I/O port for the first ISA board
-board2 :	I/O port for the second ISA board
-board3 :	I/O port for the third ISA board
-board4 :	I/O port for the fourth ISA board
+board1:
+	I/O port for the first ISA board
+board2:
+	I/O port for the second ISA board
+board3:
+	I/O port for the third ISA board
+board4:
+	I/O port for the fourth ISA board
 
 There is a set of utilities and scripts provided with the external driver
-( downloadable from http://www.comtrol.com ) that ease the configuration and
+(downloadable from http://www.comtrol.com) that ease the configuration and
 setup of the ISA cards.
 
 The RocketModem II PCI boards require firmware to be loaded into the card
 before it will function.  The driver has only been tested as a module for this
 board.
 
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
-INSTALLATION PROCEDURES
+Installation Procedures
 -----------------------
 
 RocketPort/RocketModem PCI cards require no driver configuration, they are
@@ -62,24 +66,24 @@ in the system log at /var/log/messages.
 
 If installed as a module, the module must be loaded.  This can be done
 manually by entering "modprobe rocket".  To have the module loaded automatically
-upon system boot, edit a /etc/modprobe.d/*.conf file and add the line
+upon system boot, edit a `/etc/modprobe.d/*.conf` file and add the line
 "alias char-major-46 rocket".
 
 In order to use the ports, their device names (nodes) must be created with mknod.
 This is only required once, the system will retain the names once created.  To
 create the RocketPort/RocketModem device names, use the command
-"mknod /dev/ttyRx c 46 x" where x is the port number starting at zero.  For example:
+"mknod /dev/ttyRx c 46 x" where x is the port number starting at zero.
 
->mknod /dev/ttyR0 c 46 0
->mknod /dev/ttyR1 c 46 1
->mknod /dev/ttyR2 c 46 2  
+For example::
 
-The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes)
-for you:
+	> mknod /dev/ttyR0 c 46 0
+	> mknod /dev/ttyR1 c 46 1
+	> mknod /dev/ttyR2 c 46 2
 
->/dev/MAKEDEV ttyR
+The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes)
+for you::
 
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+	>/dev/MAKEDEV ttyR
 
 ISA Rocketport Boards
 ---------------------
@@ -89,7 +93,7 @@ card before installing and using it.  This is done by setting a set of DIP
 switches on the Rocketport board.
 
 
-SETTING THE I/O ADDRESS
+Setting the I/O address
 -----------------------
 
 Before installing RocketPort(R) or RocketPort RA boards, you must find
@@ -130,9 +134,7 @@ the first 4 bytes of that range are used by the first board.  You would
 need to set the second, third, or fourth board to one of the next available
 blocks such as 0x180.
 
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
-RocketPort and RocketPort RA SW1 Settings:
+RocketPort and RocketPort RA SW1 Settings::
 
             +-------------------------------+
             | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
@@ -140,30 +142,28 @@ RocketPort and RocketPort RA SW1 Settings:
             | Unused| Card  | I/O Port Block|
             +-------------------------------+
 
-DIP Switches                             DIP Switches
-7    8                                   6    5
-===================                      ===================
-On   On   UNUSED, MUST BE ON.            On   On   First Card    <==== Default
+  DIP Switches                             DIP Switches
+  7    8                                   6    5
+  ===================                      ===================
+  On   On   UNUSED, MUST BE ON.            On   On   First Card    <==== Default
                                            On   Off  Second Card
                                            Off  On   Third Card
                                            Off  Off  Fourth Card
 
-DIP Switches         I/O Address Range
-4    3    2    1     Used by the First Card
-=====================================
-On   Off  On   Off   100-143
-On   Off  Off  On    140-183
-On   Off  Off  Off   180-1C3       <==== Default
-Off  On   On   Off   200-243
-Off  On   Off  On    240-283
-Off  On   Off  Off   280-2C3
-Off  Off  On   Off   300-343
-Off  Off  Off  On    340-383
-Off  Off  Off  Off   380-3C3
-
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
-REPORTING BUGS
+  DIP Switches         I/O Address Range
+  4    3    2    1     Used by the First Card
+  =====================================
+  On   Off  On   Off   100-143
+  On   Off  Off  On    140-183
+  On   Off  Off  Off   180-1C3       <==== Default
+  Off  On   On   Off   200-243
+  Off  On   Off  On    240-283
+  Off  On   Off  Off   280-2C3
+  Off  Off  On   Off   300-343
+  Off  Off  Off  On    340-383
+  Off  Off  Off  Off   380-3C3
+
+Reporting Bugs
 --------------
 
 For technical support, please provide the following
@@ -171,19 +171,15 @@ information: Driver version, kernel release, distribution of
 kernel, and type of board you are using. Error messages and log
 printouts port configuration details are especially helpful.
 
-USA
-    Phone: (612) 494-4100
-      FAX: (612) 494-4199
-    email: support@comtrol.com
+USA:
+    :Phone: (612) 494-4100
+    :FAX: (612) 494-4199
+    :email: support@comtrol.com
 
-Comtrol Europe
-    Phone: +44 (0) 1 869 323-220
-      FAX: +44 (0) 1 869 323-211
-    email: support@comtrol.co.uk
+Comtrol Europe:
+    :Phone: +44 (0) 1 869 323-220
+    :FAX: +44 (0) 1 869 323-211
+    :email: support@comtrol.co.uk
 
 Web:	http://www.comtrol.com
 FTP:	ftp.comtrol.com
-
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
-

Documentation/serial/serial-iso7816.txt → Documentation/serial/serial-iso7816.rst

-                        ISO7816 SERIAL COMMUNICATIONS
+=============================
+ISO7816 Serial Communications
+=============================
 
-1. INTRODUCTION
+1. Introduction
+===============
 
   ISO/IEC7816 is a series of standards specifying integrated circuit cards (ICC)
   also known as smart cards.
 
-2. HARDWARE-RELATED CONSIDERATIONS
+2. Hardware-related considerations
+==================================
 
   Some CPUs/UARTs (e.g., Microchip AT91) contain a built-in mode capable of
   handling communication with a smart card.
@@ -15,7 +19,8 @@
   available at user-level to allow switching from one mode to the other, and
   vice versa.
 
-3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL
+3. Data Structures Already Available in the Kernel
+==================================================
 
   The Linux kernel provides the serial_iso7816 structure (see [1]) to handle
   ISO7816 communications. This data structure is used to set and configure
@@ -27,10 +32,11 @@
   to TIOCGISO7816 and TIOCSISO7816 ioctls (see below). The iso7816_config
   callback receives a pointer to struct serial_iso7816.
 
-4. USAGE FROM USER-LEVEL
+4. Usage from user-level
+========================
 
   From user-level, ISO7816 configuration can be get/set using the previous
-  ioctls. For instance, to set ISO7816 you can use the following code:
+  ioctls. For instance, to set ISO7816 you can use the following code::
 
 	#include <linux/serial.h>
 
@@ -78,6 +84,7 @@
 		/* Error handling. See errno. */
 	}
 
-5. REFERENCES
+5. References
+=============
 
  [1]    include/uapi/linux/serial.h

Documentation/serial/serial-rs485.txt → Documentation/serial/serial-rs485.rst

-                        RS485 SERIAL COMMUNICATIONS
+===========================
+RS485 Serial Communications
+===========================
 
-1. INTRODUCTION
+1. Introduction
+===============
 
    EIA-485, also known as TIA/EIA-485 or RS-485, is a standard defining the
    electrical characteristics of drivers and receivers for use in balanced
@@ -9,7 +12,8 @@
    because it can be used effectively over long distances and in electrically
    noisy environments.
 
-2. HARDWARE-RELATED CONSIDERATIONS
+2. Hardware-related Considerations
+==================================
 
    Some CPUs/UARTs (e.g., Atmel AT91 or 16C950 UART) contain a built-in
    half-duplex mode capable of automatically controlling line direction by
@@ -22,7 +26,8 @@
    available at user-level to allow switching from one mode to the other, and
    vice versa.
 
-3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL
+3. Data Structures Already Available in the Kernel
+==================================================
 
    The Linux kernel provides the serial_rs485 structure (see [1]) to handle
    RS485 communications. This data structure is used to set and configure RS485
@@ -38,10 +43,11 @@
    to TIOCSRS485 and TIOCGRS485 ioctls (see below). The rs485_config callback
    receives a pointer to struct serial_rs485.
 
-4. USAGE FROM USER-LEVEL
+4. Usage from user-level
+========================
 
    From user-level, RS485 configuration can be get/set using the previous
-   ioctls. For instance, to set RS485 you can use the following code:
+   ioctls. For instance, to set RS485 you can use the following code::
 
 	#include <linux/serial.h>
 
@@ -89,7 +95,9 @@
 		/* Error handling. See errno. */
 	}
 
-5. REFERENCES
+5. References
+=============
 
  [1]	include/uapi/linux/serial.h
+
  [2]	Documentation/devicetree/bindings/serial/rs485.txt

MAINTAINERS

@@ -10433,7 +10433,7 @@ F:	include/uapi/linux/meye.h
 MOXA SMARTIO/INDUSTIO/INTELLIO SERIAL CARD
 M:	Jiri Slaby <jirislaby@gmail.com>
 S:	Maintained
-F:	Documentation/serial/moxa-smartio
+F:	Documentation/serial/moxa-smartio.rst
 F:	drivers/tty/mxser.*
 
 MR800 AVERMEDIA USB FM RADIO DRIVER
@@ -13317,7 +13317,7 @@ ROCKETPORT DRIVER
 P:	Comtrol Corp.
 W:	http://www.comtrol.com
 S:	Maintained
-F:	Documentation/serial/rocket.txt
+F:	Documentation/serial/rocket.rst
 F:	drivers/tty/rocket*
 
 ROCKETPORT EXPRESS/INFINITY DRIVER

drivers/tty/Kconfig

@@ -175,7 +175,7 @@ config ROCKETPORT
 	  This driver supports Comtrol RocketPort and RocketModem PCI boards.   
           These boards provide 2, 4, 8, 16, or 32 high-speed serial ports or
           modems.  For information about the RocketPort/RocketModem  boards
-          and this driver read <file:Documentation/serial/rocket.txt>.
+          and this driver read <file:Documentation/serial/rocket.rst>.
 
 	  To compile this driver as a module, choose M here: the
 	  module will be called rocket.
@@ -193,7 +193,7 @@ config CYCLADES
 	  your Linux box, for instance in order to become a dial-in server.
 
 	  For information about the Cyclades-Z card, read
-	  <file:Documentation/serial/README.cycladesZ>.
+	  <file:Documentation/serial/cyclades_z.rst>.
 
 	  To compile this driver as a module, choose M here: the
 	  module will be called cyclades.

drivers/tty/serial/ucc_uart.c

@@ -1081,7 +1081,7 @@ static int qe_uart_verify_port(struct uart_port *port,
 }
 /* UART operations
  *
- * Details on these functions can be found in Documentation/serial/driver
+ * Details on these functions can be found in Documentation/serial/driver.rst
  */
 static const struct uart_ops qe_uart_pops = {
 	.tx_empty       = qe_uart_tx_empty,

include/linux/serial_core.h

@@ -45,7 +45,7 @@ struct device;
 
 /*
  * This structure describes all the operations that can be done on the
- * physical hardware.  See Documentation/serial/driver for details.
+ * physical hardware.  See Documentation/serial/driver.rst for details.
  */
 struct uart_ops {
 	unsigned int	(*tx_empty)(struct uart_port *);