Root/
| 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 | can 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 | |
| 302 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9
