dect
/
linux-2.6
Archived
13
0
Fork 0
Code Releases Activity

[PATCH] Update to Documentation/tty.txt on line disciplines 

While trying to develop a line discipline I found a couple of things worth
mentioning in Documentation/tty.txt which weren't, so I decided to add
them.  It would be nice if someone more knowledgeable than me in that area
would look over them, in case I got something wrong.

Signed-off-by: Tilman Schmidt <tilman@imap.cc>
Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>
Cc: Theodore Ts'o <tytso@mit.edu>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
This commit is contained in:
Tilman Schmidt 2006-12-29 16:48:03 -08:00 committed by Linus Torvalds
parent cfe7c09ac2
commit 1f59c140f8
1 changed files with 102 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
Documentation/tty.txt
View File

@ -39,28 +39,37 @@ Line Discipline Methods
TTY side interfaces:
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.
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. 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.
write() - A process is writing data through the line
discipline. Multiple write calls are serialized
by the tty layer for the ldisc. May sleep.
flush_buffer() - May be called at any point between open and close.
flush_buffer() - (optional) May be called at any point between
open and close, and instructs the line discipline
to empty its input buffer.
chars_in_buffer() - Report the number of bytes in the buffer.
chars_in_buffer() - (optional) Report the number of bytes in the input
buffer.
set_termios() - 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.
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.
read() - Move data from the line discipline to the user.
Multiple read calls may occur in parallel and the
@ -92,6 +101,88 @@ write_wakeup() - May be called at any point between open and close.
this function. In such a situation defer it.
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.
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.
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