[PATCH 0/6] tty: Documentation moves and updates.

[PATCH 0/6] tty: Documentation moves and updates.

[Jiri Slaby]

This moves tty to driver-api, move more tty documents there and updates
them. Either to use ReST properly or update so that they correspond to
the current state.

Jiri Slaby (6):
  Documentation: move tty to driver-api
  Documentation: tty: introduce "Other Documentation"
  Documentation: tty: move n_gsm to tty
  Documentation: tty: move moxa-smartio.rst to tty
  Documentation: tty: n_gsm, delete "Additional Documentation"
  Documentation: tty: n_gsm, use power of ReST

 Documentation/driver-api/index.rst            |   1 +
 Documentation/driver-api/serial/driver.rst    |   2 +-
 Documentation/driver-api/serial/index.rst     |   2 -
 Documentation/driver-api/serial/n_gsm.rst     | 159 ------------------
 Documentation/{ => driver-api}/tty/index.rst  |  22 ++-
 .../{serial => tty}/moxa-smartio.rst          |   0
 Documentation/driver-api/tty/n_gsm.rst        | 153 +++++++++++++++++
 Documentation/{ => driver-api}/tty/n_tty.rst  |   0
 .../{ => driver-api}/tty/tty_buffer.rst       |   0
 .../{ => driver-api}/tty/tty_driver.rst       |   0
 .../{ => driver-api}/tty/tty_internals.rst    |   0
 .../{ => driver-api}/tty/tty_ldisc.rst        |   0
 .../{ => driver-api}/tty/tty_port.rst         |   0
 .../{ => driver-api}/tty/tty_struct.rst       |   0
 Documentation/index.rst                       |   1 -
 15 files changed, 171 insertions(+), 169 deletions(-)
 delete mode 100644 Documentation/driver-api/serial/n_gsm.rst
 rename Documentation/{ => driver-api}/tty/index.rst (81%)
 rename Documentation/driver-api/{serial => tty}/moxa-smartio.rst (100%)
 create mode 100644 Documentation/driver-api/tty/n_gsm.rst
 rename Documentation/{ => driver-api}/tty/n_tty.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_buffer.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_driver.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_internals.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_ldisc.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_port.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_struct.rst (100%)

-- 
2.35.1

[PATCH 1/6] Documentation: move tty to driver-api

[Jiri Slaby]

Based on discussion starting as 87mthw2o93.fsf@meer.lwn.net, let's move
the tty documentation to driver-api. It's more appropriate there.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/driver-api/index.rst                   | 1 +
 Documentation/driver-api/serial/driver.rst           | 2 +-
 Documentation/{ => driver-api}/tty/index.rst         | 9 ++++-----
 Documentation/{ => driver-api}/tty/n_tty.rst         | 0
 Documentation/{ => driver-api}/tty/tty_buffer.rst    | 0
 Documentation/{ => driver-api}/tty/tty_driver.rst    | 0
 Documentation/{ => driver-api}/tty/tty_internals.rst | 0
 Documentation/{ => driver-api}/tty/tty_ldisc.rst     | 0
 Documentation/{ => driver-api}/tty/tty_port.rst      | 0
 Documentation/{ => driver-api}/tty/tty_struct.rst    | 0
 Documentation/index.rst                              | 1 -
 11 files changed, 6 insertions(+), 7 deletions(-)
 rename Documentation/{ => driver-api}/tty/index.rst (86%)
 rename Documentation/{ => driver-api}/tty/n_tty.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_buffer.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_driver.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_internals.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_ldisc.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_port.rst (100%)
 rename Documentation/{ => driver-api}/tty/tty_struct.rst (100%)

diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index a7b0223e2886..bbbbcf20b7ce 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -101,6 +101,7 @@ available subsections can be seen below.
    surface_aggregator/index
    switchtec
    sync_file
+   tty
    vfio-mediated-device
    vfio
    vfio-pci-device-specific-driver-acceptance
