← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-lowlatency/precise

« back to all changes in this revision

Viewing changes to Documentation/serial/tty.txt

  • Committer: Package Import Robot
  • Author(s): Alessio Igor Bogani
  • Date: 2011-10-26 11:13:05 UTC
  • Revision ID: package-import@ubuntu.com-20111026111305-tz023xykf0i6eosh
Tags: upstream-3.2.0
Import upstream version 3.2.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/serial/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. Returning an error will
 
46
                        prevent the ldisc from being attached. Can sleep.
 
47
 
 
48
close()         -       This is called on a terminal when the line
 
49
                        discipline is being unplugged. At the point of
 
50
                        execution no further users will enter the
 
51
                        ldisc code for this tty. Can sleep.
 
52
 
 
53
hangup()        -       Called when the tty line is hung up.
 
54
                        The line discipline should cease I/O to the tty.
 
55
                        No further calls into the ldisc code will occur.
 
56
                        The return value is ignored. Can sleep.
 
57
 
 
58
write()         -       A process is writing data through the line
 
59
                        discipline.  Multiple write calls are serialized
 
60
                        by the tty layer for the ldisc.  May sleep. 
 
61
 
 
62
flush_buffer()  -       (optional) May be called at any point between
 
63
                        open and close, and instructs the line discipline
 
64
                        to empty its input buffer.
 
65
 
 
66
chars_in_buffer() -     (optional) Report the number of bytes in the input
 
67
                        buffer.
 
68
 
 
69
set_termios()   -       (optional) Called on termios structure changes.
 
70
                        The caller passes the old termios data and the
 
71
                        current data is in the tty. Called under the
 
72
                        termios semaphore so allowed to sleep. Serialized
 
73
                        against itself only.
 
74
 
 
75
read()          -       Move data from the line discipline to the user.
 
76
                        Multiple read calls may occur in parallel and the
 
77
                        ldisc must deal with serialization issues. May 
 
78
                        sleep.
 
79
 
 
80
poll()          -       Check the status for the poll/select calls. Multiple
 
81
                        poll calls may occur in parallel. May sleep.
 
82
 
 
83
ioctl()         -       Called when an ioctl is handed to the tty layer
 
84
                        that might be for the ldisc. Multiple ioctl calls
 
85
                        may occur in parallel. May sleep. 
 
86
 
 
87
compat_ioctl()  -       Called when a 32 bit ioctl is handed to the tty layer
 
88
                        that might be for the ldisc. Multiple ioctl calls
 
89
                        may occur in parallel. May sleep.
 
90
 
 
91
Driver Side Interfaces:
 
92
 
 
93
receive_buf()   -       Hand buffers of bytes from the driver to the ldisc
 
94
                        for processing. Semantics currently rather
 
