Merge tag 'tty-5.17-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty
Pull tty/serial driver updates from Greg KH:
"Here is the big set of tty/serial driver updates for 5.17-rc1.
Nothing major in here, just lots of good updates and fixes, including:
- more tty core cleanups from Jiri as well as mxser driver cleanups.
This is the majority of the core diffstat
- tty documentation updates from Jiri
- platform_get_irq() updates
- various serial driver updates for new features and hardware
- fifo usage for 8250 console, reducing cpu load a lot
- LED fix for keyboards, long-time bugfix that went through many
revisions
- minor cleanups
All have been in linux-next for a while with no reported problems"
* tag 'tty-5.17-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty: (119 commits)
serial: core: Keep mctrl register state and cached copy in sync
serial: stm32: correct loop for dma error handling
serial: stm32: fix flow control transfer in DMA mode
serial: stm32: rework TX DMA state condition
serial: stm32: move tx dma terminate DMA to shutdown
serial: pl011: Drop redundant DTR/RTS preservation on close/open
serial: pl011: Drop CR register reset on set_termios
serial: pl010: Drop CR register reset on set_termios
serial: liteuart: fix MODULE_ALIAS
serial: 8250_bcm7271: Fix return error code in case of dma_alloc_coherent() failure
Revert "serdev: BREAK/FRAME/PARITY/OVERRUN notification prototype V2"
tty: goldfish: Use platform_get_irq() to get the interrupt
serdev: BREAK/FRAME/PARITY/OVERRUN notification prototype V2
tty: serial: meson: Drop the legacy compatible strings and clock code
serial: pmac_zilog: Use platform_get_irq() to get the interrupt
serial: bcm63xx: Use platform_get_irq() to get the interrupt
serial: ar933x: Use platform_get_irq() to get the interrupt
serial: vt8500: Use platform_get_irq() to get the interrupt
serial: altera_jtaguart: Use platform_get_irq_optional() to get the interrupt
serial: pxa: Use platform_get_irq() to get the interrupt
...
This commit is contained in:
Linus Torvalds
@@ -9,7 +9,6 @@ Support for Serial devices
|
||||
|
||||
|
||||
driver
|
||||
tty
|
||||
|
||||
Serial drivers
|
||||
==============
|
||||
|
||||
@@ -18,9 +18,12 @@ How to use it
|
||||
1.1 initialize the modem in 0710 mux mode (usually AT+CMUX= command) through
|
||||
its serial port. Depending on the modem used, you can pass more or less
|
||||
parameters to this command.
|
||||
|
||||
1.2 switch the serial line to using the n_gsm line discipline by using
|
||||
TIOCSETD ioctl.
|
||||
|
||||
1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
|
||||
|
||||
1.4 obtain base gsmtty number for the used serial port.
|
||||
|
||||
Major parts of the initialization program :
|
||||
@@ -95,10 +98,13 @@ Major parts of the initialization program :
|
||||
|
||||
2.1 receive string "AT+CMUX= command" through its serial port,initialize
|
||||
mux mode config
|
||||
|
||||
2.2 switch the serial line to using the n_gsm line discipline by using
|
||||
TIOCSETD ioctl.
|
||||
|
||||
2.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
|
||||
2.4 obtain base gsmtty number for the used serial port,
|
||||
|
||||
2.4 obtain base gsmtty number for the used serial port::
|
||||
|
||||
#include <stdio.h>
|
||||
#include <stdint.h>
|
||||
|
||||
@@ -1,328 +0,0 @@
|
||||
=================
|
||||
The Lockronomicon
|
||||
=================
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Line Discipline
|
||||
---------------
|
||||
|
||||
Line disciplines are registered with tty_register_ldisc() passing 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
|
||||
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
|
||||
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
|
||||
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
|
||||
demons.
|
||||
|
||||
In order to remove a line discipline call tty_unregister_ldisc().
|
||||
In ancient times this always worked. In modern times the function will
|
||||
return -EBUSY if the ldisc is currently in use. Since the ldisc referencing
|
||||
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
|
||||
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
|
||||
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
|
||||
about to enter and exit although this detail matters not).
|
||||
|
||||
Line Discipline Methods
|
||||
-----------------------
|
||||
|
||||
TTY side interfaces
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
======================= =======================================================
|
||||
open() Called when the line discipline is attached to
|
||||
the terminal. No other call into the line
|
||||
discipline for this tty will occur until it
|
||||
completes successfully. Should initialize any
|
||||
state needed by the ldisc, and set receive_room
|
||||
in the tty_struct to the maximum amount of data
|
||||
the line discipline is willing to accept from the
|
||||
driver with a single call to receive_buf().
|
||||
Returning an error will prevent the ldisc from
|
||||
being attached. Can sleep.
|
||||
|
||||
close() This is called on a terminal when the line
|
||||
discipline is being unplugged. At the point of
|
||||
execution no further users will enter the
|
||||
ldisc code for this tty. Can sleep.
|
||||
|
||||
hangup() Called when the tty line is hung up.
|
||||
The line discipline should cease I/O to the tty.
|
||||
No further calls into the ldisc code will occur.
|
||||
Can sleep.
|
||||
|
||||
read() (optional) A process requests reading data from
|
||||
the line. Multiple read calls may occur in parallel
|
||||
and the ldisc must deal with serialization issues.
|
||||
If not defined, the process will receive an EIO
|
||||
error. May sleep.
|
||||
|
||||
write() (optional) A process requests writing data to the
|
||||
line. Multiple write calls are serialized by the
|
||||
tty layer for the ldisc. If not defined, the
|
||||
process will receive an EIO error. May sleep.
|
||||
|
||||
flush_buffer() (optional) May be called at any point between
|
||||
open and close, and instructs the line discipline
|
||||
to empty its input buffer.
|
||||
|
||||
set_termios() (optional) Called on termios structure changes.
|
||||
The caller passes the old termios data and the
|
||||
current data is in the tty. Called under the
|
||||
termios semaphore so allowed to sleep. Serialized
|
||||
against itself only.
|
||||
|
||||
poll() (optional) Check the status for the poll/select
|
||||
calls. Multiple poll calls may occur in parallel.
|
||||
May sleep.
|
||||
|
||||
ioctl() (optional) Called when an ioctl is handed to the
|
||||
tty layer that might be for the ldisc. Multiple
|
||||
ioctl calls may occur in parallel. May sleep.
|
||||
|
||||
compat_ioctl() (optional) Called when a 32 bit ioctl is handed
|
||||
to the tty layer that might be for the ldisc.
|
||||
Multiple ioctl calls may occur in parallel.
|
||||
May sleep.
|
||||
======================= =======================================================
|
||||
|
||||
Driver Side Interfaces
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
======================= =======================================================
|
||||
receive_buf() (optional) Called by the low-level driver to hand
|
||||
a buffer of received bytes to the ldisc for
|
||||
processing. The number of bytes is guaranteed not
|
||||
to exceed the current value of tty->receive_room.
|
||||
All bytes must be processed.
|
||||
|
||||
receive_buf2() (optional) Called by the low-level driver to hand
|
||||
a buffer of received bytes to the ldisc for
|
||||
processing. Returns the number of bytes processed.
|
||||
|
||||
If both receive_buf() and receive_buf2() are
|
||||
defined, receive_buf2() should be preferred.
|
||||
|
||||
write_wakeup() May be called at any point between open and close.
|
||||
The TTY_DO_WRITE_WAKEUP flag indicates if a call
|
||||
is needed but always races versus calls. Thus the
|
||||
ldisc must be careful about setting order and to
|
||||
handle unexpected calls. Must not sleep.
|
||||
|
||||
The driver is forbidden from calling this directly
|
||||
from the ->write call from the ldisc as the ldisc
|
||||
is permitted to call the driver write method from
|
||||
this function. In such a situation defer it.
|
||||
|
||||
dcd_change() Report to the tty line the current DCD pin status
|
||||
changes and the relative timestamp. The timestamp
|
||||
cannot be NULL.
|
||||
======================= =======================================================
|
||||
|
||||
|
||||
Driver Access
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
Line discipline methods can call the following methods of the underlying
|
||||
hardware driver through the function pointers within the tty->driver
|
||||
structure:
|
||||
|
||||
======================= =======================================================
|
||||
write() Write a block of characters to the tty device.
|
||||
Returns the number of characters accepted. The
|
||||
character buffer passed to this method is already
|
||||
in kernel space.
|
||||
|
||||
put_char() Queues a character for writing to the tty device.
|
||||
If there is no room in the queue, the character is
|
||||
ignored.
|
||||
|
||||
flush_chars() (Optional) If defined, must be called after
|
||||
queueing characters with put_char() in order to
|
||||
start transmission.
|
||||
|
||||
write_room() Returns the numbers of characters the tty driver
|
||||
will accept for queueing to be written.
|
||||
|
||||
ioctl() Invoke device specific ioctl.
|
||||
Expects data pointers to refer to userspace.
|
||||
Returns ENOIOCTLCMD for unrecognized ioctl numbers.
|
||||
|
||||
set_termios() Notify the tty driver that the device's termios
|
||||
settings have changed. New settings are in
|
||||
tty->termios. Previous settings should be passed in
|
||||
the "old" argument.
|
||||
|
||||
The API is defined such that the driver should return
|
||||
the actual modes selected. This means that the
|
||||
driver function is responsible for modifying any
|
||||
bits in the request it cannot fulfill to indicate
|
||||
the actual modes being used. A device with no
|
||||
hardware capability for change (e.g. a USB dongle or
|
||||
virtual port) can provide NULL for this method.
|
||||
|
||||
throttle() Notify the tty driver that input buffers for the
|
||||
line discipline are close to full, and it should
|
||||
somehow signal that no more characters should be
|
||||
sent to the tty.
|
||||
|
||||
unthrottle() Notify the tty driver that characters can now be
|
||||
sent to the tty without fear of overrunning the
|
||||
input buffers of the line disciplines.
|
||||
|
||||
stop() Ask the tty driver to stop outputting characters
|
||||
to the tty device.
|
||||
|
||||
start() Ask the tty driver to resume sending characters
|
||||
to the tty device.
|
||||
|
||||
hangup() Ask the tty driver to hang up the tty device.
|
||||
|
||||
break_ctl() (Optional) Ask the tty driver to turn on or off
|
||||
BREAK status on the RS-232 port. If state is -1,
|
||||
then the BREAK status should be turned on; if
|
||||
state is 0, then BREAK should be turned off.
|
||||
If this routine is not implemented, use ioctls
|
||||
TIOCSBRK / TIOCCBRK instead.
|
||||
|
||||
wait_until_sent() Waits until the device has written out all of the
|
||||
characters in its transmitter FIFO.
|
||||
|
||||
send_xchar() Send a high-priority XON/XOFF character to the device.
|
||||
======================= =======================================================
|
||||
|
||||
|
||||
Flags
|
||||
^^^^^
|
||||
|
||||
Line discipline methods have access to tty->flags field containing the
|
||||
following interesting flags:
|
||||
|
||||
======================= =======================================================
|
||||
TTY_THROTTLED Driver input is throttled. The ldisc should call
|
||||
tty->driver->unthrottle() in order to resume
|
||||
reception when it is ready to process more data.
|
||||
|
||||
TTY_DO_WRITE_WAKEUP If set, causes the driver to call the ldisc's
|
||||
write_wakeup() method in order to resume
|
||||
transmission when it can accept more data
|
||||
to transmit.
|
||||
|
||||
TTY_IO_ERROR If set, causes all subsequent userspace read/write
|
||||
calls on the tty to fail, returning -EIO.
|
||||
|
||||
TTY_OTHER_CLOSED Device is a pty and the other side has closed.
|
||||
|
||||
TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into
|
||||
smaller chunks.
|
||||
======================= =======================================================
|
||||
|
||||
|
||||
Locking
|
||||
^^^^^^^
|
||||
|
||||
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
|
||||
but not yet enforced.
|
||||
|
||||
Three calls are now provided::
|
||||
|
||||
ldisc = tty_ldisc_ref(tty);
|
||||
|
||||
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
|
||||
point then NULL is returned. While this handle is held the ldisc will not
|
||||
change or go away::
|
||||
|
||||
tty_ldisc_deref(ldisc)
|
||||
|
||||
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
|
||||
a new reference::
|
||||
|
||||
ldisc = tty_ldisc_ref_wait(tty);
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
need to take a reference when they push bits up through the driver.
|
||||
|
||||
A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc
|
||||
functions are called with the ldisc unavailable. Thus tty_ldisc_ref will
|
||||
fail in this situation if used within these functions. Ldisc and driver
|
||||
code calling its own functions must be careful in this case.
|
||||
|
||||
|
||||
Driver Interface
|
||||
----------------
|
||||
|
||||
======================= =======================================================
|
||||
open() Called when a device is opened. May sleep
|
||||
|
||||
close() Called when a device is closed. At the point of
|
||||
return from this call the driver must make no
|
||||
further ldisc calls of any kind. May sleep
|
||||
|
||||
write() Called to write bytes to the device. May not
|
||||
sleep. May occur in parallel in special cases.
|
||||
Because this includes panic paths drivers generally
|
||||
shouldn't try and do clever locking here.
|
||||
|
||||
put_char() Stuff a single character onto the queue. The
|
||||
driver is guaranteed following up calls to
|
||||
flush_chars.
|
||||
|
||||
flush_chars() Ask the kernel to write put_char queue
|
||||
|
||||
write_room() Return the number of characters that can be stuffed
|
||||
into the port buffers without overflow (or less).
|
||||
The ldisc is responsible for being intelligent
|
||||
about multi-threading of write_room/write calls
|
||||
|
||||
ioctl() Called when an ioctl may be for the driver
|
||||
|
||||
set_termios() Called on termios change, serialized against
|
||||
itself by a semaphore. May sleep.
|
||||
|
||||
set_ldisc() Notifier for discipline change. At the point this
|
||||
is done the discipline is not yet usable. Can now
|
||||
sleep (I think)
|
||||
|
||||
throttle() Called by the ldisc to ask the driver to do flow
|
||||
control. Serialization including with unthrottle
|
||||
is the job of the ldisc layer.
|
||||
|
||||
unthrottle() Called by the ldisc to ask the driver to stop flow
|
||||
control.
|
||||
|
||||
stop() Ldisc notifier to the driver to stop output. As with
|
||||
throttle the serializations with start() are down
|
||||
to the ldisc layer.
|
||||
|
||||
start() Ldisc notifier to the driver to start output.
|
||||
|
||||
hangup() Ask the tty driver to cause a hangup initiated
|
||||
from the host side. [Can sleep ??]
|
||||
|
||||
break_ctl() Send RS232 break. Can sleep. Can get called in
|
||||
parallel, driver must serialize (for now), and
|
||||
with write calls.
|
||||
|
||||
wait_until_sent() Wait for characters to exit the hardware queue
|
||||
of the driver. Can sleep
|
||||
|
||||
send_xchar() Send XON/XOFF and if possible jump the queue with
|
||||
it in order to get fast flow control responses.
|
||||
Cannot sleep ??
|
||||
======================= =======================================================
|
||||
Reference in New Issue
Block a user