Contents of /alx-src/tags/kernel26-2.6.12-alx-r9/Documentation/tty.txt
Parent Directory | Revision Log
Revision 630 -
(show annotations)
(download)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 7449 byte(s)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 7449 byte(s)
Tag kernel26-2.6.12-alx-r9
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_register_ldisc passing NULL. |
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 | close() - This is called on a terminal when the line |
43 | discipline is being unplugged. At the point of |
44 | execution no further users will enter the |
45 | ldisc code for this tty. Can sleep. |
46 | |
47 | open() - Called when the line discipline is attached to |
48 | the terminal. No other call into the line |
49 | discipline for this tty will occur until it |
50 | completes successfully. Can sleep. |
51 | |
52 | write() - A process is writing data through the line |
53 | discipline. Multiple write calls are serialized |
54 | by the tty layer for the ldisc. May sleep. |
55 | |
56 | flush_buffer() - May be called at any point between open and close. |
57 | |
58 | chars_in_buffer() - Report the number of bytes in the buffer. |
59 | |
60 | set_termios() - Called on termios structure changes. The caller |
61 | passes the old termios data and the current data |
62 | is in the tty. Called under the termios semaphore so |
63 | allowed to sleep. Serialized against itself only. |
64 | |
65 | read() - Move data from the line discipline to the user. |
66 | Multiple read calls may occur in parallel and the |
67 | ldisc must deal with serialization issues. May |
68 | sleep. |
69 | |
70 | poll() - Check the status for the poll/select calls. Multiple |
71 | poll calls may occur in parallel. May sleep. |
72 | |
73 | ioctl() - Called when an ioctl is handed to the tty layer |
74 | that might be for the ldisc. Multiple ioctl calls |
75 | may occur in parallel. May sleep. |
76 | |
77 | Driver Side Interfaces: |
78 | |
79 | receive_buf() - Hand buffers of bytes from the driver to the ldisc |
80 | for processing. Semantics currently rather |
81 | mysterious 8( |
82 | |
83 | receive_room() - Can be called by the driver layer at any time when |
84 | the ldisc is opened. The ldisc must be able to |
85 | handle the reported amount of data at that instant. |
86 | Synchronization between active receive_buf and |
87 | receive_room calls is down to the driver not the |
88 | ldisc. Must not sleep. |
89 | |
90 | write_wakeup() - May be called at any point between open and close. |
91 | The TTY_DO_WRITE_WAKEUP flag indicates if a call |
92 | is needed but always races versus calls. Thus the |
93 | ldisc must be careful about setting order and to |
94 | handle unexpected calls. Must not sleep. |
95 | |
96 | The driver is forbidden from calling this directly |
97 | from the ->write call from the ldisc as the ldisc |
98 | is permitted to call the driver write method from |
99 | this function. In such a situation defer it. |
100 | |
101 | |
102 | Locking |
103 | |
104 | Callers to the line discipline functions from the tty layer are required to |
105 | take line discipline locks. The same is true of calls from the driver side |
106 | but not yet enforced. |
107 | |
108 | Three calls are now provided |
109 | |
110 | ldisc = tty_ldisc_ref(tty); |
111 | |
112 | takes a handle to the line discipline in the tty and returns it. If no ldisc |
113 | is currently attached or the ldisc is being closed and re-opened at this |
114 | point then NULL is returned. While this handle is held the ldisc will not |
115 | change or go away. |
116 | |
117 | tty_ldisc_deref(ldisc) |
118 | |
119 | Returns the ldisc reference and allows the ldisc to be closed. Returning the |
120 | reference takes away your right to call the ldisc functions until you take |
121 | a new reference. |
122 | |
123 | ldisc = tty_ldisc_ref_wait(tty); |
124 | |
125 | Performs the same function as tty_ldisc_ref except that it will wait for an |
126 | ldisc change to complete and then return a reference to the new ldisc. |
127 | |
128 | While these functions are slightly slower than the old code they should have |
129 | minimal impact as most receive logic uses the flip buffers and they only |
130 | need to take a reference when they push bits up through the driver. |
131 | |
132 | A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc |
133 | functions are called with the ldisc unavailable. Thus tty_ldisc_ref will |
134 | fail in this situation if used within these functions. Ldisc and driver |
135 | code calling its own functions must be careful in this case. |
136 | |
137 | |
138 | Driver Interface |
139 | ---------------- |
140 | |
141 | open() - Called when a device is opened. May sleep |
142 | |
143 | close() - Called when a device is closed. At the point of |
144 | return from this call the driver must make no |
145 | further ldisc calls of any kind. May sleep |
146 | |
147 | write() - Called to write bytes to the device. May not |
148 | sleep. May occur in parallel in special cases. |
149 | Because this includes panic paths drivers generally |
150 | shouldn't try and do clever locking here. |
151 | |
152 | put_char() - Stuff a single character onto the queue. The |
153 | driver is guaranteed following up calls to |
154 | flush_chars. |
155 | |
156 | flush_chars() - Ask the kernel to write put_char queue |
157 | |
158 | write_room() - Return the number of characters tht can be stuffed |
159 | into the port buffers without overflow (or less). |
160 | The ldisc is responsible for being intelligent |
161 | about multi-threading of write_room/write calls |
162 | |
163 | ioctl() - Called when an ioctl may be for the driver |
164 | |
165 | set_termios() - Called on termios change, serialized against |
166 | itself by a semaphore. May sleep. |
167 | |
168 | set_ldisc() - Notifier for discipline change. At the point this |
169 | is done the discipline is not yet usable. Can now |
170 | sleep (I think) |
171 | |
172 | throttle() - Called by the ldisc to ask the driver to do flow |
173 | control. Serialization including with unthrottle |
174 | is the job of the ldisc layer. |
175 | |
176 | unthrottle() - Called by the ldisc to ask the driver to stop flow |
177 | control. |
178 | |
179 | stop() - Ldisc notifier to the driver to stop output. As with |
180 | throttle the serializations with start() are down |
181 | to the ldisc layer. |
182 | |
183 | start() - Ldisc notifier to the driver to start output. |
184 | |
185 | hangup() - Ask the tty driver to cause a hangup initiated |
186 | from the host side. [Can sleep ??] |
187 | |
188 | break_ctl() - Send RS232 break. Can sleep. Can get called in |
189 | parallel, driver must serialize (for now), and |
190 | with write calls. |
191 | |
192 | wait_until_sent() - Wait for characters to exit the hardware queue |
193 | of the driver. Can sleep |
194 | |
195 | send_xchar() - Send XON/XOFF and if possible jump the queue with |
196 | it in order to get fast flow control responses. |
197 | Cannot sleep ?? |
198 |