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
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 <[email protected]>
---
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
So far only n_tty belongs here, but in the next patches, more will come.
Signed-off-by: Jiri Slaby <[email protected]>
---
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
Based on discussion starting as [email protected], let's move
the tty documentation to driver-api. It's more appropriate there.
Signed-off-by: Jiri Slaby <[email protected]>
Cc: Jonathan Corbet <[email protected]>
---
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
Reformat the whole document, so that automatic numbering and TOC is
properly generated.
Signed-off-by: Jiri Slaby <[email protected]>
---
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
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 <[email protected]>
---
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