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
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 The Cyclades-Z must have firmware loaded onto the card before it will
operate. This operation should be performed during system startup, operate. This operation should be performed during system startup,
The firmware, loader program and the latest device driver code are The firmware, loader program and the latest device driver code are
available from Cyclades at 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
View file @ f1374017
====================
Low Level Serial API Low Level Serial API
-------------------- ====================
This document is meant as a brief overview of some aspects of the new serial 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.) ...@@ -44,7 +44,7 @@ are described in the uart_ops listing below.)
There are two locks. A per-port spinlock, and an overall semaphore. There are two locks. A per-port spinlock, and an overall semaphore.
From the core driver perspective, the port->lock locks the following From the core driver perspective, the port->lock locks the following
data: data::
port->mctrl port->mctrl
port->icount port->icount
...@@ -75,41 +75,51 @@ hardware. ...@@ -75,41 +75,51 @@ hardware.
return TIOCSER_TEMT. return TIOCSER_TEMT.
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
This call must not sleep This call must not sleep
set_mctrl(port, mctrl) set_mctrl(port, mctrl)
This function sets the modem control lines for port described This function sets the modem control lines for port described
by 'port' to the state described by mctrl. The relevant bits by 'port' to the state described by mctrl. The relevant bits
of mctrl are: of mctrl are:
- TIOCM_RTS RTS signal. - TIOCM_RTS RTS signal.
- TIOCM_DTR DTR signal. - TIOCM_DTR DTR signal.
- TIOCM_OUT1 OUT1 signal. - TIOCM_OUT1 OUT1 signal.
- TIOCM_OUT2 OUT2 signal. - TIOCM_OUT2 OUT2 signal.
- TIOCM_LOOP Set the port into loopback mode. - TIOCM_LOOP Set the port into loopback mode.
If the appropriate bit is set, the signal should be driven If the appropriate bit is set, the signal should be driven
active. If the bit is clear, the signal should be driven active. If the bit is clear, the signal should be driven
inactive. inactive.
Locking: port->lock taken. Locking: port->lock taken.
Interrupts: locally disabled. Interrupts: locally disabled.
This call must not sleep This call must not sleep
get_mctrl(port) get_mctrl(port)
Returns the current state of modem control inputs. The state Returns the current state of modem control inputs. The state
of the outputs should not be returned, since the core keeps of the outputs should not be returned, since the core keeps
track of their state. The state information should include: track of their state. The state information should include:
- TIOCM_CAR state of DCD signal - TIOCM_CAR state of DCD signal
- TIOCM_CTS state of CTS signal - TIOCM_CTS state of CTS signal
- TIOCM_DSR state of DSR signal - TIOCM_DSR state of DSR signal
- TIOCM_RI state of RI signal - TIOCM_RI state of RI signal
The bit is set if the signal is currently driven active. If The bit is set if the signal is currently driven active. If
the port does not support CTS, DCD or DSR, the driver should the port does not support CTS, DCD or DSR, the driver should
indicate that the signal is permanently active. If RI is indicate that the signal is permanently active. If RI is
not available, the signal should not be indicated as active. not available, the signal should not be indicated as active.
Locking: port->lock taken. Locking: port->lock taken.
Interrupts: locally disabled. Interrupts: locally disabled.
This call must not sleep This call must not sleep
stop_tx(port) stop_tx(port)
...@@ -121,14 +131,18 @@ hardware. ...@@ -121,14 +131,18 @@ hardware.
possible. possible.
Locking: port->lock taken. Locking: port->lock taken.
Interrupts: locally disabled. Interrupts: locally disabled.
This call must not sleep This call must not sleep
start_tx(port) start_tx(port)
Start transmitting characters. Start transmitting characters.
Locking: port->lock taken. Locking: port->lock taken.
Interrupts: locally disabled. Interrupts: locally disabled.
This call must not sleep This call must not sleep
throttle(port) throttle(port)
...@@ -138,16 +152,17 @@ hardware. ...@@ -138,16 +152,17 @@ hardware.
This will be called only if hardware assisted flow control is enabled. This will be called only if hardware assisted flow control is enabled.
Locking: serialized with .unthrottle() and termios modification by the Locking: serialized with .unthrottle() and termios modification by the
tty layer. tty layer.
unthrottle(port) unthrottle(port)
Notify the serial driver that characters can now be sent to the serial Notify the serial driver that characters can now be sent to the serial
port without fear of overrunning the input buffers of the line port without fear of overrunning the input buffers of the line
disciplines. disciplines.
This will be called only if hardware assisted flow control is enabled. This will be called only if hardware assisted flow control is enabled.
Locking: serialized with .throttle() and termios modification by the Locking: serialized with .throttle() and termios modification by the
tty layer. tty layer.
send_xchar(port,ch) send_xchar(port,ch)
Transmit a high priority character, even if the port is stopped. Transmit a high priority character, even if the port is stopped.
...@@ -159,6 +174,7 @@ hardware. ...@@ -159,6 +174,7 @@ hardware.
Do not transmit if ch == '\0' (__DISABLED_CHAR). Do not transmit if ch == '\0' (__DISABLED_CHAR).
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
stop_rx(port) stop_rx(port)
...@@ -166,7 +182,9 @@ hardware. ...@@ -166,7 +182,9 @@ hardware.
being closed. being closed.
Locking: port->lock taken. Locking: port->lock taken.
Interrupts: locally disabled. Interrupts: locally disabled.
This call must not sleep This call must not sleep
enable_ms(port) enable_ms(port)
...@@ -177,7 +195,9 @@ hardware. ...@@ -177,7 +195,9 @@ hardware.
called. called.
Locking: port->lock taken. Locking: port->lock taken.
Interrupts: locally disabled. Interrupts: locally disabled.
This call must not sleep This call must not sleep
break_ctl(port,ctl) break_ctl(port,ctl)
...@@ -196,6 +216,7 @@ hardware. ...@@ -196,6 +216,7 @@ hardware.
This method will only be called when the port is initially opened. This method will only be called when the port is initially opened.
Locking: port_sem taken. Locking: port_sem taken.
Interrupts: globally disabled. Interrupts: globally disabled.
shutdown(port) shutdown(port)
...@@ -210,6 +231,7 @@ hardware. ...@@ -210,6 +231,7 @@ hardware.
this port. this port.
Locking: port_sem taken. Locking: port_sem taken.
Interrupts: caller dependent. Interrupts: caller dependent.
flush_buffer(port) flush_buffer(port)
...@@ -220,7 +242,9 @@ hardware. ...@@ -220,7 +242,9 @@ hardware.
buffer is cleared. buffer is cleared.
Locking: port->lock taken. Locking: port->lock taken.
Interrupts: locally disabled. Interrupts: locally disabled.
This call must not sleep This call must not sleep
set_termios(port,termios,oldtermios) set_termios(port,termios,oldtermios)
...@@ -228,29 +252,46 @@ hardware. ...@@ -228,29 +252,46 @@ hardware.
bits. Update read_status_mask and ignore_status_mask to indicate bits. Update read_status_mask and ignore_status_mask to indicate
the types of events we are interested in receiving. Relevant the types of events we are interested in receiving. Relevant
termios->c_cflag bits are: termios->c_cflag bits are:
CSIZE - word size
CSTOPB - 2 stop bits CSIZE
PARENB - parity enable - word size
PARODD - odd parity (when PARENB is in force) CSTOPB
CREAD - enable reception of characters (if not set, - 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 still receive characters from the port, but
throw them away. throw them away.
CRTSCTS - if set, enable CTS status change reporting CRTSCTS
CLOCAL - if not set, enable modem status change - if set, enable CTS status change reporting
CLOCAL
- if not set, enable modem status change
reporting. reporting.
Relevant termios->c_iflag bits are: 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. passed to the TTY layer.
BRKINT BRKINT / PARMRK
PARMRK - both of these enable break events to be - both of these enable break events to be
passed to the TTY layer. passed to the TTY layer.
IGNPAR - ignore parity and framing errors IGNPAR
IGNBRK - ignore break errors, If IGNPAR is also - ignore parity and framing errors
IGNBRK
- ignore break errors, If IGNPAR is also
set, ignore overrun errors as well. set, ignore overrun errors as well.
The interaction of the iflag bits is as follows (parity error The interaction of the iflag bits is as follows (parity error
given as an example): given as an example):
=============== ======= ====== =============================
Parity error INPCK IGNPAR Parity error INPCK IGNPAR
=============== ======= ====== =============================
n/a 0 n/a character received, marked as n/a 0 n/a character received, marked as
TTY_NORMAL TTY_NORMAL
None 1 n/a character received, marked as None 1 n/a character received, marked as
...@@ -258,16 +299,19 @@ hardware. ...@@ -258,16 +299,19 @@ hardware.
Yes 1 0 character received, marked as Yes 1 0 character received, marked as
TTY_PARITY TTY_PARITY
Yes 1 1 character discarded Yes 1 1 character discarded
=============== ======= ====== =============================
Other flags may be used (eg, xon/xoff characters) if your Other flags may be used (eg, xon/xoff characters) if your
hardware supports hardware "soft" flow control. hardware supports hardware "soft" flow control.
Locking: caller holds tty_port->mutex Locking: caller holds tty_port->mutex
Interrupts: caller dependent. Interrupts: caller dependent.
This call must not sleep This call must not sleep
set_ldisc(port,termios) 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 Locking: caller holds tty_port->mutex
...@@ -283,6 +327,7 @@ hardware. ...@@ -283,6 +327,7 @@ hardware.
will occur even if CONFIG_PM is not set. will occur even if CONFIG_PM is not set.
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
type(port) type(port)
...@@ -291,6 +336,7 @@ hardware. ...@@ -291,6 +336,7 @@ hardware.
substituted. substituted.
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
release_port(port) release_port(port)
...@@ -298,6 +344,7 @@ hardware. ...@@ -298,6 +344,7 @@ hardware.
the port. the port.
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
request_port(port) request_port(port)
...@@ -306,6 +353,7 @@ hardware. ...@@ -306,6 +353,7 @@ hardware.
returns, and it should return -EBUSY on failure. returns, and it should return -EBUSY on failure.
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
config_port(port,type) config_port(port,type)
...@@ -321,6 +369,7 @@ hardware. ...@@ -321,6 +369,7 @@ hardware.
internally hard wired (eg, system on a chip implementations). internally hard wired (eg, system on a chip implementations).
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
verify_port(port,serinfo) verify_port(port,serinfo)
...@@ -328,6 +377,7 @@ hardware. ...@@ -328,6 +377,7 @@ hardware.
suitable for this port type. suitable for this port type.
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
ioctl(port,cmd,arg) ioctl(port,cmd,arg)
...@@ -335,6 +385,7 @@ hardware. ...@@ -335,6 +385,7 @@ hardware.
using the standard numbering system found in <asm/ioctl.h> using the standard numbering system found in <asm/ioctl.h>
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
poll_init(port) poll_init(port)
...@@ -343,6 +394,7 @@ hardware. ...@@ -343,6 +394,7 @@ hardware.
this should not request interrupts. this should not request interrupts.
Locking: tty_mutex and tty_port->mutex taken. Locking: tty_mutex and tty_port->mutex taken.
Interrupts: n/a. Interrupts: n/a.
poll_put_char(port,ch) poll_put_char(port,ch)
...@@ -350,7 +402,9 @@ hardware. ...@@ -350,7 +402,9 @@ hardware.
port. It can and should block until there is space in the TX FIFO. port. It can and should block until there is space in the TX FIFO.
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
This call must not sleep This call must not sleep
poll_get_char(port) poll_get_char(port)
...@@ -359,7 +413,9 @@ hardware. ...@@ -359,7 +413,9 @@ hardware.
the function should return NO_POLL_CHAR immediately. the function should return NO_POLL_CHAR immediately.
Locking: none. Locking: none.
Interrupts: caller dependent. Interrupts: caller dependent.
This call must not sleep This call must not sleep
Other functions Other functions
...@@ -370,6 +426,7 @@ uart_update_timeout(port,cflag,baud) ...@@ -370,6 +426,7 @@ uart_update_timeout(port,cflag,baud)
number of bits, parity, stop bits and baud rate. number of bits, parity, stop bits and baud rate.
Locking: caller is expected to take port->lock Locking: caller is expected to take port->lock
Interrupts: n/a Interrupts: n/a
uart_get_baud_rate(port,termios,old,min,max) uart_get_baud_rate(port,termios,old,min,max)
...@@ -385,6 +442,7 @@ 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. Note: min..max must always allow 9600 baud to be selected.
Locking: caller dependent. Locking: caller dependent.
Interrupts: n/a Interrupts: n/a
uart_get_divisor(port,baud) uart_get_divisor(port,baud)
...@@ -395,6 +453,7 @@ uart_get_divisor(port,baud) ...@@ -395,6 +453,7 @@ uart_get_divisor(port,baud)
custom divisor instead. custom divisor instead.
Locking: caller dependent. Locking: caller dependent.
Interrupts: n/a Interrupts: n/a
uart_match_port(port1,port2) uart_match_port(port1,port2)
...@@ -402,6 +461,7 @@ uart_match_port(port1,port2) ...@@ -402,6 +461,7 @@ uart_match_port(port1,port2)
uart_port structures describe the same port. uart_port structures describe the same port.
Locking: n/a Locking: n/a
Interrupts: n/a Interrupts: n/a
uart_write_wakeup(port) uart_write_wakeup(port)
...@@ -409,6 +469,7 @@ uart_write_wakeup(port) ...@@ -409,6 +469,7 @@ uart_write_wakeup(port)
characters in the transmit buffer have dropped below a threshold. characters in the transmit buffer have dropped below a threshold.
Locking: port->lock should be held. Locking: port->lock should be held.
Interrupts: n/a Interrupts: n/a
uart_register_driver(drv) uart_register_driver(drv)
...@@ -419,6 +480,7 @@ uart_register_driver(drv) ...@@ -419,6 +480,7 @@ uart_register_driver(drv)
registered using uart_add_one_port after this call has succeeded. registered using uart_add_one_port after this call has succeeded.
Locking: none Locking: none
Interrupts: enabled Interrupts: enabled
uart_unregister_driver() uart_unregister_driver()
...@@ -427,15 +489,16 @@ uart_unregister_driver() ...@@ -427,15 +489,16 @@ uart_unregister_driver()
uart_remove_one_port() if it registered them with uart_add_one_port(). uart_remove_one_port() if it registered them with uart_add_one_port().
Locking: none Locking: none
Interrupts: enabled 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 Other notes
----------- -----------
...@@ -444,7 +507,7 @@ It is intended some day to drop the 'unused' entries from uart_port, and ...@@ -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 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 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, structure containing both the uart_port entry with their own extensions,
thus: thus::
struct my_port { struct my_port {
struct uart_port port; struct uart_port port;
...@@ -459,14 +522,14 @@ Some helpers are provided in order to set/get modem control lines via GPIO. ...@@ -459,14 +522,14 @@ Some helpers are provided in order to set/get modem control lines via GPIO.
mctrl_gpio_init(port, idx): mctrl_gpio_init(port, idx):
This will get the {cts,rts,...}-gpios from device tree if they are This will get the {cts,rts,...}-gpios from device tree if they are
present and request them, set direction etc, and return an 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(). to call mctrl_gpio_free().
As this sets up the irq handling make sure to not handle changes to the As this sets up the irq handling make sure to not handle changes to the
gpio input lines in your driver, too. gpio input lines in your driver, too.
mctrl_gpio_free(dev, gpios): mctrl_gpio_free(dev, gpios):
This will free the requested gpios in mctrl_gpio_init(). 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. this function.
mctrl_gpio_to_gpiod(gpios, gidx) mctrl_gpio_to_gpiod(gpios, gidx)
......
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/moxa-smartio → Documentation/serial/moxa-smartio.rst
View file @ f1374017
============================================================================= =============================================================
MOXA Smartio/Industio Family Device Driver Installation Guide MOXA Smartio/Industio Family Device Driver Installation Guide
for Linux Kernel 2.4.x, 2.6.x =============================================================
Copyright (C) 2008, Moxa Inc.
=============================================================================
Date: 01/21/2008
Content .. note::
1. Introduction This file is outdated. It needs some care in order to make it
2. System Requirement updated to Kernel 5.0 and upper
3. Installation
3.1 Hardware installation Copyright (C) 2008, Moxa Inc.
3.2 Driver files
3.3 Device naming convention Date: 01/21/2008
3.4 Module driver configuration
3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x. .. Content
3.6 Custom configuration
3.7 Verify driver installation 1. Introduction
4. Utilities 2. System Requirement
5. Setserial 3. Installation
6. Troubleshooting 3.1 Hardware installation
3.2 Driver files
3.3 Device naming convention
3.4 Module driver configuration
3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x.
3.6 Custom configuration
3.7 Verify driver installation
4. Utilities
5. Setserial
6. Troubleshooting
-----------------------------------------------------------------------------
1. Introduction 1. Introduction
^^^^^^^^^^^^^^^
The Smartio/Industio/UPCI family Linux driver supports following multiport The Smartio/Industio/UPCI family Linux driver supports following multiport
boards. boards.
...@@ -43,7 +49,7 @@ Content ...@@ -43,7 +49,7 @@ Content
C104H, C104HS, C104H, C104HS,
CI-104J, CI-104JS, CI-104J, CI-104JS,
CI-134, CI-134I, CI-134IS, CI-134, CI-134I, CI-134IS,
(C114HI, CT-114I, C104P) (C114HI, CT-114I, C104P),
POS-104UL, POS-104UL,
CB-114, CB-114,
CB-134I CB-134I
...@@ -63,13 +69,17 @@ Content ...@@ -63,13 +69,17 @@ Content
occurs, please contact Moxa at support@moxa.com.tw. occurs, please contact Moxa at support@moxa.com.tw.
In addition to device driver, useful utilities are also provided in this In addition to device driver, useful utilities are also provided in this
version. They are version. They are:
- msdiag Diagnostic program for displaying installed Moxa
- msdiag
Diagnostic program for displaying installed Moxa
Smartio/Industio boards. Smartio/Industio boards.
- msmon Monitor program to observe data count and line status signals. - msmon
Monitor program to observe data count and line status signals.
- msterm A simple terminal program which is useful in testing serial - msterm A simple terminal program which is useful in testing serial
ports. ports.
- io-irq.exe Configuration program to setup ISA boards. Please note that - io-irq.exe
Configuration program to setup ISA boards. Please note that
this program can only be executed under DOS. this program can only be executed under DOS.
All the drivers and utilities are published in form of source code under All the drivers and utilities are published in form of source code under
...@@ -84,65 +94,63 @@ Content ...@@ -84,65 +94,63 @@ Content
please refer to hardware installation procedure in the User's Manual. please refer to hardware installation procedure in the User's Manual.
We assume the user should be familiar with following documents. We assume the user should be familiar with following documents.
- Serial-HOWTO - Serial-HOWTO
- Kernel-HOWTO - Kernel-HOWTO
-----------------------------------------------------------------------------
2. System Requirement 2. System Requirement
^^^^^^^^^^^^^^^^^^^^^
- Hardware platform: Intel x86 machine - Hardware platform: Intel x86 machine
- Kernel version: 2.4.x or 2.6.x - Kernel version: 2.4.x or 2.6.x
- gcc version 2.72 or later - gcc version 2.72 or later
- Maximum 4 boards can be installed in combination - Maximum 4 boards can be installed in combination
-----------------------------------------------------------------------------
3. Installation 3. Installation
^^^^^^^^^^^^^^^
3.1 Hardware installation
=========================
3.1 Hardware installation There are two types of buses, ISA and PCI, for Smartio/Industio
3.2 Driver files family multiport board.
3.3 Device naming convention
3.4 Module driver configuration
3.5 Static driver configuration for Linux kernel 2.4.x, 2.6.x.
3.6 Custom configuration
3.7 Verify driver installation
ISA board
---------
3.1 Hardware installation You'll have to configure CAP address, I/O address, Interrupt Vector
as well as IRQ before installing this driver. Please refer to hardware
installation procedure in User's Manual before proceed any further.
Please make sure the JP1 is open after the ISA board is set properly.
There are two types of buses, ISA and PCI, for Smartio/Industio PCI/UPCI board
family multiport board. --------------
ISA board You may need to adjust IRQ usage in BIOS to avoid from IRQ conflict
--------- with other ISA devices. Please refer to hardware installation
You'll have to configure CAP address, I/O address, Interrupt Vector procedure in User's Manual in advance.
as well as IRQ before installing this driver. Please refer to hardware
installation procedure in User's Manual before proceed any further.
Please make sure the JP1 is open after the ISA board is set properly.
PCI/UPCI board PCI IRQ Sharing
-------------- ---------------
You may need to adjust IRQ usage in BIOS to avoid from IRQ conflict
with other ISA devices. Please refer to hardware installation
procedure in User's Manual in advance.
PCI IRQ Sharing Each port within the same multiport board shares the same IRQ. Up to
----------- 4 Moxa Smartio/Industio PCI Family multiport boards can be installed
Each port within the same multiport board shares the same IRQ. Up to together on one system and they can share the same IRQ.
4 Moxa Smartio/Industio PCI Family multiport boards can be installed
together on one system and they can share the same IRQ.
3.2 Driver files 3.2 Driver files
================
The driver file may be obtained from ftp, CD-ROM or floppy disk. The The driver file may be obtained from ftp, CD-ROM or floppy disk. The
first step, anyway, is to copy driver file "mxser.tgz" into specified first step, anyway, is to copy driver file "mxser.tgz" into specified
directory. e.g. /moxa. The execute commands as below. directory. e.g. /moxa. The execute commands as below::
# cd / # cd /
# mkdir moxa # mkdir moxa
# cd /moxa # cd /moxa
# tar xvf /dev/fd0 # tar xvf /dev/fd0
or or::
# cd / # cd /
# mkdir moxa # mkdir moxa
...@@ -151,278 +159,348 @@ Content ...@@ -151,278 +159,348 @@ Content
# tar xvfz mxser.tgz # tar xvfz mxser.tgz
3.3 Device naming convention 3.3 Device naming convention
============================
You may find all the driver and utilities files in /moxa/mxser.
Following installation procedure depends on the model you'd like to
run the driver. If you prefer module driver, please refer to 3.4.
If static driver is required, please refer to 3.5.
Dialin and callout port
-----------------------
This driver remains traditional serial device properties. There are
two special file name for each serial port. One is dial-in port
which is named "ttyMxx". For callout port, the naming convention
is "cumxx".
Device naming when more than 2 boards installed
-----------------------------------------------
Naming convention for each Smartio/Industio multiport board is
pre-defined as below.
Board Num. Dial-in Port Callout port
1st board ttyM0 - ttyM7 cum0 - cum7
2nd board ttyM8 - ttyM15 cum8 - cum15
3rd board ttyM16 - ttyM23 cum16 - cum23
4th board ttyM24 - ttym31 cum24 - cum31
!!!!!!!!!!!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Under Kernel 2.6 the cum Device is Obsolete. So use ttyM*
device instead.
!!!!!!!!!!!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Board sequence
--------------
This driver will activate ISA boards according to the parameter set
in the driver. After all specified ISA board activated, PCI board
will be installed in the system automatically driven.
Therefore the board number is sorted by the CAP address of ISA boards.
For PCI boards, their sequence will be after ISA boards and C168H/PCI
has higher priority than C104H/PCI boards.
3.4 Module driver configuration
Module driver is easiest way to install. If you prefer static driver
installation, please skip this paragraph.
------------- Prepare to use the MOXA driver--------------------
3.4.1 Create tty device with correct major number
Before using MOXA driver, your system must have the tty devices
which are created with driver's major number. We offer one shell
script "msmknod" to simplify the procedure.
This step is only needed to be executed once. But you still
need to do this procedure when:
a. You change the driver's major number. Please refer the "3.7"
section.
b. Your total installed MOXA boards number is changed. Maybe you
add/delete one MOXA board.
c. You want to change the tty name. This needs to modify the
shell script "msmknod"
The procedure is:
# cd /moxa/mxser/driver
# ./msmknod
This shell script will require the major number for dial-in
device and callout device to create tty device. You also need
to specify the total installed MOXA board number. Default major
numbers for dial-in device and callout device are 30, 35. If
you need to change to other number, please refer section "3.7"
for more detailed procedure.
Msmknod will delete any special files occupying the same device
naming.
3.4.2 Build the MOXA driver and utilities
Before using the MOXA driver and utilities, you need compile the
all the source code. This step is only need to be executed once.
But you still re-compile the source code if you modify the source
code. For example, if you change the driver's major number (see
"3.7" section), then you need to do this step again.
Find "Makefile" in /moxa/mxser, then run
# make clean; make install You may find all the driver and utilities files in /moxa/mxser.
Following installation procedure depends on the model you'd like to
run the driver. If you prefer module driver, please refer to 3.4.
If static driver is required, please refer to 3.5.
Dialin and callout port
-----------------------
This driver remains traditional serial device properties. There are
two special file name for each serial port. One is dial-in port
which is named "ttyMxx". For callout port, the naming convention
is "cumxx".
Device naming when more than 2 boards installed
-----------------------------------------------
Naming convention for each Smartio/Industio multiport board is
pre-defined as below.
============ =============== ==============
Board Num. Dial-in Port Callout port
1st board ttyM0 - ttyM7 cum0 - cum7
2nd board ttyM8 - ttyM15 cum8 - cum15
3rd board ttyM16 - ttyM23 cum16 - cum23
4th board ttyM24 - ttym31 cum24 - cum31
============ =============== ==============
.. note::
Under Kernel 2.6 and upper, the cum Device is Obsolete. So use ttyM*
device instead.
Board sequence
--------------
This driver will activate ISA boards according to the parameter set
in the driver. After all specified ISA board activated, PCI board
will be installed in the system automatically driven.
Therefore the board number is sorted by the CAP address of ISA boards.
For PCI boards, their sequence will be after ISA boards and C168H/PCI
has higher priority than C104H/PCI boards.
3.4 Module driver configuration
===============================
!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!! Module driver is easiest way to install. If you prefer static driver
For Red Hat 9, Red Hat Enterprise Linux AS3/ES3/WS3 & Fedora Core1: installation, please skip this paragraph.
# make clean; make installsp1
For Red Hat Enterprise Linux AS4/ES4/WS4:
# make clean; make installsp2
!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!
The driver files "mxser.o" and utilities will be properly compiled ------------- Prepare to use the MOXA driver --------------------
and copied to system directories respectively.
------------- Load MOXA driver-------------------- 3.4.1 Create tty device with correct major number
3.4.3 Load the MOXA driver -------------------------------------------------
# modprobe mxser <argument> Before using MOXA driver, your system must have the tty devices
which are created with driver's major number. We offer one shell
script "msmknod" to simplify the procedure.
This step is only needed to be executed once. But you still
need to do this procedure when:
will activate the module driver. You may run "lsmod" to check a. You change the driver's major number. Please refer the "3.7"
if "mxser" is activated. If the MOXA board is ISA board, the section.
<argument> is needed. Please refer to section "3.4.5" for more b. Your total installed MOXA boards number is changed. Maybe you
information. add/delete one MOXA board.
c. You want to change the tty name. This needs to modify the
shell script "msmknod"
The procedure is::
------------- Load MOXA driver on boot -------------------- # cd /moxa/mxser/driver
3.4.4 For the above description, you may manually execute # ./msmknod
"modprobe mxser" to activate this driver and run
"rmmod mxser" to remove it.
However, it's better to have a boot time configuration to
eliminate manual operation. Boot time configuration can be
achieved by rc file. We offer one "rc.mxser" file to simplify
the procedure under "moxa/mxser/driver".
But if you use ISA board, please modify the "modprobe ..." command This shell script will require the major number for dial-in
to add the argument (see "3.4.5" section). After modifying the device and callout device to create tty device. You also need
rc.mxser, please try to execute "/moxa/mxser/driver/rc.mxser" to specify the total installed MOXA board number. Default major
manually to make sure the modification is ok. If any error numbers for dial-in device and callout device are 30, 35. If
encountered, please try to modify again. If the modification is you need to change to other number, please refer section "3.7"
completed, follow the below step. for more detailed procedure.
Msmknod will delete any special files occupying the same device
naming.
Run following command for setting rc files. 3.4.2 Build the MOXA driver and utilities
-----------------------------------------
# cd /moxa/mxser/driver Before using the MOXA driver and utilities, you need compile the
# cp ./rc.mxser /etc/rc.d all the source code. This step is only need to be executed once.
# cd /etc/rc.d But you still re-compile the source code if you modify the source
code. For example, if you change the driver's major number (see
"3.7" section), then you need to do this step again.
Check "rc.serial" is existed or not. If "rc.serial" doesn't exist, Find "Makefile" in /moxa/mxser, then run
create it by vi, run "chmod 755 rc.serial" to change the permission.
Add "/etc/rc.d/rc.mxser" in last line,
Reboot and check if moxa.o activated by "lsmod" command. # make clean; make install
3.4.5. If you'd like to drive Smartio/Industio ISA boards in the system, ..note::
you'll have to add parameter to specify CAP address of given
board while activating "mxser.o". The format for parameters are
as follows.
modprobe mxser ioaddr=0x???,0x???,0x???,0x??? For Red Hat 9, Red Hat Enterprise Linux AS3/ES3/WS3 & Fedora Core1:
| | | | # make clean; make installsp1
| | | +- 4th ISA board
| | +------ 3rd ISA board
| +------------ 2nd ISA board
+------------------- 1st ISA board
3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x For Red Hat Enterprise Linux AS4/ES4/WS4:
# make clean; make installsp2
Note: To use static driver, you must install the linux kernel The driver files "mxser.o" and utilities will be properly compiled
source package. and copied to system directories respectively.
3.5.1 Backup the built-in driver in the kernel. ------------- Load MOXA driver--------------------
# cd /usr/src/linux/drivers/char
# mv mxser.c mxser.c.old
For Red Hat 7.x user, you need to create link: 3.4.3 Load the MOXA driver
# cd /usr/src --------------------------
# ln -s linux-2.4 linux
::
# modprobe mxser <argument>
will activate the module driver. You may run "lsmod" to check
if "mxser" is activated. If the MOXA board is ISA board, the
<argument> is needed. Please refer to section "3.4.5" for more
information.
------------- Load MOXA driver on boot --------------------
3.4.4 Load the mxser driver
---------------------------
For the above description, you may manually execute
"modprobe mxser" to activate this driver and run
"rmmod mxser" to remove it.
However, it's better to have a boot time configuration to
eliminate manual operation. Boot time configuration can be
achieved by rc file. We offer one "rc.mxser" file to simplify
the procedure under "moxa/mxser/driver".
But if you use ISA board, please modify the "modprobe ..." command
to add the argument (see "3.4.5" section). After modifying the
rc.mxser, please try to execute "/moxa/mxser/driver/rc.mxser"
manually to make sure the modification is ok. If any error
encountered, please try to modify again. If the modification is
completed, follow the below step.
Run following command for setting rc files::
# cd /moxa/mxser/driver
# cp ./rc.mxser /etc/rc.d
# cd /etc/rc.d
Check "rc.serial" is existed or not. If "rc.serial" doesn't exist,
create it by vi, run "chmod 755 rc.serial" to change the permission.
Add "/etc/rc.d/rc.mxser" in last line.
Reboot and check if moxa.o activated by "lsmod" command.
3.4.5. specify CAP address
--------------------------
If you'd like to drive Smartio/Industio ISA boards in the system,
you'll have to add parameter to specify CAP address of given
board while activating "mxser.o". The format for parameters are
as follows.::
modprobe mxser ioaddr=0x???,0x???,0x???,0x???
| | | |
| | | +- 4th ISA board
| | +------ 3rd ISA board
| +------------ 2nd ISA board
+-------------------1st ISA board
3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x
================================================================
Note:
To use static driver, you must install the linux kernel
source package.
3.5.1 Backup the built-in driver in the kernel
----------------------------------------------
::
# cd /usr/src/linux/drivers/char
# mv mxser.c mxser.c.old
For Red Hat 7.x user, you need to create link:
# cd /usr/src
# ln -s linux-2.4 linux
3.5.2 Create link
-----------------
::
3.5.2 Create link
# cd /usr/src/linux/drivers/char # cd /usr/src/linux/drivers/char
# ln -s /moxa/mxser/driver/mxser.c mxser.c # ln -s /moxa/mxser/driver/mxser.c mxser.c
3.5.3 Add CAP address list for ISA boards. For PCI boards user, 3.5.3 Add CAP address list for ISA boards.
please skip this step. ------------------------------------------
In module mode, the CAP address for ISA board is given by For PCI boards user, please skip this step.
parameter. In static driver configuration, you'll have to
assign it within driver's source code. If you will not In module mode, the CAP address for ISA board is given by
install any ISA boards, you may skip to next portion. parameter. In static driver configuration, you'll have to
The instructions to modify driver source code are as assign it within driver's source code. If you will not
below. install any ISA boards, you may skip to next portion.
a. # cd /moxa/mxser/driver The instructions to modify driver source code are as
# vi mxser.c below.
b. Find the array mxserBoardCAP[] as below.
a. run::
static int mxserBoardCAP[]
= {0x00, 0x00, 0x00, 0x00}; # cd /moxa/mxser/driver
# vi mxser.c
c. Change the address within this array using vi. For
example, to driver 2 ISA boards with CAP address b. Find the array mxserBoardCAP[] as below::
0x280 and 0x180 as 1st and 2nd board. Just to change
the source code as follows. static int mxserBoardCAP[] = {0x00, 0x00, 0x00, 0x00};
static int mxserBoardCAP[] c. Change the address within this array using vi. For
= {0x280, 0x180, 0x00, 0x00}; example, to driver 2 ISA boards with CAP address
0x280 and 0x180 as 1st and 2nd board. Just to change
3.5.4 Setup kernel configuration the source code as follows::
Configure the kernel: static int mxserBoardCAP[] = {0x280, 0x180, 0x00, 0x00};
# cd /usr/src/linux 3.5.4 Setup kernel configuration
# make menuconfig --------------------------------
You will go into a menu-driven system. Please select [Character Configure the kernel::
devices][Non-standard serial port support], enable the [Moxa
SmartIO support] driver with "[*]" for built-in (not "[M]"), then # cd /usr/src/linux
select [Exit] to exit this program. # make menuconfig
3.5.5 Rebuild kernel You will go into a menu-driven system. Please select [Character
The following are for Linux kernel rebuilding, for your devices][Non-standard serial port support], enable the [Moxa
reference only. SmartIO support] driver with "[*]" for built-in (not "[M]"), then
For appropriate details, please refer to the Linux document. select [Exit] to exit this program.
a. cd /usr/src/linux 3.5.5 Rebuild kernel
b. make clean /* take a few minutes */ --------------------
c. make dep /* take a few minutes */
d. make bzImage /* take probably 10-20 minutes */ The following are for Linux kernel rebuilding, for your
e. make install /* copy boot image to correct position */ reference only.
f. Please make sure the boot kernel (vmlinuz) is in the
correct position. For appropriate details, please refer to the Linux document:
g. If you use 'lilo' utility, you should check /etc/lilo.conf
'image' item specified the path which is the 'vmlinuz' path, a. Run the following commands::
or you will load wrong (or old) boot kernel image (vmlinuz).
After checking /etc/lilo.conf, please run "lilo". cd /usr/src/linux
make clean # take a few minutes
make dep # take a few minutes
make bzImage # take probably 10-20 minutes
make install # copy boot image to correct position
f. Please make sure the boot kernel (vmlinuz) is in the
correct position.
g. If you use 'lilo' utility, you should check /etc/lilo.conf
'image' item specified the path which is the 'vmlinuz' path,
or you will load wrong (or old) boot kernel image (vmlinuz).
After checking /etc/lilo.conf, please run "lilo".
Note that if the result of "make bzImage" is ERROR, then you have to Note that if the result of "make bzImage" is ERROR, then you have to
go back to Linux configuration Setup. Type "make menuconfig" in go back to Linux configuration Setup. Type "make menuconfig" in
directory /usr/src/linux. directory /usr/src/linux.
3.5.6 Make tty device and special file 3.5.6 Make tty device and special file
# cd /moxa/mxser/driver --------------------------------------
# ./msmknod
::
# cd /moxa/mxser/driver
# ./msmknod
3.5.7 Make utility
------------------
::
3.5.7 Make utility
# cd /moxa/mxser/utility # cd /moxa/mxser/utility
# make clean; make install # make clean; make install
3.5.8 Reboot 3.5.8 Reboot
------------
3.6 Custom configuration
Although this driver already provides you default configuration, you 3.6 Custom configuration
still can change the device name and major number. The instruction to ========================
change these parameters are shown as below.
Although this driver already provides you default configuration, you
Change Device name still can change the device name and major number. The instruction to
------------------ change these parameters are shown as below.
If you'd like to use other device names instead of default naming
convention, all you have to do is to modify the internal code a. Change Device name
within the shell script "msmknod". First, you have to open "msmknod"
by vi. Locate each line contains "ttyM" and "cum" and change them If you'd like to use other device names instead of default naming
to the device name you desired. "msmknod" creates the device names convention, all you have to do is to modify the internal code
you need next time executed. within the shell script "msmknod". First, you have to open "msmknod"
by vi. Locate each line contains "ttyM" and "cum" and change them
Change Major number to the device name you desired. "msmknod" creates the device names
------------------- you need next time executed.
If major number 30 and 35 had been occupied, you may have to select
2 free major numbers for this driver. There are 3 steps to change b. Change Major number
major numbers.
If major number 30 and 35 had been occupied, you may have to select
3.6.1 Find free major numbers 2 free major numbers for this driver. There are 3 steps to change
In /proc/devices, you may find all the major numbers occupied major numbers.
in the system. Please select 2 major numbers that are available.
e.g. 40, 45. 3.6.1 Find free major numbers
3.6.2 Create special files -----------------------------
Run /moxa/mxser/driver/msmknod to create special files with
specified major numbers. In /proc/devices, you may find all the major numbers occupied
3.6.3 Modify driver with new major number in the system. Please select 2 major numbers that are available.
Run vi to open /moxa/mxser/driver/mxser.c. Locate the line e.g. 40, 45.
contains "MXSERMAJOR". Change the content as below.
3.6.2 Create special files
--------------------------
Run /moxa/mxser/driver/msmknod to create special files with
specified major numbers.
3.6.3 Modify driver with new major number
-----------------------------------------
Run vi to open /moxa/mxser/driver/mxser.c. Locate the line
contains "MXSERMAJOR". Change the content as below::
#define MXSERMAJOR 40 #define MXSERMAJOR 40
#define MXSERCUMAJOR 45 #define MXSERCUMAJOR 45
3.6.4 Run "make clean; make install" in /moxa/mxser/driver.
3.7 Verify driver installation 3.6.4 Run "make clean; make install" in /moxa/mxser/driver.
You may refer to /var/log/messages to check the latest status
log reported by this driver whenever it's activated. 3.7 Verify driver installation
==============================
You may refer to /var/log/messages to check the latest status
log reported by this driver whenever it's activated.
-----------------------------------------------------------------------------
4. Utilities 4. Utilities
^^^^^^^^^^^^
There are 3 utilities contained in this driver. They are msdiag, msmon and There are 3 utilities contained in this driver. They are msdiag, msmon and
msterm. These 3 utilities are released in form of source code. They should msterm. These 3 utilities are released in form of source code. They should
be compiled into executable file and copied into /usr/bin. be compiled into executable file and copied into /usr/bin.
...@@ -430,16 +508,19 @@ Content ...@@ -430,16 +508,19 @@ Content
Before using these utilities, please load driver (refer 3.4 & 3.5) and Before using these utilities, please load driver (refer 3.4 & 3.5) and
make sure you had run the "msmknod" utility. make sure you had run the "msmknod" utility.
msdiag - Diagnostic msdiag - Diagnostic
-------------------- ===================
This utility provides the function to display what Moxa Smartio/Industio This utility provides the function to display what Moxa Smartio/Industio
board found by driver in the system. board found by driver in the system.
msmon - Port Monitoring msmon - Port Monitoring
----------------------- =======================
This utility gives the user a quick view about all the MOXA ports' This utility gives the user a quick view about all the MOXA ports'
activities. One can easily learn each port's total received/transmitted activities. One can easily learn each port's total received/transmitted
(Rx/Tx) character count since the time when the monitoring is started. (Rx/Tx) character count since the time when the monitoring is started.
Rx/Tx throughputs per second are also reported in interval basis (e.g. Rx/Tx throughputs per second are also reported in interval basis (e.g.
the last 5 seconds) and in average basis (since the time the monitoring the last 5 seconds) and in average basis (since the time the monitoring
is started). You can reset all ports' count by <HOME> key. <+> <-> is started). You can reset all ports' count by <HOME> key. <+> <->
...@@ -447,19 +528,21 @@ Content ...@@ -447,19 +528,21 @@ Content
on the port, that cursor stay, to view the port's communication on the port, that cursor stay, to view the port's communication
parameters, signal status, and input/output queue. parameters, signal status, and input/output queue.
msterm - Terminal Emulation msterm - Terminal Emulation
--------------------------- ===========================
This utility provides data sending and receiving ability of all tty ports, This utility provides data sending and receiving ability of all tty ports,
especially for MOXA ports. It is quite useful for testing simple especially for MOXA ports. It is quite useful for testing simple
application, for example, sending AT command to a modem connected to the application, for example, sending AT command to a modem connected to the
port or used as a terminal for login purpose. Note that this is only a port or used as a terminal for login purpose. Note that this is only a
dumb terminal emulation without handling full screen operation. dumb terminal emulation without handling full screen operation.
-----------------------------------------------------------------------------
5. Setserial 5. Setserial
^^^^^^^^^^^^
Supported Setserial parameters are listed as below. Supported Setserial parameters are listed as below.
============== =========================================================
uart set UART type(16450-->disable FIFO, 16550A-->enable FIFO) uart set UART type(16450-->disable FIFO, 16550A-->enable FIFO)
close_delay set the amount of time(in 1/100 of a second) that DTR close_delay set the amount of time(in 1/100 of a second) that DTR
should be kept low while being closed. should be kept low while being closed.
...@@ -475,49 +558,58 @@ Content ...@@ -475,49 +558,58 @@ Content
application requests 38.4kb. application requests 38.4kb.
divisor This option set the custom division. divisor This option set the custom division.
baud_base This option set the base baud rate. baud_base This option set the base baud rate.
============== =========================================================
-----------------------------------------------------------------------------
6. Troubleshooting 6. Troubleshooting
^^^^^^^^^^^^^^^^^^
The boot time error messages and solutions are stated as clearly as The boot time error messages and solutions are stated as clearly as
possible. If all the possible solutions fail, please contact our technical possible. If all the possible solutions fail, please contact our technical
support team to get more help. support team to get more help.
Error msg: More than 4 Moxa Smartio/Industio family boards found. Fifth board Error msg:
More than 4 Moxa Smartio/Industio family boards found. Fifth board
and after are ignored. and after are ignored.
Solution: Solution:
To avoid this problem, please unplug fifth and after board, because Moxa To avoid this problem, please unplug fifth and after board, because Moxa
driver supports up to 4 boards. driver supports up to 4 boards.
Error msg: Request_irq fail, IRQ(?) may be conflict with another device. Error msg:
Request_irq fail, IRQ(?) may be conflict with another device.
Solution: Solution:
Other PCI or ISA devices occupy the assigned IRQ. If you are not sure Other PCI or ISA devices occupy the assigned IRQ. If you are not sure
which device causes the situation, please check /proc/interrupts to find which device causes the situation, please check /proc/interrupts to find
free IRQ and simply change another free IRQ for Moxa board. free IRQ and simply change another free IRQ for Moxa board.
Error msg: Board #: C1xx Series(CAP=xxx) interrupt number invalid. Error msg:
Board #: C1xx Series(CAP=xxx) interrupt number invalid.
Solution: Solution:
Each port within the same multiport board shares the same IRQ. Please set Each port within the same multiport board shares the same IRQ. Please set
one IRQ (IRQ doesn't equal to zero) for one Moxa board. one IRQ (IRQ doesn't equal to zero) for one Moxa board.
Error msg: No interrupt vector be set for Moxa ISA board(CAP=xxx). Error msg:
No interrupt vector be set for Moxa ISA board(CAP=xxx).
Solution: Solution:
Moxa ISA board needs an interrupt vector.Please refer to user's manual Moxa ISA board needs an interrupt vector.Please refer to user's manual
"Hardware Installation" chapter to set interrupt vector. "Hardware Installation" chapter to set interrupt vector.
Error msg: Couldn't install MOXA Smartio/Industio family driver! Error msg:
Couldn't install MOXA Smartio/Industio family driver!
Solution: Solution:
Load Moxa driver fail, the major number may conflict with other devices. Load Moxa driver fail, the major number may conflict with other devices.
Please refer to previous section 3.7 to change a free major number for Please refer to previous section 3.7 to change a free major number for
Moxa driver. Moxa driver.
Error msg: Couldn't install MOXA Smartio/Industio family callout driver! Error msg:
Couldn't install MOXA Smartio/Industio family callout driver!
Solution: Solution:
Load Moxa callout driver fail, the callout device major number may Load Moxa callout driver fail, the callout device major number may
conflict with other devices. Please refer to previous section 3.7 to conflict with other devices. Please refer to previous section 3.7 to
change a free callout device major number for Moxa driver. change a free callout device major number for Moxa driver.
-----------------------------------------------------------------------------
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 This line discipline implements the GSM 07.10 multiplexing protocol
detailed in the following 3GPP document : detailed in the following 3GPP document:
http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
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 This document give some hints on how to use this driver with GPRS and 3G
modems connected to a physical serial port. modems connected to a physical serial port.
How to use it 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 its serial port. Depending on the modem used, you can pass more or less
parameters to this command, 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, 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 : 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 */ #include <linux/gsmmux.h>
#define DEFAULT_SPEED B115200 #define N_GSM0710 21 /* GSM 0710 Mux */
#define SERIAL_PORT /dev/ttyS0 #define DEFAULT_SPEED B115200
#define SERIAL_PORT /dev/ttyS0
int ldisc = N_GSM0710; int ldisc = N_GSM0710;
struct gsm_config c; struct gsm_config c;
...@@ -60,37 +63,41 @@ Major parts of the initialization program : ...@@ -60,37 +63,41 @@ Major parts of the initialization program :
daemon(0,0); daemon(0,0);
pause(); 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, each modem has its configuration and some DLC have dedicated functions,
for example GPS), starting with minor 1 (DLC0 is reserved for the management 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}` MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}`
for i in `seq 1 4`; do for i in `seq 1 4`; do
mknod /dev/ttygsm$i c $MAJOR $i 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:
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. - 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 6. first close all virtual ports before closing the physical port.
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 Note that after closing the physical port the modem is still in multiplexing
a disconnect command frame manually before initializing the multiplexing mode mode. This may prevent a successful re-opening of the port later. To avoid
for the second time. The byte sequence for the disconnect command frame is: this situation either reset the modem if your hardware allows that or send
0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9. 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 Additional Documentation
------------------------ ------------------------
More practical details on the protocol and how it's supported by industrial More practical details on the protocol and how it's supported by industrial
modems can be found in the following documents : 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.telit.com/module/infopool/download.php?id=616
http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx - http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf
http://wm.sim.com/sim/News/photo/2010721161442.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> 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 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 high-speed serial ports or modems. This driver supports up to a combination
of four RocketPort or RocketModems boards in one machine simultaneously. of four RocketPort or RocketModems boards in one machine simultaneously.
This file assumes that you are using the RocketPort driver which is 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 The driver can also be installed as an external module using the usual
"make;make install" routine. This external module driver, obtainable "make;make install" routine. This external module driver, obtainable
from the Comtrol website listed below, is useful for updating the driver from the Comtrol website listed below, is useful for updating the driver
or installing it into kernels which do not have the driver configured or installing it into kernels which do not have the driver configured
into them. Installations instructions for the external module into them. Installations instructions for the external module
...@@ -29,57 +31,59 @@ information on how to set the DIP switches. ...@@ -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: You pass the I/O port to the driver using the following module parameters:
board1 : I/O port for the first ISA board board1:
board2 : I/O port for the second ISA board I/O port for the first ISA board
board3 : I/O port for the third ISA board board2:
board4 : I/O port for the fourth ISA board 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 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. setup of the ISA cards.
The RocketModem II PCI boards require firmware to be loaded into the card 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 before it will function. The driver has only been tested as a module for this
board. 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. 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` 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 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 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 installed in the system, the mapping of port names to serial ports is displayed
in the system log at /var/log/messages. in the system log at /var/log/messages.
If installed as a module, the module must be loaded. This can be done 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 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". "alias char-major-46 rocket".
In order to use the ports, their device names (nodes) must be created with mknod. 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 This is only required once, the system will retain the names once created. To
create the RocketPort/RocketModem device names, use the command 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 For example::
>mknod /dev/ttyR1 c 46 1
>mknod /dev/ttyR2 c 46 2
The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes) > mknod /dev/ttyR0 c 46 0
for you: > 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 ISA Rocketport Boards
--------------------- ---------------------
...@@ -89,7 +93,7 @@ card before installing and using it. This is done by setting a set of DIP ...@@ -89,7 +93,7 @@ card before installing and using it. This is done by setting a set of DIP
switches on the Rocketport board. 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 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 ...@@ -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 need to set the second, third, or fourth board to one of the next available
blocks such as 0x180. blocks such as 0x180.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- RocketPort and RocketPort RA SW1 Settings::
RocketPort and RocketPort RA SW1 Settings: +-------------------------------+
| 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
+-------------------------------+ +-------+-------+---------------+
| 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | | Unused| Card | I/O Port Block|
+-------+-------+---------------+ +-------------------------------+
| Unused| Card | I/O Port Block|
+-------------------------------+ DIP Switches DIP Switches
7 8 6 5
DIP Switches DIP Switches =================== ===================
7 8 6 5 On On UNUSED, MUST BE ON. On On First Card <==== Default
=================== =================== On Off Second Card
On On UNUSED, MUST BE ON. On On First Card <==== Default Off On Third Card
On Off Second Card Off Off Fourth Card
Off On Third Card
Off Off Fourth Card DIP Switches I/O Address Range
4 3 2 1 Used by the First 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 On Off 100-143 On Off Off Off 180-1C3 <==== Default
On Off Off On 140-183 Off On On Off 200-243
On Off Off Off 180-1C3 <==== Default Off On Off On 240-283
Off On On Off 200-243 Off On Off Off 280-2C3
Off On Off On 240-283 Off Off On Off 300-343
Off On Off Off 280-2C3 Off Off Off On 340-383
Off Off On Off 300-343 Off Off Off Off 380-3C3
Off Off Off On 340-383
Off Off Off Off 380-3C3 Reporting Bugs
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
REPORTING BUGS
-------------- --------------
For technical support, please provide the following For technical support, please provide the following
...@@ -171,19 +171,15 @@ information: Driver version, kernel release, distribution of ...@@ -171,19 +171,15 @@ information: Driver version, kernel release, distribution of
kernel, and type of board you are using. Error messages and log kernel, and type of board you are using. Error messages and log
printouts port configuration details are especially helpful. printouts port configuration details are especially helpful.
USA USA:
Phone: (612) 494-4100 :Phone: (612) 494-4100
FAX: (612) 494-4199 :FAX: (612) 494-4199
email: support@comtrol.com :email: support@comtrol.com
Comtrol Europe Comtrol Europe:
Phone: +44 (0) 1 869 323-220 :Phone: +44 (0) 1 869 323-220
FAX: +44 (0) 1 869 323-211 :FAX: +44 (0) 1 869 323-211
email: support@comtrol.co.uk :email: support@comtrol.co.uk
Web: http://www.comtrol.com Web: http://www.comtrol.com
FTP: ftp.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) ISO/IEC7816 is a series of standards specifying integrated circuit cards (ICC)
also known as smart cards. 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 Some CPUs/UARTs (e.g., Microchip AT91) contain a built-in mode capable of
handling communication with a smart card. handling communication with a smart card.
...@@ -15,7 +19,8 @@ ...@@ -15,7 +19,8 @@
available at user-level to allow switching from one mode to the other, and available at user-level to allow switching from one mode to the other, and
vice versa. 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 The Linux kernel provides the serial_iso7816 structure (see [1]) to handle
ISO7816 communications. This data structure is used to set and configure ISO7816 communications. This data structure is used to set and configure
...@@ -27,10 +32,11 @@ ...@@ -27,10 +32,11 @@
to TIOCGISO7816 and TIOCSISO7816 ioctls (see below). The iso7816_config to TIOCGISO7816 and TIOCSISO7816 ioctls (see below). The iso7816_config
callback receives a pointer to struct serial_iso7816. 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 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> #include <linux/serial.h>
...@@ -78,6 +84,7 @@ ...@@ -78,6 +84,7 @@
/* Error handling. See errno. */ /* Error handling. See errno. */
} }
5. REFERENCES 5. References
=============
[1] include/uapi/linux/serial.h [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 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 electrical characteristics of drivers and receivers for use in balanced
...@@ -9,7 +12,8 @@ ...@@ -9,7 +12,8 @@
because it can be used effectively over long distances and in electrically because it can be used effectively over long distances and in electrically
noisy environments. noisy environments.
2. HARDWARE-RELATED CONSIDERATIONS 2. Hardware-related Considerations
==================================
Some CPUs/UARTs (e.g., Atmel AT91 or 16C950 UART) contain a built-in Some CPUs/UARTs (e.g., Atmel AT91 or 16C950 UART) contain a built-in
half-duplex mode capable of automatically controlling line direction by half-duplex mode capable of automatically controlling line direction by
...@@ -22,7 +26,8 @@ ...@@ -22,7 +26,8 @@
available at user-level to allow switching from one mode to the other, and available at user-level to allow switching from one mode to the other, and
vice versa. 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 The Linux kernel provides the serial_rs485 structure (see [1]) to handle
RS485 communications. This data structure is used to set and configure RS485 RS485 communications. This data structure is used to set and configure RS485
...@@ -38,10 +43,11 @@ ...@@ -38,10 +43,11 @@
to TIOCSRS485 and TIOCGRS485 ioctls (see below). The rs485_config callback to TIOCSRS485 and TIOCGRS485 ioctls (see below). The rs485_config callback
receives a pointer to struct serial_rs485. 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 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> #include <linux/serial.h>
...@@ -89,7 +95,9 @@ ...@@ -89,7 +95,9 @@
/* Error handling. See errno. */ /* Error handling. See errno. */
} }
5. REFERENCES 5. References
=============
[1] include/uapi/linux/serial.h [1] include/uapi/linux/serial.h
[2] Documentation/devicetree/bindings/serial/rs485.txt [2] Documentation/devicetree/bindings/serial/rs485.txt
Documentation/serial/tty.txt → Documentation/serial/tty.rst
View file @ f1374017
=================
The Lockronomicon The Lockronomicon
=================
Your guide to the ancient and twisted locking policies of the tty layer and Your guide to the ancient and twisted locking policies of the tty layer and
the warped logic behind them. Beware all ye who read on. the warped logic behind them. Beware all ye who read on.
...@@ -9,12 +10,12 @@ Line Discipline ...@@ -9,12 +10,12 @@ Line Discipline
--------------- ---------------
Line disciplines are registered with tty_register_ldisc() passing the Line disciplines are registered with tty_register_ldisc() passing the
discipline number and the ldisc structure. At the point of registration the discipline number and the ldisc structure. At the point of registration the
discipline must be ready to use and it is possible it will get used before discipline must be ready to use and it is possible it will get used before
the call returns success. If the call returns an error then it won't get the call returns success. If the call returns an error then it won't get
called. Do not re-use ldisc numbers as they are part of the userspace ABI called. Do not re-use ldisc numbers as they are part of the userspace ABI
and writing over an existing ldisc will cause demons to eat your computer. and writing over an existing ldisc will cause demons to eat your computer.
After the return the ldisc data has been copied so you may free your own After the return the ldisc data has been copied so you may free your own
copy of the structure. You must not re-register over the top of the line copy of the structure. You must not re-register over the top of the line
discipline even with the same data or your computer again will be eaten by discipline even with the same data or your computer again will be eaten by
demons. demons.
...@@ -26,7 +27,7 @@ code manages the module counts this should not usually be a concern. ...@@ -26,7 +27,7 @@ code manages the module counts this should not usually be a concern.
Heed this warning: the reference count field of the registered copies of the Heed this warning: the reference count field of the registered copies of the
tty_ldisc structure in the ldisc table counts the number of lines using this tty_ldisc structure in the ldisc table counts the number of lines using this
discipline. The reference count of the tty_ldisc structure within a tty discipline. The reference count of the tty_ldisc structure within a tty
counts the number of active users of the ldisc at this instant. In effect it counts the number of active users of the ldisc at this instant. In effect it
counts the number of threads of execution within an ldisc method (plus those counts the number of threads of execution within an ldisc method (plus those
about to enter and exit although this detail matters not). about to enter and exit although this detail matters not).
...@@ -34,9 +35,11 @@ about to enter and exit although this detail matters not). ...@@ -34,9 +35,11 @@ about to enter and exit although this detail matters not).
Line Discipline Methods Line Discipline Methods
----------------------- -----------------------
TTY side interfaces: TTY side interfaces
^^^^^^^^^^^^^^^^^^^
open() - Called when the line discipline is attached to ======================= =======================================================
open() Called when the line discipline is attached to
the terminal. No other call into the line the terminal. No other call into the line
discipline for this tty will occur until it discipline for this tty will occur until it
completes successfully. Should initialize any completes successfully. Should initialize any
...@@ -47,66 +50,69 @@ open() - Called when the line discipline is attached to ...@@ -47,66 +50,69 @@ open() - Called when the line discipline is attached to
Returning an error will prevent the ldisc from Returning an error will prevent the ldisc from
being attached. Can sleep. being attached. Can sleep.
close() - This is called on a terminal when the line close() This is called on a terminal when the line
discipline is being unplugged. At the point of discipline is being unplugged. At the point of
execution no further users will enter the execution no further users will enter the
ldisc code for this tty. Can sleep. ldisc code for this tty. Can sleep.
hangup() - Called when the tty line is hung up. hangup() Called when the tty line is hung up.
The line discipline should cease I/O to the tty. The line discipline should cease I/O to the tty.
No further calls into the ldisc code will occur. No further calls into the ldisc code will occur.
The return value is ignored. Can sleep. The return value is ignored. Can sleep.
read() - (optional) A process requests reading data from read() (optional) A process requests reading data from
the line. Multiple read calls may occur in parallel the line. Multiple read calls may occur in parallel
and the ldisc must deal with serialization issues. and the ldisc must deal with serialization issues.
If not defined, the process will receive an EIO If not defined, the process will receive an EIO
error. May sleep. error. May sleep.
write() - (optional) A process requests writing data to the write() (optional) A process requests writing data to the
line. Multiple write calls are serialized by the line. Multiple write calls are serialized by the
tty layer for the ldisc. If not defined, the tty layer for the ldisc. If not defined, the
process will receive an EIO error. May sleep. process will receive an EIO error. May sleep.
flush_buffer() - (optional) May be called at any point between flush_buffer() (optional) May be called at any point between
open and close, and instructs the line discipline open and close, and instructs the line discipline
to empty its input buffer. to empty its input buffer.
set_termios() - (optional) Called on termios structure changes. set_termios() (optional) Called on termios structure changes.
The caller passes the old termios data and the The caller passes the old termios data and the
current data is in the tty. Called under the current data is in the tty. Called under the
termios semaphore so allowed to sleep. Serialized termios semaphore so allowed to sleep. Serialized
against itself only. against itself only.
poll() - (optional) Check the status for the poll/select poll() (optional) Check the status for the poll/select
calls. Multiple poll calls may occur in parallel. calls. Multiple poll calls may occur in parallel.
May sleep. May sleep.
ioctl() - (optional) Called when an ioctl is handed to the ioctl() (optional) Called when an ioctl is handed to the
tty layer that might be for the ldisc. Multiple tty layer that might be for the ldisc. Multiple
ioctl calls may occur in parallel. May sleep. ioctl calls may occur in parallel. May sleep.
compat_ioctl() - (optional) Called when a 32 bit ioctl is handed compat_ioctl() (optional) Called when a 32 bit ioctl is handed
to the tty layer that might be for the ldisc. to the tty layer that might be for the ldisc.
Multiple ioctl calls may occur in parallel. Multiple ioctl calls may occur in parallel.
May sleep. May sleep.
======================= =======================================================
Driver Side Interfaces: Driver Side Interfaces
^^^^^^^^^^^^^^^^^^^^^^
receive_buf() - (optional) Called by the low-level driver to hand ======================= =======================================================
receive_buf() (optional) Called by the low-level driver to hand
a buffer of received bytes to the ldisc for a buffer of received bytes to the ldisc for
processing. The number of bytes is guaranteed not processing. The number of bytes is guaranteed not
to exceed the current value of tty->receive_room. to exceed the current value of tty->receive_room.
All bytes must be processed. All bytes must be processed.
receive_buf2() - (optional) Called by the low-level driver to hand receive_buf2() (optional) Called by the low-level driver to hand
a buffer of received bytes to the ldisc for a buffer of received bytes to the ldisc for
processing. Returns the number of bytes processed. processing. Returns the number of bytes processed.
If both receive_buf() and receive_buf2() are If both receive_buf() and receive_buf2() are
defined, receive_buf2() should be preferred. defined, receive_buf2() should be preferred.
write_wakeup() - May be called at any point between open and close. write_wakeup() May be called at any point between open and close.
The TTY_DO_WRITE_WAKEUP flag indicates if a call The TTY_DO_WRITE_WAKEUP flag indicates if a call
is needed but always races versus calls. Thus the is needed but always races versus calls. Thus the
ldisc must be careful about setting order and to ldisc must be careful about setting order and to
...@@ -117,17 +123,20 @@ write_wakeup() - May be called at any point between open and close. ...@@ -117,17 +123,20 @@ write_wakeup() - May be called at any point between open and close.
is permitted to call the driver write method from is permitted to call the driver write method from
this function. In such a situation defer it. this function. In such a situation defer it.
dcd_change() - Report to the tty line the current DCD pin status dcd_change() Report to the tty line the current DCD pin status
changes and the relative timestamp. The timestamp changes and the relative timestamp. The timestamp
cannot be NULL. cannot be NULL.
======================= =======================================================
Driver Access Driver Access
^^^^^^^^^^^^^
Line discipline methods can call the following methods of the underlying Line discipline methods can call the following methods of the underlying
hardware driver through the function pointers within the tty->driver hardware driver through the function pointers within the tty->driver
structure: structure:
======================= =======================================================
write() Write a block of characters to the tty device. write() Write a block of characters to the tty device.
Returns the number of characters accepted. The Returns the number of characters accepted. The
character buffer passed to this method is already character buffer passed to this method is already
...@@ -189,13 +198,16 @@ wait_until_sent() Waits until the device has written out all of the ...@@ -189,13 +198,16 @@ wait_until_sent() Waits until the device has written out all of the
characters in its transmitter FIFO. characters in its transmitter FIFO.
send_xchar() Send a high-priority XON/XOFF character to the device. send_xchar() Send a high-priority XON/XOFF character to the device.
======================= =======================================================
Flags Flags
^^^^^
Line discipline methods have access to tty->flags field containing the Line discipline methods have access to tty->flags field containing the
following interesting flags: following interesting flags:
======================= =======================================================
TTY_THROTTLED Driver input is throttled. The ldisc should call TTY_THROTTLED Driver input is throttled. The ldisc should call
tty->driver->unthrottle() in order to resume tty->driver->unthrottle() in order to resume
reception when it is ready to process more data. reception when it is ready to process more data.
...@@ -212,102 +224,105 @@ TTY_OTHER_CLOSED Device is a pty and the other side has closed. ...@@ -212,102 +224,105 @@ TTY_OTHER_CLOSED Device is a pty and the other side has closed.
TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into
smaller chunks. smaller chunks.
======================= =======================================================
Locking Locking
^^^^^^^
Callers to the line discipline functions from the tty layer are required to Callers to the line discipline functions from the tty layer are required to
take line discipline locks. The same is true of calls from the driver side take line discipline locks. The same is true of calls from the driver side
but not yet enforced. but not yet enforced.
Three calls are now provided Three calls are now provided::
ldisc = tty_ldisc_ref(tty); ldisc = tty_ldisc_ref(tty);
takes a handle to the line discipline in the tty and returns it. If no ldisc takes a handle to the line discipline in the tty and returns it. If no ldisc
is currently attached or the ldisc is being closed and re-opened at this is currently attached or the ldisc is being closed and re-opened at this
point then NULL is returned. While this handle is held the ldisc will not point then NULL is returned. While this handle is held the ldisc will not
change or go away. change or go away::
tty_ldisc_deref(ldisc) tty_ldisc_deref(ldisc)
Returns the ldisc reference and allows the ldisc to be closed. Returning the Returns the ldisc reference and allows the ldisc to be closed. Returning the
reference takes away your right to call the ldisc functions until you take reference takes away your right to call the ldisc functions until you take
a new reference. a new reference::
ldisc = tty_ldisc_ref_wait(tty); ldisc = tty_ldisc_ref_wait(tty);
Performs the same function as tty_ldisc_ref except that it will wait for an Performs the same function as tty_ldisc_ref except that it will wait for an
ldisc change to complete and then return a reference to the new ldisc. ldisc change to complete and then return a reference to the new ldisc.
While these functions are slightly slower than the old code they should have While these functions are slightly slower than the old code they should have
minimal impact as most receive logic uses the flip buffers and they only minimal impact as most receive logic uses the flip buffers and they only
need to take a reference when they push bits up through the driver. need to take a reference when they push bits up through the driver.
A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc
functions are called with the ldisc unavailable. Thus tty_ldisc_ref will functions are called with the ldisc unavailable. Thus tty_ldisc_ref will
fail in this situation if used within these functions. Ldisc and driver fail in this situation if used within these functions. Ldisc and driver
code calling its own functions must be careful in this case. code calling its own functions must be careful in this case.
Driver Interface Driver Interface
---------------- ----------------
open() - Called when a device is opened. May sleep ======================= =======================================================
open() Called when a device is opened. May sleep
close() - Called when a device is closed. At the point of close() Called when a device is closed. At the point of
return from this call the driver must make no return from this call the driver must make no
further ldisc calls of any kind. May sleep further ldisc calls of any kind. May sleep
write() - Called to write bytes to the device. May not write() Called to write bytes to the device. May not
sleep. May occur in parallel in special cases. sleep. May occur in parallel in special cases.
Because this includes panic paths drivers generally Because this includes panic paths drivers generally
shouldn't try and do clever locking here. shouldn't try and do clever locking here.
put_char() - Stuff a single character onto the queue. The put_char() Stuff a single character onto the queue. The
driver is guaranteed following up calls to driver is guaranteed following up calls to
flush_chars. flush_chars.
flush_chars() - Ask the kernel to write put_char queue flush_chars() Ask the kernel to write put_char queue
write_room() - Return the number of characters that can be stuffed write_room() Return the number of characters that can be stuffed
into the port buffers without overflow (or less). into the port buffers without overflow (or less).
The ldisc is responsible for being intelligent The ldisc is responsible for being intelligent
about multi-threading of write_room/write calls about multi-threading of write_room/write calls
ioctl() - Called when an ioctl may be for the driver ioctl() Called when an ioctl may be for the driver
set_termios() - Called on termios change, serialized against set_termios() Called on termios change, serialized against
itself by a semaphore. May sleep. itself by a semaphore. May sleep.
set_ldisc() - Notifier for discipline change. At the point this set_ldisc() Notifier for discipline change. At the point this
is done the discipline is not yet usable. Can now is done the discipline is not yet usable. Can now
sleep (I think) sleep (I think)
throttle() - Called by the ldisc to ask the driver to do flow throttle() Called by the ldisc to ask the driver to do flow
control. Serialization including with unthrottle control. Serialization including with unthrottle
is the job of the ldisc layer. is the job of the ldisc layer.
unthrottle() - Called by the ldisc to ask the driver to stop flow unthrottle() Called by the ldisc to ask the driver to stop flow
control. control.
stop() - Ldisc notifier to the driver to stop output. As with stop() Ldisc notifier to the driver to stop output. As with
throttle the serializations with start() are down throttle the serializations with start() are down
to the ldisc layer. to the ldisc layer.
start() - Ldisc notifier to the driver to start output. start() Ldisc notifier to the driver to start output.
hangup() - Ask the tty driver to cause a hangup initiated hangup() Ask the tty driver to cause a hangup initiated
from the host side. [Can sleep ??] from the host side. [Can sleep ??]
break_ctl() - Send RS232 break. Can sleep. Can get called in break_ctl() Send RS232 break. Can sleep. Can get called in
parallel, driver must serialize (for now), and parallel, driver must serialize (for now), and
with write calls. with write calls.
wait_until_sent() - Wait for characters to exit the hardware queue wait_until_sent() Wait for characters to exit the hardware queue
of the driver. Can sleep of the driver. Can sleep
send_xchar() - Send XON/XOFF and if possible jump the queue with send_xchar() Send XON/XOFF and if possible jump the queue with
it in order to get fast flow control responses. it in order to get fast flow control responses.
Cannot sleep ?? Cannot sleep ??
======================= =======================================================
MAINTAINERS
View file @ f1374017
...@@ -10433,7 +10433,7 @@ F: include/uapi/linux/meye.h ...@@ -10433,7 +10433,7 @@ F: include/uapi/linux/meye.h
MOXA SMARTIO/INDUSTIO/INTELLIO SERIAL CARD MOXA SMARTIO/INDUSTIO/INTELLIO SERIAL CARD
M: Jiri Slaby <jirislaby@gmail.com> M: Jiri Slaby <jirislaby@gmail.com>
S: Maintained S: Maintained
F: Documentation/serial/moxa-smartio F: Documentation/serial/moxa-smartio.rst
F: drivers/tty/mxser.* F: drivers/tty/mxser.*
MR800 AVERMEDIA USB FM RADIO DRIVER MR800 AVERMEDIA USB FM RADIO DRIVER
...@@ -13317,7 +13317,7 @@ ROCKETPORT DRIVER ...@@ -13317,7 +13317,7 @@ ROCKETPORT DRIVER
P: Comtrol Corp. P: Comtrol Corp.
W: http://www.comtrol.com W: http://www.comtrol.com
S: Maintained S: Maintained
F: Documentation/serial/rocket.txt F: Documentation/serial/rocket.rst
F: drivers/tty/rocket* F: drivers/tty/rocket*
ROCKETPORT EXPRESS/INFINITY DRIVER ROCKETPORT EXPRESS/INFINITY DRIVER
......
drivers/tty/Kconfig
View file @ f1374017
...@@ -175,7 +175,7 @@ config ROCKETPORT ...@@ -175,7 +175,7 @@ config ROCKETPORT
This driver supports Comtrol RocketPort and RocketModem PCI boards. This driver supports Comtrol RocketPort and RocketModem PCI boards.
These boards provide 2, 4, 8, 16, or 32 high-speed serial ports or These boards provide 2, 4, 8, 16, or 32 high-speed serial ports or
modems. For information about the RocketPort/RocketModem boards 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 To compile this driver as a module, choose M here: the
module will be called rocket. module will be called rocket.
...@@ -193,7 +193,7 @@ config CYCLADES ...@@ -193,7 +193,7 @@ config CYCLADES
your Linux box, for instance in order to become a dial-in server. your Linux box, for instance in order to become a dial-in server.
For information about the Cyclades-Z card, read 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 To compile this driver as a module, choose M here: the
module will be called cyclades. 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, ...@@ -1081,7 +1081,7 @@ static int qe_uart_verify_port(struct uart_port *port,
} }
/* UART operations /* 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 = { static const struct uart_ops qe_uart_pops = {
.tx_empty = qe_uart_tx_empty, .tx_empty = qe_uart_tx_empty,
......
include/linux/serial_core.h
View file @ f1374017
...@@ -45,7 +45,7 @@ struct device; ...@@ -45,7 +45,7 @@ struct device;
/* /*
* This structure describes all the operations that can be done on the * 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 { struct uart_ops {
unsigned int (*tx_empty)(struct uart_port *); 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