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

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

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

+4 −1
Original line number Diff line number Diff line 
================

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

+89 −26
Original line number Diff line number Diff line 


====================

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

0 → 100644
+32 −0
Original line number Diff line number Diff line 
: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/moxa-smartio→Documentation/serial/moxa-smartio.rst

+615 −0

File changed and moved.

Preview size limit exceeded, changes collapsed.

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

+103 −0
Original line number Diff line number Diff line 
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



This document give some hints on how to use this driver with GPRS and 3G
@@ -10,15 +12,16 @@ modems connected to a physical serial port. 


How to use it

-------------

1- initialize the modem in 0710 mux mode (usually AT+CMUX= command) through

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

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,

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)

(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
@@ -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,

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)

   of the mux)::



     MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}`

     for i in `seq 1 4`; do

	mknod /dev/ttygsm$i c $MAJOR $i

     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



6- first close all virtual ports before closing the physical port.

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:

   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>

CRA Git | Maintained and supported by SUSTech CRA and CCSE