ia64/linux-2.6.18-xen.hg

diff Documentation/tty.txt @ 0:831230e53067

Import 2.6.18 from kernel.org tarball.
author Ian Campbell <ian.campbell@xensource.com>
date Wed Apr 11 14:15:44 2007 +0100 (2007-04-11)
parents
children
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/Documentation/tty.txt	Wed Apr 11 14:15:44 2007 +0100
     1.3 @@ -0,0 +1,191 @@
     1.4 +
     1.5 +			The Lockronomicon
     1.6 +
     1.7 +Your guide to the ancient and twisted locking policies of the tty layer and
     1.8 +the warped logic behind them. Beware all ye who read on.
     1.9 +
    1.10 +FIXME: still need to work out the full set of BKL assumptions and document
    1.11 +them so they can eventually be killed off.
    1.12 +
    1.13 +
    1.14 +Line Discipline
    1.15 +---------------
    1.16 +
    1.17 +Line disciplines are registered with tty_register_ldisc() passing the
    1.18 +discipline number and the ldisc structure. At the point of registration the 
    1.19 +discipline must be ready to use and it is possible it will get used before
    1.20 +the call returns success. If the call returns an error then it won't get
    1.21 +called. Do not re-use ldisc numbers as they are part of the userspace ABI
    1.22 +and writing over an existing ldisc will cause demons to eat your computer.
    1.23 +After the return the ldisc data has been copied so you may free your own 
    1.24 +copy of the structure. You must not re-register over the top of the line
    1.25 +discipline even with the same data or your computer again will be eaten by
    1.26 +demons.
    1.27 +
    1.28 +In order to remove a line discipline call tty_unregister_ldisc().
    1.29 +In ancient times this always worked. In modern times the function will
    1.30 +return -EBUSY if the ldisc is currently in use. Since the ldisc referencing
    1.31 +code manages the module counts this should not usually be a concern.
    1.32 +
    1.33 +Heed this warning: the reference count field of the registered copies of the
    1.34 +tty_ldisc structure in the ldisc table counts the number of lines using this
    1.35 +discipline. The reference count of the tty_ldisc structure within a tty 
    1.36 +counts the number of active users of the ldisc at this instant. In effect it
    1.37 +counts the number of threads of execution within an ldisc method (plus those
    1.38 +about to enter and exit although this detail matters not).
    1.39 +
    1.40 +Line Discipline Methods
    1.41 +-----------------------
    1.42 +
    1.43 +TTY side interfaces:
    1.44 +
    1.45 +close()		-	This is called on a terminal when the line
    1.46 +			discipline is being unplugged. At the point of
    1.47 +			execution no further users will enter the
    1.48 +			ldisc code for this tty. Can sleep.
    1.49 +
    1.50 +open()		-	Called when the line discipline is attached to
    1.51 +			the terminal. No other call into the line
    1.52 +			discipline for this tty will occur until it
    1.53 +			completes successfully. Can sleep.
    1.54 +
    1.55 +write()		-	A process is writing data through the line
    1.56 +			discipline.  Multiple write calls are serialized
    1.57 +			by the tty layer for the ldisc.  May sleep. 
    1.58 +
    1.59 +flush_buffer()	-	May be called at any point between open and close.
    1.60 +
    1.61 +chars_in_buffer() -	Report the number of bytes in the buffer.
    1.62 +
    1.63 +set_termios()	-	Called on termios structure changes. The caller
    1.64 +			passes the old termios data and the current data
    1.65 +			is in the tty. Called under the termios semaphore so
    1.66 +			allowed to sleep. Serialized against itself only.
    1.67 +
    1.68 +read()		-	Move data from the line discipline to the user.
    1.69 +			Multiple read calls may occur in parallel and the
    1.70 +			ldisc must deal with serialization issues. May 
    1.71 +			sleep.
    1.72 +
    1.73 +poll()		-	Check the status for the poll/select calls. Multiple
    1.74 +			poll calls may occur in parallel. May sleep.
    1.75 +
    1.76 +ioctl()		-	Called when an ioctl is handed to the tty layer
    1.77 +			that might be for the ldisc. Multiple ioctl calls
    1.78 +			may occur in parallel. May sleep. 
    1.79 +
    1.80 +Driver Side Interfaces:
    1.81 +
    1.82 +receive_buf()	-	Hand buffers of bytes from the driver to the ldisc
    1.83 +			for processing. Semantics currently rather
    1.84 +			mysterious 8(
    1.85 +
    1.86 +write_wakeup()	-	May be called at any point between open and close.
    1.87 +			The TTY_DO_WRITE_WAKEUP flag indicates if a call
    1.88 +			is needed but always races versus calls. Thus the
    1.89 +			ldisc must be careful about setting order and to
    1.90 +			handle unexpected calls. Must not sleep.
    1.91 +
    1.92 +			The driver is forbidden from calling this directly
    1.93 +			from the ->write call from the ldisc as the ldisc
    1.94 +			is permitted to call the driver write method from
    1.95 +			this function. In such a situation defer it.
    1.96 +
    1.97 +
    1.98 +Locking
    1.99 +
   1.100 +Callers to the line discipline functions from the tty layer are required to
   1.101 +take line discipline locks. The same is true of calls from the driver side
   1.102 +but not yet enforced.
   1.103 +
   1.104 +Three calls are now provided
   1.105 +
   1.106 +	ldisc = tty_ldisc_ref(tty);
   1.107 +
   1.108 +takes a handle to the line discipline in the tty and returns it. If no ldisc
   1.109 +is currently attached or the ldisc is being closed and re-opened at this
   1.110 +point then NULL is returned. While this handle is held the ldisc will not
   1.111 +change or go away.
   1.112 +
   1.113 +	tty_ldisc_deref(ldisc)
   1.114 +
   1.115 +Returns the ldisc reference and allows the ldisc to be closed. Returning the
   1.116 +reference takes away your right to call the ldisc functions until you take
   1.117 +a new reference.
   1.118 +
   1.119 +	ldisc = tty_ldisc_ref_wait(tty);
   1.120 +
   1.121 +Performs the same function as tty_ldisc_ref except that it will wait for an
   1.122 +ldisc change to complete and then return a reference to the new ldisc. 
   1.123 +
   1.124 +While these functions are slightly slower than the old code they should have
   1.125 +minimal impact as most receive logic uses the flip buffers and they only
   1.126 +need to take a reference when they push bits up through the driver.
   1.127 +
   1.128 +A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc 
   1.129 +functions are called with the ldisc unavailable. Thus tty_ldisc_ref will
   1.130 +fail in this situation if used within these functions. Ldisc and driver
   1.131 +code calling its own functions must be careful in this case. 
   1.132 +
   1.133 +
   1.134 +Driver Interface
   1.135 +----------------
   1.136 +
   1.137 +open()		-	Called when a device is opened. May sleep
   1.138 +
   1.139 +close()		-	Called when a device is closed. At the point of
   1.140 +			return from this call the driver must make no 
   1.141 +			further ldisc calls of any kind. May sleep
   1.142 +
   1.143 +write()		-	Called to write bytes to the device. May not
   1.144 +			sleep. May occur in parallel in special cases. 
   1.145 +			Because this includes panic paths drivers generally
   1.146 +			shouldn't try and do clever locking here.
   1.147 +
   1.148 +put_char()	-	Stuff a single character onto the queue. The
   1.149 +			driver is guaranteed following up calls to
   1.150 +			flush_chars.
   1.151 +
   1.152 +flush_chars()	-	Ask the kernel to write put_char queue
   1.153 +
   1.154 +write_room()	-	Return the number of characters tht can be stuffed
   1.155 +			into the port buffers without overflow (or less).
   1.156 +			The ldisc is responsible for being intelligent
   1.157 + 			about multi-threading of write_room/write calls
   1.158 +
   1.159 +ioctl()		-	Called when an ioctl may be for the driver
   1.160 +
   1.161 +set_termios()	-	Called on termios change, serialized against
   1.162 +			itself by a semaphore. May sleep.
   1.163 +
   1.164 +set_ldisc()	-	Notifier for discipline change. At the point this 
   1.165 +			is done the discipline is not yet usable. Can now
   1.166 +			sleep (I think)
   1.167 +
   1.168 +throttle()	-	Called by the ldisc to ask the driver to do flow
   1.169 +			control.  Serialization including with unthrottle
   1.170 +			is the job of the ldisc layer.
   1.171 +
   1.172 +unthrottle()	-	Called by the ldisc to ask the driver to stop flow
   1.173 +			control.
   1.174 +
   1.175 +stop()		-	Ldisc notifier to the driver to stop output. As with
   1.176 +			throttle the serializations with start() are down
   1.177 +			to the ldisc layer.
   1.178 +
   1.179 +start()		-	Ldisc notifier to the driver to start output.
   1.180 +
   1.181 +hangup()	-	Ask the tty driver to cause a hangup initiated
   1.182 +			from the host side. [Can sleep ??]
   1.183 +
   1.184 +break_ctl()	-	Send RS232 break. Can sleep. Can get called in
   1.185 +			parallel, driver must serialize (for now), and
   1.186 +			with write calls.
   1.187 +
   1.188 +wait_until_sent() -	Wait for characters to exit the hardware queue
   1.189 +			of the driver. Can sleep
   1.190 +
   1.191 +send_xchar()	  -	Send XON/XOFF and if possible jump the queue with
   1.192 +			it in order to get fast flow control responses.
   1.193 +			Cannot sleep ??
   1.194 +