aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Documentation/tty.txt111
1 files changed, 101 insertions, 10 deletions
diff --git a/Documentation/tty.txt b/Documentation/tty.txt
index dab56604745d..5f799e612e03 100644
--- a/Documentation/tty.txt
+++ b/Documentation/tty.txt
@@ -39,28 +39,37 @@ Line Discipline Methods
39 39
40TTY side interfaces: 40TTY side interfaces:
41 41
42open() - Called when the line discipline is attached to
43 the terminal. No other call into the line
44 discipline for this tty will occur until it
45 completes successfully. Can sleep.
46
42close() - This is called on a terminal when the line 47close() - This is called on a terminal when the line
43 discipline is being unplugged. At the point of 48 discipline is being unplugged. At the point of
44 execution no further users will enter the 49 execution no further users will enter the
45 ldisc code for this tty. Can sleep. 50 ldisc code for this tty. Can sleep.
46 51
47open() - Called when the line discipline is attached to 52hangup() - Called when the tty line is hung up.
48 the terminal. No other call into the line 53 The line discipline should cease I/O to the tty.
49 discipline for this tty will occur until it 54 No further calls into the ldisc code will occur.
50 completes successfully. Can sleep. 55 Can sleep.
51 56
52write() - A process is writing data through the line 57write() - A process is writing data through the line
53 discipline. Multiple write calls are serialized 58 discipline. Multiple write calls are serialized
54 by the tty layer for the ldisc. May sleep. 59 by the tty layer for the ldisc. May sleep.
55 60
56flush_buffer() - May be called at any point between open and close. 61flush_buffer() - (optional) May be called at any point between
62 open and close, and instructs the line discipline
63 to empty its input buffer.
57 64
58chars_in_buffer() - Report the number of bytes in the buffer. 65chars_in_buffer() - (optional) Report the number of bytes in the input
66 buffer.
59 67
60set_termios() - Called on termios structure changes. The caller 68set_termios() - (optional) Called on termios structure changes.
61 passes the old termios data and the current data 69 The caller passes the old termios data and the
62 is in the tty. Called under the termios semaphore so 70 current data is in the tty. Called under the
63 allowed to sleep. Serialized against itself only. 71 termios semaphore so allowed to sleep. Serialized
72 against itself only.
64 73
65read() - Move data from the line discipline to the user. 74read() - Move data from the line discipline to the user.
66 Multiple read calls may occur in parallel and the 75 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.
92 this function. In such a situation defer it. 101 this function. In such a situation defer it.
93 102
94 103
104Driver Access
105
106Line discipline methods can call the following methods of the underlying
107hardware driver through the function pointers within the tty->driver
108structure:
109
110write() Write a block of characters to the tty device.
111 Returns the number of characters accepted.
112
113put_char() Queues a character for writing to the tty device.
114 If there is no room in the queue, the character is
115 ignored.
116
117flush_chars() (Optional) If defined, must be called after
118 queueing characters with put_char() in order to
119 start transmission.
120
121write_room() Returns the numbers of characters the tty driver
122 will accept for queueing to be written.
123
124ioctl() Invoke device specific ioctl.
125 Expects data pointers to refer to userspace.
126 Returns ENOIOCTLCMD for unrecognized ioctl numbers.
127
128set_termios() Notify the tty driver that the device's termios
129 settings have changed. New settings are in
130 tty->termios. Previous settings should be passed in
131 the "old" argument.
132
133throttle() Notify the tty driver that input buffers for the
134 line discipline are close to full, and it should
135 somehow signal that no more characters should be
136 sent to the tty.
137
138unthrottle() Notify the tty driver that characters can now be
139 sent to the tty without fear of overrunning the
140 input buffers of the line disciplines.
141
142stop() Ask the tty driver to stop outputting characters
143 to the tty device.
144
145start() Ask the tty driver to resume sending characters
146 to the tty device.
147
148hangup() Ask the tty driver to hang up the tty device.
149
150break_ctl() (Optional) Ask the tty driver to turn on or off
151 BREAK status on the RS-232 port. If state is -1,
152 then the BREAK status should be turned on; if
153 state is 0, then BREAK should be turned off.
154 If this routine is not implemented, use ioctls
155 TIOCSBRK / TIOCCBRK instead.
156
157wait_until_sent() Waits until the device has written out all of the
158 characters in its transmitter FIFO.
159
160send_xchar() Send a high-priority XON/XOFF character to the device.
161
162
163Flags
164
165Line discipline methods have access to tty->flags field containing the
166following interesting flags:
167
168TTY_THROTTLED Driver input is throttled. The ldisc should call
169 tty->driver->unthrottle() in order to resume
170 reception when it is ready to process more data.
171
172TTY_DO_WRITE_WAKEUP If set, causes the driver to call the ldisc's
173 write_wakeup() method in order to resume
174 transmission when it can accept more data
175 to transmit.
176
177TTY_IO_ERROR If set, causes all subsequent userspace read/write
178 calls on the tty to fail, returning -EIO.
179
180TTY_OTHER_CLOSED Device is a pty and the other side has closed.
181
182TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into
183 smaller chunks.
184
185
95Locking 186Locking
96 187
97Callers to the line discipline functions from the tty layer are required to 188Callers to the line discipline functions from the tty layer are required to