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