Skip to content

L
linux
Commit f1374017 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Greg Kroah-Hartman
Browse files
Options

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: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 3e51ceea
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1015 additions and 173 deletions
Documentation/serial/README.cycladesZ → Documentation/serial/cyclades_z.rst
View file @ f1374017
================
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/index.rst 0 → 100644
View file @ f1374017
: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
View file @ f1374017
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
View file @ f1374017
Comtrol(tm) RocketPort(R)/RocketModem(TM) Series
Device Driver for the Linux Operating System
================================================
Comtrol(tm) RocketPort(R)/RocketModem(TM) Series
================================================
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Device Driver for the Linux Operating System
============================================
PRODUCT OVERVIEW
Product overview
----------------
This driver provides a loadable kernel driver for the Comtrol RocketPort
and RocketModem PCI boards. These boards provide, 2, 4, 8, 16, or 32
and RocketModem PCI boards. These boards provide, 2, 4, 8, 16, or 32
high-speed serial ports or modems. This driver supports up to a combination
of four RocketPort or RocketModems boards in one machine simultaneously.
This file assumes that you are using the RocketPort driver which is
integrated into the kernel sources.
integrated into the kernel sources.
The driver can also be installed as an external module using the usual
"make;make install" routine. This external module driver, obtainable
The driver can also be installed as an external module using the usual
"make;make install" routine. This external module driver, obtainable
from the Comtrol website listed below, is useful for updating the driver
or installing it into kernels which do not have the driver configured
into them. Installations instructions for the external module
......@@ -29,57 +31,59 @@ 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
RocketPort/RocketModem PCI cards require no driver configuration, they are
automatically detected and configured.
The RocketPort driver can be installed as a module (recommended) or built
The RocketPort driver can be installed as a module (recommended) or built
into the kernel. This is selected, as for other drivers, through the `make config`
command from the root of the Linux source tree during the kernel build process.
command from the root of the Linux source tree during the kernel build process.
The RocketPort/RocketModem serial ports installed by this driver are assigned
device major number 46, and will be named /dev/ttyRx, where x is the port number
device major number 46, and will be named /dev/ttyRx, where x is the port number
starting at zero (ex. /dev/ttyR0, /devttyR1, ...). If you have multiple cards
installed in the system, the mapping of port names to serial ports is displayed
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:
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.
>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,40 +134,36 @@ 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:
+-------------------------------+
| 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
+-------+-------+---------------+
| 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
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
RocketPort and RocketPort RA SW1 Settings::
+-------------------------------+
| 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
+-------+-------+---------------+
| 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
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
--------------
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
View file @ f1374017
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
View file @ f1374017
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
View file @ f1374017
......@@ -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
View file @ f1374017
......@@ -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
View file @ f1374017
......@@ -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
View file @ f1374017
......@@ -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 *);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7