annotate Documentation/tty.txt @ 524:7f8b544237bf

netfront: Allow netfront in domain 0.

This is useful if your physical network device is in a utility domain.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Tue Apr 15 15:18:58 2008 +0100 (2008-04-15)
parents 831230e53067
rev   line source
ian@0 1
ian@0 2 The Lockronomicon
ian@0 3
ian@0 4 Your guide to the ancient and twisted locking policies of the tty layer and
ian@0 5 the warped logic behind them. Beware all ye who read on.
ian@0 6
ian@0 7 FIXME: still need to work out the full set of BKL assumptions and document
ian@0 8 them so they can eventually be killed off.
ian@0 9
ian@0 10
ian@0 11 Line Discipline
ian@0 12 ---------------
ian@0 13
ian@0 14 Line disciplines are registered with tty_register_ldisc() passing the
ian@0 15 discipline number and the ldisc structure. At the point of registration the
ian@0 16 discipline must be ready to use and it is possible it will get used before
ian@0 17 the call returns success. If the call returns an error then it won't get
ian@0 18 called. Do not re-use ldisc numbers as they are part of the userspace ABI
ian@0 19 and writing over an existing ldisc will cause demons to eat your computer.
ian@0 20 After the return the ldisc data has been copied so you may free your own
ian@0 21 copy of the structure. You must not re-register over the top of the line
ian@0 22 discipline even with the same data or your computer again will be eaten by
ian@0 23 demons.
ian@0 24
ian@0 25 In order to remove a line discipline call tty_unregister_ldisc().
ian@0 26 In ancient times this always worked. In modern times the function will
ian@0 27 return -EBUSY if the ldisc is currently in use. Since the ldisc referencing
ian@0 28 code manages the module counts this should not usually be a concern.
ian@0 29
ian@0 30 Heed this warning: the reference count field of the registered copies of the
ian@0 31 tty_ldisc structure in the ldisc table counts the number of lines using this
ian@0 32 discipline. The reference count of the tty_ldisc structure within a tty
ian@0 33 counts the number of active users of the ldisc at this instant. In effect it
ian@0 34 counts the number of threads of execution within an ldisc method (plus those
ian@0 35 about to enter and exit although this detail matters not).
ian@0 36
ian@0 37 Line Discipline Methods
ian@0 38 -----------------------
ian@0 39
ian@0 40 TTY side interfaces:
ian@0 41
ian@0 42 close() - This is called on a terminal when the line
ian@0 43 discipline is being unplugged. At the point of
ian@0 44 execution no further users will enter the
ian@0 45 ldisc code for this tty. Can sleep.
ian@0 46
ian@0 47 open() - Called when the line discipline is attached to
ian@0 48 the terminal. No other call into the line
ian@0 49 discipline for this tty will occur until it
ian@0 50 completes successfully. Can sleep.
ian@0 51
ian@0 52 write() - A process is writing data through the line
ian@0 53 discipline. Multiple write calls are serialized
ian@0 54 by the tty layer for the ldisc. May sleep.
ian@0 55
ian@0 56 flush_buffer() - May be called at any point between open and close.
ian@0 57
ian@0 58 chars_in_buffer() - Report the number of bytes in the buffer.
ian@0 59
ian@0 60 set_termios() - Called on termios structure changes. The caller
ian@0 61 passes the old termios data and the current data
ian@0 62 is in the tty. Called under the termios semaphore so
ian@0 63 allowed to sleep. Serialized against itself only.
ian@0 64
ian@0 65 read() - Move data from the line discipline to the user.
ian@0 66 Multiple read calls may occur in parallel and the
ian@0 67 ldisc must deal with serialization issues. May
ian@0 68 sleep.
ian@0 69
ian@0 70 poll() - Check the status for the poll/select calls. Multiple
ian@0 71 poll calls may occur in parallel. May sleep.
ian@0 72
ian@0 73 ioctl() - Called when an ioctl is handed to the tty layer
ian@0 74 that might be for the ldisc. Multiple ioctl calls
ian@0 75 may occur in parallel. May sleep.
ian@0 76
ian@0 77 Driver Side Interfaces:
ian@0 78
ian@0 79 receive_buf() - Hand buffers of bytes from the driver to the ldisc
ian@0 80 for processing. Semantics currently rather
ian@0 81 mysterious 8(
ian@0 82
ian@0 83 write_wakeup() - May be called at any point between open and close.
ian@0 84 The TTY_DO_WRITE_WAKEUP flag indicates if a call
ian@0 85 is needed but always races versus calls. Thus the
ian@0 86 ldisc must be careful about setting order and to
ian@0 87 handle unexpected calls. Must not sleep.
ian@0 88
ian@0 89 The driver is forbidden from calling this directly
ian@0 90 from the ->write call from the ldisc as the ldisc
ian@0 91 is permitted to call the driver write method from
ian@0 92 this function. In such a situation defer it.
ian@0 93
ian@0 94
ian@0 95 Locking
ian@0 96
ian@0 97 Callers to the line discipline functions from the tty layer are required to
ian@0 98 take line discipline locks. The same is true of calls from the driver side
ian@0 99 but not yet enforced.
ian@0 100
ian@0 101 Three calls are now provided
ian@0 102
ian@0 103 ldisc = tty_ldisc_ref(tty);
ian@0 104
ian@0 105 takes a handle to the line discipline in the tty and returns it. If no ldisc
ian@0 106 is currently attached or the ldisc is being closed and re-opened at this
ian@0 107 point then NULL is returned. While this handle is held the ldisc will not
ian@0 108 change or go away.
ian@0 109
ian@0 110 tty_ldisc_deref(ldisc)
ian@0 111
ian@0 112 Returns the ldisc reference and allows the ldisc to be closed. Returning the
ian@0 113 reference takes away your right to call the ldisc functions until you take
ian@0 114 a new reference.
ian@0 115
ian@0 116 ldisc = tty_ldisc_ref_wait(tty);
ian@0 117
ian@0 118 Performs the same function as tty_ldisc_ref except that it will wait for an
ian@0 119 ldisc change to complete and then return a reference to the new ldisc.
ian@0 120
ian@0 121 While these functions are slightly slower than the old code they should have
ian@0 122 minimal impact as most receive logic uses the flip buffers and they only
ian@0 123 need to take a reference when they push bits up through the driver.
ian@0 124
ian@0 125 A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc
ian@0 126 functions are called with the ldisc unavailable. Thus tty_ldisc_ref will
ian@0 127 fail in this situation if used within these functions. Ldisc and driver
ian@0 128 code calling its own functions must be careful in this case.
ian@0 129
ian@0 130
ian@0 131 Driver Interface
ian@0 132 ----------------
ian@0 133
ian@0 134 open() - Called when a device is opened. May sleep
ian@0 135
ian@0 136 close() - Called when a device is closed. At the point of
ian@0 137 return from this call the driver must make no
ian@0 138 further ldisc calls of any kind. May sleep
ian@0 139
ian@0 140 write() - Called to write bytes to the device. May not
ian@0 141 sleep. May occur in parallel in special cases.
ian@0 142 Because this includes panic paths drivers generally
ian@0 143 shouldn't try and do clever locking here.
ian@0 144
ian@0 145 put_char() - Stuff a single character onto the queue. The
ian@0 146 driver is guaranteed following up calls to
ian@0 147 flush_chars.
ian@0 148
ian@0 149 flush_chars() - Ask the kernel to write put_char queue
ian@0 150
ian@0 151 write_room() - Return the number of characters tht can be stuffed
ian@0 152 into the port buffers without overflow (or less).
ian@0 153 The ldisc is responsible for being intelligent
ian@0 154 about multi-threading of write_room/write calls
ian@0 155
ian@0 156 ioctl() - Called when an ioctl may be for the driver
ian@0 157
ian@0 158 set_termios() - Called on termios change, serialized against
ian@0 159 itself by a semaphore. May sleep.
ian@0 160
ian@0 161 set_ldisc() - Notifier for discipline change. At the point this
ian@0 162 is done the discipline is not yet usable. Can now
ian@0 163 sleep (I think)
ian@0 164
ian@0 165 throttle() - Called by the ldisc to ask the driver to do flow
ian@0 166 control. Serialization including with unthrottle
ian@0 167 is the job of the ldisc layer.
ian@0 168
ian@0 169 unthrottle() - Called by the ldisc to ask the driver to stop flow
ian@0 170 control.
ian@0 171
ian@0 172 stop() - Ldisc notifier to the driver to stop output. As with
ian@0 173 throttle the serializations with start() are down
ian@0 174 to the ldisc layer.
ian@0 175
ian@0 176 start() - Ldisc notifier to the driver to start output.
ian@0 177
ian@0 178 hangup() - Ask the tty driver to cause a hangup initiated
ian@0 179 from the host side. [Can sleep ??]
ian@0 180
ian@0 181 break_ctl() - Send RS232 break. Can sleep. Can get called in
ian@0 182 parallel, driver must serialize (for now), and
ian@0 183 with write calls.
ian@0 184
ian@0 185 wait_until_sent() - Wait for characters to exit the hardware queue
ian@0 186 of the driver. Can sleep
ian@0 187
ian@0 188 send_xchar() - Send XON/XOFF and if possible jump the queue with
ian@0 189 it in order to get fast flow control responses.
ian@0 190 Cannot sleep ??
ian@0 191