[SERIAL] Update serial_core documentation
Russell King [Mon, 31 Oct 2005 11:53:19 +0000 (11:53 +0000)]
Signed-off-by: Russell King <rmk+kernel@arm.linux.org.uk>

Documentation/serial/driver

index 87856d3..42ef997 100644 (file)
@@ -116,12 +116,15 @@ hardware.
        line becoming inactive or the tty layer indicating we want
        to stop transmission due to an XOFF character.
 
+       The driver should stop transmitting characters as soon as
+       possible.
+
        Locking: port->lock taken.
        Interrupts: locally disabled.
        This call must not sleep
 
   start_tx(port)
-       start transmitting characters.
+       Start transmitting characters.
 
        Locking: port->lock taken.
        Interrupts: locally disabled.
@@ -281,26 +284,31 @@ hardware.
 Other functions
 ---------------
 
-uart_update_timeout(port,cflag,quot)
+uart_update_timeout(port,cflag,baud)
        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
 
-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.
 
+       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
 
-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.
@@ -308,6 +316,46 @@ uart_get_divisor(port,termios,oldtermios)
        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
 -----------