95
                        mysterious 8(
 
96
 
 
97
write_wakeup()  -       May be called at any point between open and close.
 
98
                        The TTY_DO_WRITE_WAKEUP flag indicates if a call
 
99
                        is needed but always races versus calls. Thus the
 
100
                        ldisc must be careful about setting order and to
 
101
                        handle unexpected calls. Must not sleep.
 
102
 
 
103
                        The driver is forbidden from calling this directly
 
104
                        from the ->write call from the ldisc as the ldisc
 
105
                        is permitted to call the driver write method from
 
106
                        this function. In such a situation defer it.
 
107
 
 
108
dcd_change()    -       Report to the tty line the current DCD pin status
 
109
                        changes and the relative timestamp. The timestamp
 
110
                        cannot be NULL.
 
111
 
 
112
 
 
113
Driver Access
 
114
 
 
115
Line discipline methods can call the following methods of the underlying
 
116
hardware driver through the function pointers within the tty->driver
 
117
structure:
 
118
 
 
119
write()                 Write a block of characters to the tty device.
 
120
                        Returns the number of characters accepted. The
 
121
                        character buffer passed to this method is already
 
122
                        in kernel space.
 
123
 
 
124
put_char()              Queues a character for writing to the tty device.
 
125
                        If there is no room in the queue, the character is
 
126
                        ignored.
 
127
 
 
128
flush_chars()           (Optional) If defined, must be called after
 
129
                        queueing characters with put_char() in order to
 
130
                        start transmission.
 
131
 
 
132
write_room()            Returns the numbers of characters the tty driver
 
133
                        will accept for queueing to be written.
 
134
 
 
135
ioctl()                 Invoke device specific ioctl.
 
136
                        Expects data pointers to refer to userspace.
 
137
                        Returns ENOIOCTLCMD for unrecognized ioctl numbers.
 
138
 
 
139
set_termios()           Notify the tty driver that the device's termios
 
140
                        settings have changed. New settings are in
 
141
                        tty->termios. Previous settings should be passed in
 
142
                        the "old" argument.
 
143
 
 
144
                        The API is defined such that the driver should return
 
145
                        the actual modes selected. This means that the
 
146
                        driver function is responsible for modifying any
 
147
                        bits in the request it cannot fulfill to indicate
 
148
                        the actual modes being used. A device with no
 
149
                        hardware capability for change (eg a USB dongle or
 
150
                        virtual port) can provide NULL for this method.
 
151
 
 
152
throttle()              Notify the tty driver that input buffers for the
 
153
                        line discipline are close to full, and it should
 
154
                        somehow signal that no more characters should be
 
155
                        sent to the tty.
 
156
 
 
157
unthrottle()            Notify the tty driver that characters can now be
 
158
                        sent to the tty without fear of overrunning the
 
159
                        input buffers of the line disciplines.
 
160
 
 
161
stop()                  Ask the tty driver to stop outputting characters
 
162
                        to the tty device.
 
163
 
 
164
start()                 Ask the tty driver to resume sending characters
 
165
                        to the tty device.
 
166
 
 
167
hangup()                Ask the tty driver to hang up the tty device.
 
168
 
 
169
break_ctl()             (Optional) Ask the tty driver to turn on or off
 
170
                        BREAK status on the RS-232 port.  If state is -1,
 
171
                        then the BREAK status should be turned on; if
 
172
                        state is 0, then BREAK should be turned off.
 
173
                        If this routine is not implemented, use ioctls
 
174
                        TIOCSBRK / TIOCCBRK instead.
 
175
 
 
176
wait_until_sent()       Waits until the device has written out all of the
 
177
                        characters in its transmitter FIFO.
 
178
 
 
179
send_xchar()            Send a high-priority XON/XOFF character to the device.
 
180
 
 
181
 
 
182
Flags
 
183
 
 
184
Line discipline methods have access to tty->flags field containing the
 
185
following interesting flags:
 
186
 
 
187
TTY_THROTTLED           Driver input is throttled. The ldisc should call
 
188
                        tty->driver->unthrottle() in order to resume
 
189
                        reception when it is ready to process more data.
 
190
 
 
191
TTY_DO_WRITE_WAKEUP     If set, causes the driver to call the ldisc's
 
192
                        write_wakeup() method in order to resume
 
193
                        transmission when it can accept more data
 
194
                        to transmit.
 
195
 
 
196
TTY_IO_ERROR            If set, causes all subsequent userspace read/write
 
197
                        calls on the tty to fail, returning -EIO.
 
198
 
 
199
TTY_OTHER_CLOSED        Device is a pty and the other side has closed.
 
200
 
 
201
TTY_NO_WRITE_SPLIT      Prevent driver from splitting up writes into
 
202
                        smaller chunks.
 
203
 
 
204
 
 
205
Locking
 
206
 
 
207
Callers to the line discipline functions from the tty layer are required to
 
208
take line discipline locks. The same is true of calls from the driver side
 
209
but not yet enforced.
 
210
 
 
211
Three calls are now provided
 
212
 
 
213
        ldisc = tty_ldisc_ref(tty);
 
214
 
 
215
takes a handle to the line discipline in the tty and returns it. If no ldisc
 
216
is currently attached or the ldisc is being closed and re-opened at this
 
217
point then NULL is returned. While this handle is held the ldisc will not
 
218
change or go away.
 
219
 
 
220
        tty_ldisc_deref(ldisc)
 
221
 
 
222
Returns the ldisc reference and allows the ldisc to be closed. Returning the
 
223
reference takes away your right to call the ldisc functions until you take
 
224
a new reference.
 
225
 
 
226
        ldisc = tty_ldisc_ref_wait(tty);
 
227
 
 
228
Performs the same function as tty_ldisc_ref except that it will wait for an
 
229
ldisc change to complete and then return a reference to the new ldisc. 
 
230
 
 
231
While these functions are slightly slower than the old code they should have
 
232
minimal impact as most receive logic uses the flip buffers and they only
 
233
need to take a reference when they push bits up through the driver.
 
234
 
 
235
A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc 
 
236
functions are called with the ldisc unavailable. Thus tty_ldisc_ref will
 
237
fail in this situation if used within these functions. Ldisc and driver
 
238
code calling its own functions must be careful in this case. 
 
239
 
 
240
 
 
241
Driver Interface
 
242
----------------
 
243
 
 
244
open()          -       Called when a device is opened. May sleep
 
245
 
 
246
close()         -       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
 
 
250
write()         -       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
 
 
255
put_char()      -       Stuff a single character onto the queue. The
 
256
                        driver is guaranteed following up calls to
 
257
                        flush_chars.
 
258
 
 
259
flush_chars()   -       Ask the kernel to write put_char queue
 
260
 
 
261
write_room()    -       Return the number of characters tht can be stuffed
 
262
                        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
 
 
266
ioctl()         -       Called when an ioctl may be for the driver
 
267
 
 
268
set_termios()   -       Called on termios change, serialized against
 
269
                        itself by a semaphore. May sleep.
 
270
 
 
271
set_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
 
 
275
throttle()      -       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
 
 
279
unthrottle()    -       Called by the ldisc to ask the driver to stop flow
 
280
                        control.
 
281
 
 
282
stop()          -       Ldisc notifier to the driver to stop output. As with
 
283
                        throttle the serializations with start() are down
 
284
                        to the ldisc layer.
 
285
 
 
286
start()         -       Ldisc notifier to the driver to start output.
 
287
 
 
288
hangup()        -       Ask the tty driver to cause a hangup initiated
 
289
                        from the host side. [Can sleep ??]
 
290
 
 
291
break_ctl()     -       Send RS232 break. Can sleep. Can get called in
 
292
                        parallel, driver must serialize (for now), and
 
293
                        with write calls.
 
294
 
 
295
wait_until_sent() -     Wait for characters to exit the hardware queue
 
296
                        of the driver. Can sleep
 
297
 
 
298
send_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