X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=Documentation%2Fserial%2Fdriver;h=88ad615dd338d75e2b282422c8f2d6f7f3af80b7;hb=43bc926fffd92024b46cafaf7350d669ba9ca884;hp=e9c0178cd202dafa7097e545152afe49a11b6628;hpb=cee37fe97739d85991964371c1f3a745c00dd236;p=linux-2.6.git diff --git a/Documentation/serial/driver b/Documentation/serial/driver index e9c0178cd..88ad615dd 100644 --- 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 -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. @@ -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. - 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. @@ -145,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 @@ -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. + This method will only be called when the port is initially opened. + 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. + 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. @@ -204,12 +214,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 - 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. @@ -288,26 +299,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. @@ -315,6 +331,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 -----------