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