Merge branch 'for-linus' of git://neil.brown.name/md

[pandora-kernel.git] / Documentation / serial / driver

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index 42ef997..77ba0af 100644 (file)
--- a/Documentation/serial/driver
+++ b/Documentation/serial/driver
@@ -3,14 +3,11 @@
                        --------------------
 
 
-   $Id: driver,v 1.10 2002/07/22 15:27:30 rmk Exp $
-
-
 This document is meant as a brief overview of some aspects of the new serial
 driver.  It is not complete, any questions you have should be directed to
 <rmk@arm.linux.org.uk>
 
-The reference implementation is contained within serial_amba.c.
+The reference implementation is contained within amba_pl011.c.
 
 
 
@@ -31,6 +28,11 @@ The serial core provides a few helper functions.  This includes identifing
 the correct port structure (via uart_get_console) and decoding command line
 arguments (uart_parse_options).
 
+There is also a helper function (uart_write_console) which performs a
+character by character write, translating newlines to CRLF sequences.
+Driver writers are recommended to use this function rather than implementing
+their own version.
+
 
 Locking
 -------
@@ -86,6 +88,7 @@ hardware.
                - TIOCM_DTR     DTR signal.
                - TIOCM_OUT1    OUT1 signal.
                - TIOCM_OUT2    OUT2 signal.
+               - TIOCM_LOOP    Set the port into loopback mode.
        If the appropriate bit is set, the signal should be driven
        active.  If the bit is clear, the signal should be driven
        inactive.
@@ -141,6 +144,10 @@ hardware.
   enable_ms(port)
        Enable the modem status interrupts.
 
+       This method may be called multiple times.  Modem status
+       interrupts should be disabled when the shutdown method is
+       called.
+
        Locking: port->lock taken.
        Interrupts: locally disabled.
        This call must not sleep
@@ -160,6 +167,8 @@ hardware.
        state.  Enable the port for reception.  It should not activate
        RTS nor DTR; this will be done via a separate call to set_mctrl.
 
+       This method will only be called when the port is initially opened.
+
        Locking: port_sem taken.
        Interrupts: globally disabled.
 
@@ -169,9 +178,25 @@ hardware.
        RTS nor DTR; this will have already been done via a separate
        call to set_mctrl.
 
+       Drivers must not access port->info once this call has completed.
+
+       This method will only be called when there are no more users of
+       this port.
+
        Locking: port_sem taken.
        Interrupts: caller dependent.
 
+  flush_buffer(port)
+       Flush any write buffers, reset any DMA state and stop any
+       ongoing DMA transfers.
+
+       This will be called whenever the port->info->xmit circular
+       buffer is cleared.
+
+       Locking: port->lock taken.
+       Interrupts: locally disabled.
+       This call must not sleep
+
   set_termios(port,termios,oldtermios)
        Change the port parameters, including word length, parity, stop
        bits.  Update read_status_mask and ignore_status_mask to indicate
@@ -200,12 +225,13 @@ hardware.
        The interaction of the iflag bits is as follows (parity error
        given as an example):
        Parity error    INPCK   IGNPAR
-       None            n/a     n/a     character received
-       Yes             n/a     0       character discarded
-       Yes             0       1       character received, marked as
+       n/a             0       n/a     character received, marked as
+                                       TTY_NORMAL
+       None            1       n/a     character received, marked as
                                        TTY_NORMAL
-       Yes             1       1       character received, marked as
+       Yes             1       0       character received, marked as
                                        TTY_PARITY
+       Yes             1       1       character discarded
 
        Other flags may be used (eg, xon/xoff characters) if your
        hardware supports hardware "soft" flow control.