diff --git a/Documentation/driver-api/serial/driver.rst b/Documentation/driver-api/serial/driver.rst
index 7dc3791addeb..3c2d12acfd54 100644
--- a/Documentation/driver-api/serial/driver.rst
+++ b/Documentation/driver-api/serial/driver.rst
@@ -339,7 +339,7 @@ hardware.
 	This call must not sleep
 
   set_ldisc(port,termios)
-	Notifier for discipline change. See Documentation/tty/tty_ldisc.rst.
+	Notifier for discipline change. See ../tty/tty_ldisc.rst.
 
 	Locking: caller holds tty_port->mutex
 
diff --git a/Documentation/tty/index.rst b/Documentation/driver-api/tty/index.rst
similarity index 86%
rename from Documentation/tty/index.rst
rename to Documentation/driver-api/tty/index.rst
index 21ea0cb21e55..2240e52203d6 100644
--- a/Documentation/tty/index.rst
+++ b/Documentation/driver-api/tty/index.rst
@@ -43,11 +43,10 @@ Writing TTY Driver
 ==================
 
 Before one starts writing a TTY driver, they must consider
-:doc:`Serial <../driver-api/serial/driver>` and :doc:`USB Serial
-<../usb/usb-serial>` layers
-first. Drivers for serial devices can often use one of these specific layers to
-implement a serial driver. Only special devices should be handled directly by
-the TTY Layer. If you are about to write such a driver, read on.
+:doc:`Serial <../serial/driver>` and :doc:`USB Serial <../../usb/usb-serial>`
+layers first. Drivers for serial devices can often use one of these specific
+layers to implement a serial driver. Only special devices should be handled
+directly by the TTY Layer. If you are about to write such a driver, read on.
 
 A *typical* sequence a TTY driver performs is as follows:
 
diff --git a/Documentation/tty/n_tty.rst b/Documentation/driver-api/tty/n_tty.rst
similarity index 100%
rename from Documentation/tty/n_tty.rst
rename to Documentation/driver-api/tty/n_tty.rst
diff --git a/Documentation/tty/tty_buffer.rst b/Documentation/driver-api/tty/tty_buffer.rst
similarity index 100%
rename from Documentation/tty/tty_buffer.rst
rename to Documentation/driver-api/tty/tty_buffer.rst
diff --git a/Documentation/tty/tty_driver.rst b/Documentation/driver-api/tty/tty_driver.rst
similarity index 100%
rename from Documentation/tty/tty_driver.rst
rename to Documentation/driver-api/tty/tty_driver.rst
diff --git a/Documentation/tty/tty_internals.rst b/Documentation/driver-api/tty/tty_internals.rst
similarity index 100%
rename from Documentation/tty/tty_internals.rst
rename to Documentation/driver-api/tty/tty_internals.rst
diff --git a/Documentation/tty/tty_ldisc.rst b/Documentation/driver-api/tty/tty_ldisc.rst
similarity index 100%
rename from Documentation/tty/tty_ldisc.rst
rename to Documentation/driver-api/tty/tty_ldisc.rst
diff --git a/Documentation/tty/tty_port.rst b/Documentation/driver-api/tty/tty_port.rst
similarity index 100%
rename from Documentation/tty/tty_port.rst
rename to Documentation/driver-api/tty/tty_port.rst
diff --git a/Documentation/tty/tty_struct.rst b/Documentation/driver-api/tty/tty_struct.rst
similarity index 100%
rename from Documentation/tty/tty_struct.rst
rename to Documentation/driver-api/tty/tty_struct.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index ee639a500278..71cc2d1f35f2 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -138,7 +138,6 @@ needed).
    misc-devices/index
    scheduler/index
    mhi/index
-   tty/index
    peci/index
 
 Architecture-agnostic documentation
-- 
2.35.1

[PATCH 2/6] Documentation: tty: introduce "Other Documentation"

[Jiri Slaby]

So far only n_tty belongs here, but in the next patches, more will come.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
---
 Documentation/driver-api/tty/index.rst | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Documentation/driver-api/tty/index.rst b/Documentation/driver-api/tty/index.rst
