Fedora kernel-2.6.17-1.2142_FC4 patched with stable patch-2.6.17.4-vs2.0.2-rc26.diff

[linux-2.6.git] / Documentation / serial / driver

diff --git a/Documentation/serial/driver b/Documentation/serial/driver
index e9c0178..88ad615 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>
 
 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).
 
 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
 -------
 
 Locking
 -------


@@ -86,6 +88,7 @@ hardware.
                - TIOCM_DTR     DTR signal.
                - TIOCM_OUT1    OUT1 signal.
                - TIOCM_OUT2    OUT2 signal.
                - 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.
        If the appropriate bit is set, the signal should be driven
        active.  If the bit is clear, the signal should be driven
        inactive.


@@ -107,28 +110,24 @@ hardware.
        indicate that the signal is permanently active.  If RI is
        not available, the signal should not be indicated as active.
 
        indicate that the signal is permanently active.  If RI is
        not available, the signal should not be indicated as active.
 

-       Locking: none.
-       Interrupts: caller dependent.
+       Locking: port->lock taken.
+       Interrupts: locally disabled.

        This call must not sleep
 
        This call must not sleep
 

-  stop_tx(port,tty_stop)
+  stop_tx(port)

        Stop transmitting characters.  This might be due to the CTS
        line becoming inactive or the tty layer indicating we want
        Stop transmitting characters.  This might be due to the CTS
        line becoming inactive or the tty layer indicating we want

-       to stop transmission.
+       to stop transmission due to an XOFF character.

 
 

-       tty_stop: 1 if this call is due to the TTY layer issuing a
-                 TTY stop to the driver (equiv to rs_stop).
+       The driver should stop transmitting characters as soon as
+       possible.

 
        Locking: port->lock taken.
        Interrupts: locally disabled.
        This call must not sleep
 
 
        Locking: port->lock taken.
        Interrupts: locally disabled.
        This call must not sleep
 

-  start_tx(port,tty_start)
-       start transmitting characters.  (incidentally, nonempty will
-       always be nonzero, and shouldn't be used - it will be dropped).
-
-       tty_start: 1 if this call was due to the TTY layer issuing
-                  a TTY start to the driver (equiv to rs_start)
+  start_tx(port)
+       Start transmitting characters.

 
        Locking: port->lock taken.
        Interrupts: locally disabled.
 
        Locking: port->lock taken.
        Interrupts: locally disabled.


@@ -145,6 +144,10 @@ hardware.
   enable_ms(port)
        Enable the modem status interrupts.
 
   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
        Locking: port->lock taken.
        Interrupts: locally disabled.
        This call must not sleep


@@ -164,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.
 
        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.
 
        Locking: port_sem taken.
        Interrupts: globally disabled.
 


@@ -173,6 +178,11 @@ hardware.
        RTS nor DTR; this will have already been done via a separate
        call to set_mctrl.
 
        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.
 
        Locking: port_sem taken.
        Interrupts: caller dependent.
 


@@ -204,12 +214,13 @@ hardware.
        The interaction of the iflag bits is as follows (parity error
        given as an example):
        Parity error    INPCK   IGNPAR
        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
                                        TTY_NORMAL

-       Yes             1       1       character received, marked as
+       None            1       n/a     character received, marked as
+                                       TTY_NORMAL
+       Yes             1       0       character received, marked as

                                        TTY_PARITY
                                        TTY_PARITY

+       Yes             1       1       character discarded

 
        Other flags may be used (eg, xon/xoff characters) if your
        hardware supports hardware "soft" flow control.
 
        Other flags may be used (eg, xon/xoff characters) if your
        hardware supports hardware "soft" flow control.


@@ -288,26 +299,31 @@ hardware.
 Other functions
 ---------------
 
 Other functions
 ---------------
 

-uart_update_timeout(port,cflag,quot)
+uart_update_timeout(port,cflag,baud)

        Update the FIFO drain timeout, port->timeout, according to the
        Update the FIFO drain timeout, port->timeout, according to the

-       number of bits, parity, stop bits and quotient.
+       number of bits, parity, stop bits and baud rate.

 
        Locking: caller is expected to take port->lock
        Interrupts: n/a
 
 
        Locking: caller is expected to take port->lock
        Interrupts: n/a
 

-uart_get_baud_rate(port,termios)
+uart_get_baud_rate(port,termios,old,min,max)

        Return the numeric baud rate for the specified termios, taking
        account of the special 38400 baud "kludge".  The B0 baud rate
        is mapped to 9600 baud.
 
        Return the numeric baud rate for the specified termios, taking
        account of the special 38400 baud "kludge".  The B0 baud rate
        is mapped to 9600 baud.
 

+       If the baud rate is not within min..max, then if old is non-NULL,
+       the original baud rate will be tried.  If that exceeds the
+       min..max constraint, 9600 baud will be returned.  termios will
+       be updated to the baud rate in use.
+
+       Note: min..max must always allow 9600 baud to be selected.
+

        Locking: caller dependent.
        Interrupts: n/a
 
        Locking: caller dependent.
        Interrupts: n/a
 

-uart_get_divisor(port,termios,oldtermios)
-       Return the divsor (baud_base / baud) for the selected baud rate
-       specified by termios.  If the baud rate is out of range, try
-       the original baud rate specified by oldtermios (if non-NULL).
-       If that fails, try 9600 baud.
+uart_get_divisor(port,baud)
+       Return the divsor (baud_base / baud) for the specified baud
+       rate, appropriately rounded.

 
        If 38400 baud and custom divisor is selected, return the
        custom divisor instead.
 
        If 38400 baud and custom divisor is selected, return the
        custom divisor instead.


@@ -315,6 +331,46 @@ uart_get_divisor(port,termios,oldtermios)
        Locking: caller dependent.
        Interrupts: n/a
 
        Locking: caller dependent.
        Interrupts: n/a
 

+uart_match_port(port1,port2)
+       This utility function can be used to determine whether two
+       uart_port structures describe the same port.
+
+       Locking: n/a
+       Interrupts: n/a
+
+uart_write_wakeup(port)
+       A driver is expected to call this function when the number of
+       characters in the transmit buffer have dropped below a threshold.
+
+       Locking: port->lock should be held.
+       Interrupts: n/a
+
+uart_register_driver(drv)
+       Register a uart driver with the core driver.  We in turn register
+       with the tty layer, and initialise the core driver per-port state.
+
+       drv->port should be NULL, and the per-port structures should be
+       registered using uart_add_one_port after this call has succeeded.
+
+       Locking: none
+       Interrupts: enabled
+
+uart_unregister_driver()
+       Remove all references to a driver from the core driver.  The low
+       level driver must have removed all its ports via the
+       uart_remove_one_port() if it registered them with uart_add_one_port().
+
+       Locking: none
+       Interrupts: enabled
+
+uart_suspend_port()
+
+uart_resume_port()
+
+uart_add_one_port()
+
+uart_remove_one_port()
+

 Other notes
 -----------
 
 Other notes
 -----------