--------------------
- $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.
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
-------
- 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.
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
- 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
- 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
- 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.
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
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.
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.
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
- 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
+ Yes 1 1 character discarded
Other flags may be used (eg, xon/xoff characters) if your
hardware supports hardware "soft" flow control.
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.
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
-----------
git://git.onelab.eu / linux-2.6.git / blobdiff