index 2240e52203d6..e6a7f717a9a5 100644
--- a/Documentation/driver-api/tty/index.rst
+++ b/Documentation/driver-api/tty/index.rst
@@ -36,7 +36,6 @@ In-detail description of the named TTY structures is in separate documents:
    tty_struct
    tty_ldisc
    tty_buffer
-   n_tty
    tty_internals
 
 Writing TTY Driver
@@ -60,3 +59,13 @@ A *typical* sequence a TTY driver performs is as follows:
 Steps regarding driver, i.e. 1., 3., and 5. are described in detail in
 :doc:`tty_driver`. For the other two (devices handling), look into
 :doc:`tty_port`.
+
+Other Documentation
+===================
+
+Miscellaneous documentation can be further found in these documents:
+
+.. toctree::
+   :maxdepth: 2
+
+   n_tty
-- 
2.35.1

[PATCH 3/6] Documentation: tty: move n_gsm to tty

[Jiri Slaby]

We have n_tty documented in Documentation/driver-api/tty/. n_gsm belongs
there too, so move from serial/ to tty/ too.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
---
 Documentation/driver-api/serial/index.rst          | 1 -
 Documentation/driver-api/tty/index.rst             | 1 +
 Documentation/driver-api/{serial => tty}/n_gsm.rst | 0
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename Documentation/driver-api/{serial => tty}/n_gsm.rst (100%)

diff --git a/Documentation/driver-api/serial/index.rst b/Documentation/driver-api/serial/index.rst
index 7eb21a695fc3..4ebdb86cd6b6 100644
--- a/Documentation/driver-api/serial/index.rst
+++ b/Documentation/driver-api/serial/index.rst
@@ -17,7 +17,6 @@ Serial drivers
     :maxdepth: 1
 
     moxa-smartio
-    n_gsm
     serial-iso7816
     serial-rs485
 
diff --git a/Documentation/driver-api/tty/index.rst b/Documentation/driver-api/tty/index.rst
index e6a7f717a9a5..85eaac76a971 100644
--- a/Documentation/driver-api/tty/index.rst
+++ b/Documentation/driver-api/tty/index.rst
@@ -68,4 +68,5 @@ Miscellaneous documentation can be further found in these documents:
 .. toctree::
    :maxdepth: 2
 
+   n_gsm
    n_tty
diff --git a/Documentation/driver-api/serial/n_gsm.rst b/Documentation/driver-api/tty/n_gsm.rst
similarity index 100%
rename from Documentation/driver-api/serial/n_gsm.rst
rename to Documentation/driver-api/tty/n_gsm.rst
-- 
2.35.1

[PATCH 4/6] Documentation: tty: move moxa-smartio.rst to tty

[Jiri Slaby]

It is a tty_driver, not serial -- uart_driver. So move it to the tty
docs dir too. (The same as the driver itself.)

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
---
 Documentation/driver-api/serial/index.rst                 | 1 -
 Documentation/driver-api/tty/index.rst                    | 1 +
 Documentation/driver-api/{serial => tty}/moxa-smartio.rst | 0
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename Documentation/driver-api/{serial => tty}/moxa-smartio.rst (100%)

diff --git a/Documentation/driver-api/serial/index.rst b/Documentation/driver-api/serial/index.rst
index 4ebdb86cd6b6..03a55b987a1d 100644
--- a/Documentation/driver-api/serial/index.rst
+++ b/Documentation/driver-api/serial/index.rst
@@ -16,7 +16,6 @@ Serial drivers
 .. toctree::
     :maxdepth: 1
 
-    moxa-smartio
     serial-iso7816
     serial-rs485
 
diff --git a/Documentation/driver-api/tty/index.rst b/Documentation/driver-api/tty/index.rst
index 85eaac76a971..2d32606a4278 100644
--- a/Documentation/driver-api/tty/index.rst
+++ b/Documentation/driver-api/tty/index.rst
@@ -68,5 +68,6 @@ Miscellaneous documentation can be further found in these documents:
 .. toctree::
    :maxdepth: 2
 
+   moxa-smartio
    n_gsm
    n_tty
