Commit 1f59c140 authored by Tilman Schmidt's avatar Tilman Schmidt Committed by Linus Torvalds
Browse files

[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: default avatarTilman Schmidt <tilman@imap.cc>
Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>
Cc: Theodore Ts'o <tytso@mit.edu>
Signed-off-by: default avatarAndrew Morton <akpm@osdl.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@osdl.org>
parent cfe7c09a

Documentation/tty.txt

+101 −10
Original line number Diff line number Diff line
@@ -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

CRA Git | Maintained and supported by SUSTech CRA and CCSE