tty: Clarify documentation of ->write()
[linux-2.6.git] / Documentation / tty.txt
1
2                         The Lockronomicon
3
4 Your guide to the ancient and twisted locking policies of the tty layer and
5 the warped logic behind them. Beware all ye who read on.
6
7 FIXME: still need to work out the full set of BKL assumptions and document
8 them so they can eventually be killed off.
9
10
11 Line Discipline
12 ---------------
13
14 Line disciplines are registered with tty_register_ldisc() passing the
15 discipline number and the ldisc structure. At the point of registration the 
16 discipline must be ready to use and it is possible it will get used before
17 the call returns success. If the call returns an error then it won't get
18 called. Do not re-use ldisc numbers as they are part of the userspace ABI
19 and writing over an existing ldisc will cause demons to eat your computer.
20 After the return the ldisc data has been copied so you may free your own 
21 copy of the structure. You must not re-register over the top of the line
22 discipline even with the same data or your computer again will be eaten by
23 demons.
24
25 In order to remove a line discipline call tty_unregister_ldisc().
26 In ancient times this always worked. In modern times the function will
27 return -EBUSY if the ldisc is currently in use. Since the ldisc referencing
28 code manages the module counts this should not usually be a concern.
29
30 Heed this warning: the reference count field of the registered copies of the
31 tty_ldisc structure in the ldisc table counts the number of lines using this
32 discipline. The reference count of the tty_ldisc structure within a tty 
33 counts the number of active users of the ldisc at this instant. In effect it
34 counts the number of threads of execution within an ldisc method (plus those
35 about to enter and exit although this detail matters not).
36
37 Line Discipline Methods
38 -----------------------
39
40 TTY side interfaces:
41
42 open()          -       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
47 close()         -       This is called on a terminal when the line
48                         discipline is being unplugged. At the point of
49                         execution no further users will enter the
50                         ldisc code for this tty. Can sleep.
51
52 hangup()        -       Called when the tty line is hung up.
53                         The line discipline should cease I/O to the tty.
54                         No further calls into the ldisc code will occur.
55                         Can sleep.
56
57 write()         -       A process is writing data through the line
58                         discipline.  Multiple write calls are serialized
59                         by the tty layer for the ldisc.  May sleep. 
60
61 flush_buffer()  -       (optional) May be called at any point between
62                         open and close, and instructs the line discipline
63                         to empty its input buffer.
64
65 chars_in_buffer() -     (optional) Report the number of bytes in the input
66                         buffer.
67
68 set_termios()   -       (optional) Called on termios structure changes.
69                         The caller passes the old termios data and the
70                         current data is in the tty. Called under the
71                         termios semaphore so allowed to sleep. Serialized
72                         against itself only.
73
74 read()          -       Move data from the line discipline to the user.
75                         Multiple read calls may occur in parallel and the
76                         ldisc must deal with serialization issues. May 
77                         sleep.
78
79 poll()          -       Check the status for the poll/select calls. Multiple
80                         poll calls may occur in parallel. May sleep.
81
82 ioctl()         -       Called when an ioctl is handed to the tty layer
83                         that might be for the ldisc. Multiple ioctl calls
84                         may occur in parallel. May sleep. 
85
86 Driver Side Interfaces:
87
88 receive_buf()   -       Hand buffers of bytes from the driver to the ldisc
89                         for processing. Semantics currently rather
90                         mysterious 8(
91
92 write_wakeup()  -       May be called at any point between open and close.
93                         The TTY_DO_WRITE_WAKEUP flag indicates if a call
94                         is needed but always races versus calls. Thus the
95                         ldisc must be careful about setting order and to
96                         handle unexpected calls. Must not sleep.
97
98                         The driver is forbidden from calling this directly
99                         from the ->write call from the ldisc as the ldisc
100                         is permitted to call the driver write method from
101                         this function. In such a situation defer it.
102
103
104 Driver Access
105
106 Line discipline methods can call the following methods of the underlying
107 hardware driver through the function pointers within the tty->driver
108 structure:
109
110 write()                 Write a block of characters to the tty device.
111                         Returns the number of characters accepted. The
112                         character buffer passed to this method is already
113                         in kernel space.
114
115 put_char()              Queues a character for writing to the tty device.
116                         If there is no room in the queue, the character is
117                         ignored.
118
119 flush_chars()           (Optional) If defined, must be called after
120                         queueing characters with put_char() in order to
121                         start transmission.
122
123 write_room()            Returns the numbers of characters the tty driver
124                         will accept for queueing to be written.
125
126 ioctl()                 Invoke device specific ioctl.
127                         Expects data pointers to refer to userspace.
128                         Returns ENOIOCTLCMD for unrecognized ioctl numbers.
129
130 set_termios()           Notify the tty driver that the device's termios
131                         settings have changed. New settings are in
132                         tty->termios. Previous settings should be passed in
133                         the "old" argument.
134
135 throttle()              Notify the tty driver that input buffers for the
136                         line discipline are close to full, and it should
137                         somehow signal that no more characters should be
138                         sent to the tty.
139
140 unthrottle()            Notify the tty driver that characters can now be
141                         sent to the tty without fear of overrunning the
142                         input buffers of the line disciplines.
143
144 stop()                  Ask the tty driver to stop outputting characters
145                         to the tty device.
146
147 start()                 Ask the tty driver to resume sending characters
148                         to the tty device.
149
150 hangup()                Ask the tty driver to hang up the tty device.
151
152 break_ctl()             (Optional) Ask the tty driver to turn on or off
153                         BREAK status on the RS-232 port.  If state is -1,
154                         then the BREAK status should be turned on; if
155                         state is 0, then BREAK should be turned off.
156                         If this routine is not implemented, use ioctls
157                         TIOCSBRK / TIOCCBRK instead.
158
159 wait_until_sent()       Waits until the device has written out all of the
160                         characters in its transmitter FIFO.
161
162 send_xchar()            Send a high-priority XON/XOFF character to the device.
163
164
165 Flags
166
167 Line discipline methods have access to tty->flags field containing the
168 following interesting flags:
169
170 TTY_THROTTLED           Driver input is throttled. The ldisc should call
171                         tty->driver->unthrottle() in order to resume
172                         reception when it is ready to process more data.
173
174 TTY_DO_WRITE_WAKEUP     If set, causes the driver to call the ldisc's
175                         write_wakeup() method in order to resume
176                         transmission when it can accept more data
177                         to transmit.
178
179 TTY_IO_ERROR            If set, causes all subsequent userspace read/write
180                         calls on the tty to fail, returning -EIO.
181
182 TTY_OTHER_CLOSED        Device is a pty and the other side has closed.
183
184 TTY_NO_WRITE_SPLIT      Prevent driver from splitting up writes into
185                         smaller chunks.
186
187
188 Locking
189
190 Callers to the line discipline functions from the tty layer are required to
191 take line discipline locks. The same is true of calls from the driver side
192 but not yet enforced.
193
194 Three calls are now provided
195
196         ldisc = tty_ldisc_ref(tty);
197
198 takes a handle to the line discipline in the tty and returns it. If no ldisc
199 is currently attached or the ldisc is being closed and re-opened at this
200 point then NULL is returned. While this handle is held the ldisc will not
201 change or go away.
202
203         tty_ldisc_deref(ldisc)
204
205 Returns the ldisc reference and allows the ldisc to be closed. Returning the
206 reference takes away your right to call the ldisc functions until you take
207 a new reference.
208
209         ldisc = tty_ldisc_ref_wait(tty);
210
211 Performs the same function as tty_ldisc_ref except that it will wait for an
212 ldisc change to complete and then return a reference to the new ldisc. 
213
214 While these functions are slightly slower than the old code they should have
215 minimal impact as most receive logic uses the flip buffers and they only
216 need to take a reference when they push bits up through the driver.
217
218 A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc 
219 functions are called with the ldisc unavailable. Thus tty_ldisc_ref will
220 fail in this situation if used within these functions. Ldisc and driver
221 code calling its own functions must be careful in this case. 
222
223
224 Driver Interface
225 ----------------
226
227 open()          -       Called when a device is opened. May sleep
228
229 close()         -       Called when a device is closed. At the point of
230                         return from this call the driver must make no 
231                         further ldisc calls of any kind. May sleep
232
233 write()         -       Called to write bytes to the device. May not
234                         sleep. May occur in parallel in special cases. 
235                         Because this includes panic paths drivers generally
236                         shouldn't try and do clever locking here.
237
238 put_char()      -       Stuff a single character onto the queue. The
239                         driver is guaranteed following up calls to
240                         flush_chars.
241
242 flush_chars()   -       Ask the kernel to write put_char queue
243
244 write_room()    -       Return the number of characters tht can be stuffed
245                         into the port buffers without overflow (or less).
246                         The ldisc is responsible for being intelligent
247                         about multi-threading of write_room/write calls
248
249 ioctl()         -       Called when an ioctl may be for the driver
250
251 set_termios()   -       Called on termios change, serialized against
252                         itself by a semaphore. May sleep.
253
254 set_ldisc()     -       Notifier for discipline change. At the point this 
255                         is done the discipline is not yet usable. Can now
256                         sleep (I think)
257
258 throttle()      -       Called by the ldisc to ask the driver to do flow
259                         control.  Serialization including with unthrottle
260                         is the job of the ldisc layer.
261
262 unthrottle()    -       Called by the ldisc to ask the driver to stop flow
263                         control.
264
265 stop()          -       Ldisc notifier to the driver to stop output. As with
266                         throttle the serializations with start() are down
267                         to the ldisc layer.
268
269 start()         -       Ldisc notifier to the driver to start output.
270
271 hangup()        -       Ask the tty driver to cause a hangup initiated
272                         from the host side. [Can sleep ??]
273
274 break_ctl()     -       Send RS232 break. Can sleep. Can get called in
275                         parallel, driver must serialize (for now), and
276                         with write calls.
277
278 wait_until_sent() -     Wait for characters to exit the hardware queue
279                         of the driver. Can sleep
280
281 send_xchar()      -     Send XON/XOFF and if possible jump the queue with
282                         it in order to get fast flow control responses.
283                         Cannot sleep ??
284