diff --git a/Documentation/driver-api/serial/moxa-smartio.rst b/Documentation/driver-api/tty/moxa-smartio.rst
similarity index 100%
rename from Documentation/driver-api/serial/moxa-smartio.rst
rename to Documentation/driver-api/tty/moxa-smartio.rst
-- 
2.35.1

[PATCH 5/6] Documentation: tty: n_gsm, delete "Additional Documentation"

[Jiri Slaby]

All of the URLs give 404. There is a little point to preserve them. If
really need be, we could try archive.org if the documents are not there
by a chance.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
---
 Documentation/driver-api/tty/n_gsm.rst | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/Documentation/driver-api/tty/n_gsm.rst b/Documentation/driver-api/tty/n_gsm.rst
index 49956509ad73..04308a7a194a 100644
--- a/Documentation/driver-api/tty/n_gsm.rst
+++ b/Documentation/driver-api/tty/n_gsm.rst
@@ -146,14 +146,4 @@ Major parts of the initialization program :
 	daemon(0,0);
 	pause();
 
-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
-
 11-03-08 - Eric Bénard - <eric@eukrea.com>
-- 
2.35.1

[PATCH 6/6] Documentation: tty: n_gsm, use power of ReST

[Jiri Slaby]

Reformat the whole document, so that automatic numbering and TOC is
properly generated.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
---
 Documentation/driver-api/tty/n_gsm.rst | 144 +++++++++++++------------
 1 file changed, 74 insertions(+), 70 deletions(-)

diff --git a/Documentation/driver-api/tty/n_gsm.rst b/Documentation/driver-api/tty/n_gsm.rst
index 04308a7a194a..35d7381515b0 100644
--- a/Documentation/driver-api/tty/n_gsm.rst
+++ b/Documentation/driver-api/tty/n_gsm.rst
@@ -2,6 +2,8 @@
 GSM 0710 tty multiplexor HOWTO
 ==============================
 
+.. contents:: :local:
+
 This line discipline implements the GSM 07.10 multiplexing protocol
 detailed in the following 3GPP document:
 
@@ -11,79 +13,81 @@ 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. config initiator
-^^^^^^^^^^^^^^^^^^^^^
+=============
 
-1.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.
+Config Initiator
+----------------
 
-1.2 switch the serial line to using the n_gsm line discipline by using
-    TIOCSETD ioctl.
+#. 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.
 
-1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
+#. Switch the serial line to using the n_gsm line discipline by using
+   ``TIOCSETD`` ioctl.
 
-1.4 obtain base gsmtty number for the used serial port.
+#. 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)::
+#. Obtain base gsmtty number for the used serial port.
 
-  #include <stdio.h>
-  #include <stdint.h>
-  #include <linux/gsmmux.h>
-  #include <linux/tty.h>
-  #define DEFAULT_SPEED	B115200
-  #define SERIAL_PORT	/dev/ttyS0
+   Major parts of the initialization program
+   (a good starting point is util-linux-ng/sys-utils/ldattach.c)::
 
-	int ldisc = N_GSM0710;
-	struct gsm_config c;
-	struct termios configuration;
-	uint32_t first;
+      #include <stdio.h>
+      #include <stdint.h>
+      #include <linux/gsmmux.h>
+      #include <linux/tty.h>
 
-	/* open the serial port connected to the modem */
-	fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
+      #define DEFAULT_SPEED	B115200
+      #define SERIAL_PORT	/dev/ttyS0
 
-	/* configure the serial port : speed, flow control ... */
+      int ldisc = N_GSM0710;
+      struct gsm_config c;
+      struct termios configuration;
+      uint32_t first;
 
-	/* send the AT commands to switch the modem to CMUX mode
-	   and check that it's successful (should return OK) */
-	write(fd, "AT+CMUX=0\r", 10);
+      /* open the serial port connected to the modem */
+      fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
 
-	/* experience showed that some modems need some time before
-	   being able to answer to the first MUX packet so a delay
-	   may be needed here in some case */
-	sleep(3);
+      /* configure the serial port : speed, flow control ... */
 
