diff options
author | Tilman Schmidt <tilman@imap.cc> | 2006-12-30 00:48:03 (GMT) |
---|---|---|
committer | Linus Torvalds <torvalds@woody.osdl.org> | 2006-12-30 18:55:55 (GMT) |
commit | 1f59c140f8387d32b8fe137eb02da40630b618e8 (patch) | |
tree | fffd41baf6b98914dc49ef049a2d6afa30de69f1 /Documentation | |
parent | cfe7c09ac2be2a89aa46bb23d480d9d908e8c041 (diff) | |
download | linux-1f59c140f8387d32b8fe137eb02da40630b618e8.tar.xz |
[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>
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/tty.txt | 111 |
1 files changed, 101 insertions, 10 deletions
diff --git a/Documentation/tty.txt b/Documentation/tty.txt index dab5660..5f799e6 100644 --- a/Documentation/tty.txt +++ b/Documentation/tty.txt @@ -39,28 +39,37 @@ 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. 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. -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. +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 |