-	/* use n_gsm line discipline */
-	ioctl(fd, TIOCSETD, &ldisc);
+      /* send the AT commands to switch the modem to CMUX mode
+         and check that it's successful (should return OK) */
+      write(fd, "AT+CMUX=0\r", 10);
 
-	/* get n_gsm configuration */
-	ioctl(fd, GSMIOC_GETCONF, &c);
-	/* we are initiator and need encoding 0 (basic) */
-	c.initiator = 1;
-	c.encapsulation = 0;
-	/* our modem defaults to a maximum size of 127 bytes */
-	c.mru = 127;
-	c.mtu = 127;
-	/* set the new configuration */
-	ioctl(fd, GSMIOC_SETCONF, &c);
-	/* get first gsmtty device node */
-	ioctl(fd, GSMIOC_GETFIRST, &first);
-	printf("first muxed line: /dev/gsmtty%i\n", first);
+      /* experience showed that some modems need some time before
+         being able to answer to the first MUX packet so a delay
+         may be needed here in some case */
+      sleep(3);
 
-	/* and wait for ever to keep the line discipline enabled */
-	daemon(0,0);
-	pause();
+      /* use n_gsm line discipline */
+      ioctl(fd, TIOCSETD, &ldisc);
+
+      /* get n_gsm configuration */
+      ioctl(fd, GSMIOC_GETCONF, &c);
+      /* we are initiator and need encoding 0 (basic) */
+      c.initiator = 1;
+      c.encapsulation = 0;
+      /* our modem defaults to a maximum size of 127 bytes */
+      c.mru = 127;
+      c.mtu = 127;
+      /* set the new configuration */
+      ioctl(fd, GSMIOC_SETCONF, &c);
+      /* get first gsmtty device node */
+      ioctl(fd, GSMIOC_GETFIRST, &first);
+      printf("first muxed line: /dev/gsmtty%i\n", first);
+
+      /* and wait for ever to keep the line discipline enabled */
+      daemon(0,0);
+      pause();
 
-1.5 use these devices as plain serial ports.
+#. Use these devices as plain serial ports.
 
-   for example, it's possible:
+   For example, it's possible:
 
-   - and to use gnokii to send / receive SMS on ttygsm1
-   - to use ppp to establish a datalink on ttygsm2
+   - to use *gnokii* to send / receive SMS on ``ttygsm1``
+   - to use *ppp* to establish a datalink on ``ttygsm2``
 
-1.6 first close all virtual ports before closing the physical port.
+#. 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
@@ -91,27 +95,27 @@ Major parts of the initialization program :
    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.
+      0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9
 
-2. config requester
-^^^^^^^^^^^^^^^^^^^^^
+Config Requester
+----------------
 
-2.1 receive string "AT+CMUX= command" through its serial port,initialize
-    mux mode config
+#. Receive ``AT+CMUX=`` command through its serial port, initialize mux mode
+   config.
 
-2.2 switch the serial line to using the n_gsm line discipline by using
-    TIOCSETD ioctl.
+#. Switch the serial line to using the *n_gsm* line discipline by using
+   ``TIOCSETD`` ioctl.
 
-2.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
+#. Configure the mux using ``GSMIOC_GETCONF``/``GSMIOC_SETCONF`` ioctl.
 
-2.4 obtain base gsmtty number for the used serial port::
+#. Obtain base gsmtty number for the used serial port::
 
-  #include <stdio.h>
-  #include <stdint.h>
-  #include <linux/gsmmux.h>
-  #include <linux/tty.h>
-  #define DEFAULT_SPEED	B115200
-  #define SERIAL_PORT	/dev/ttyS0
+        #include <stdio.h>
+        #include <stdint.h>
+        #include <linux/gsmmux.h>
+        #include <linux/tty.h>
+        #define DEFAULT_SPEED	B115200
+        #define SERIAL_PORT	/dev/ttyS0
 
 	int ldisc = N_GSM0710;
 	struct gsm_config c;
-- 
2.35.1