6 $Id: driver,v 1.10 2002/07/22 15:27:30 rmk Exp $
9 This document is meant as a brief overview of some aspects of the new serial
10 driver. It is not complete, any questions you have should be directed to
11 <rmk@arm.linux.org.uk>
13 The reference implementation is contained within serial_amba.c.
17 Low Level Serial Hardware Driver
18 --------------------------------
20 The low level serial hardware driver is responsible for supplying port
21 information (defined by uart_port) and a set of control methods (defined
22 by uart_ops) to the core serial driver. The low level driver is also
23 responsible for handling interrupts for the port, and providing any
30 The serial core provides a few helper functions. This includes identifing
31 the correct port structure (via uart_get_console) and decoding command line
32 arguments (uart_parse_options).
38 It is the responsibility of the low level hardware driver to perform the
39 necessary locking using port->lock. There are some exceptions (which
40 are described in the uart_ops listing below.)
42 There are three locks. A per-port spinlock, a per-port tmpbuf semaphore,
43 and an overall semaphore.
45 From the core driver perspective, the port->lock locks the following
50 info->xmit.head (circ->head)
51 info->xmit.tail (circ->tail)
53 The low level driver is free to use this lock to provide any additional
56 The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded
57 access to the info->tmpbuf bouncebuffer used for port writes.
59 The port_sem semaphore is used to protect against ports being added/
60 removed or reconfigured at inappropriate times.
66 The uart_ops structure is the main interface between serial_core and the
67 hardware specific driver. It contains all the methods to control the
71 This function tests whether the transmitter fifo and shifter
72 for the port described by 'port' is empty. If it is empty,
73 this function should return TIOCSER_TEMT, otherwise return 0.
74 If the port does not support this operation, then it should
78 Interrupts: caller dependent.
79 This call must not sleep
81 set_mctrl(port, mctrl)
82 This function sets the modem control lines for port described
83 by 'port' to the state described by mctrl. The relevant bits
85 - TIOCM_RTS RTS signal.
86 - TIOCM_DTR DTR signal.
87 - TIOCM_OUT1 OUT1 signal.
88 - TIOCM_OUT2 OUT2 signal.
89 If the appropriate bit is set, the signal should be driven
90 active. If the bit is clear, the signal should be driven
93 Locking: port->lock taken.
94 Interrupts: locally disabled.
95 This call must not sleep
98 Returns the current state of modem control inputs. The state
99 of the outputs should not be returned, since the core keeps
100 track of their state. The state information should include:
101 - TIOCM_DCD state of DCD signal
102 - TIOCM_CTS state of CTS signal
103 - TIOCM_DSR state of DSR signal
104 - TIOCM_RI state of RI signal
105 The bit is set if the signal is currently driven active. If
106 the port does not support CTS, DCD or DSR, the driver should
107 indicate that the signal is permanently active. If RI is
108 not available, the signal should not be indicated as active.
111 Interrupts: caller dependent.
112 This call must not sleep
114 stop_tx(port,tty_stop)
115 Stop transmitting characters. This might be due to the CTS
116 line becoming inactive or the tty layer indicating we want
117 to stop transmission.
119 tty_stop: 1 if this call is due to the TTY layer issuing a
120 TTY stop to the driver (equiv to rs_stop).
122 Locking: port->lock taken.
123 Interrupts: locally disabled.
124 This call must not sleep
126 start_tx(port,tty_start)
127 start transmitting characters. (incidentally, nonempty will
128 always be nonzero, and shouldn't be used - it will be dropped).
130 tty_start: 1 if this call was due to the TTY layer issuing
131 a TTY start to the driver (equiv to rs_start)
133 Locking: port->lock taken.
134 Interrupts: locally disabled.
135 This call must not sleep
138 Stop receiving characters; the port is in the process of
141 Locking: port->lock taken.
142 Interrupts: locally disabled.
143 This call must not sleep
146 Enable the modem status interrupts.
148 Locking: port->lock taken.
149 Interrupts: locally disabled.
150 This call must not sleep
153 Control the transmission of a break signal. If ctl is
154 nonzero, the break signal should be transmitted. The signal
155 should be terminated when another call is made with a zero
159 Interrupts: caller dependent.
160 This call must not sleep
163 Grab any interrupt resources and initialise any low level driver
164 state. Enable the port for reception. It should not activate
165 RTS nor DTR; this will be done via a separate call to set_mctrl.
167 Locking: port_sem taken.
168 Interrupts: globally disabled.
171 Disable the port, disable any break condition that may be in
172 effect, and free any interrupt resources. It should not disable
173 RTS nor DTR; this will have already been done via a separate
176 Locking: port_sem taken.
177 Interrupts: caller dependent.
179 set_termios(port,termios,oldtermios)
180 Change the port parameters, including word length, parity, stop
181 bits. Update read_status_mask and ignore_status_mask to indicate
182 the types of events we are interested in receiving. Relevant
183 termios->c_cflag bits are:
186 PARENB - parity enable
187 PARODD - odd parity (when PARENB is in force)
188 CREAD - enable reception of characters (if not set,
189 still receive characters from the port, but
191 CRTSCTS - if set, enable CTS status change reporting
192 CLOCAL - if not set, enable modem status change
194 Relevant termios->c_iflag bits are:
195 INPCK - enable frame and parity error events to be
196 passed to the TTY layer.
198 PARMRK - both of these enable break events to be
199 passed to the TTY layer.
201 IGNPAR - ignore parity and framing errors
202 IGNBRK - ignore break errors, If IGNPAR is also
203 set, ignore overrun errors as well.
204 The interaction of the iflag bits is as follows (parity error
205 given as an example):
206 Parity error INPCK IGNPAR
207 None n/a n/a character received
208 Yes n/a 0 character discarded
209 Yes 0 1 character received, marked as
211 Yes 1 1 character received, marked as
215 Interrupts: caller dependent.
216 This call must not sleep
218 pm(port,state,oldstate)
219 perform any power management related activities on the specified
220 port. state indicates the new state (defined by ACPI D0-D3),
221 oldstate indicates the previous state. Essentially, D0 means
222 fully on, D3 means powered down.
224 This function should not be used to grab any resources.
227 Interrupts: caller dependent.
230 Return a pointer to a string constant describing the specified
231 port, or return NULL, in which case the string 'unknown' is
235 Interrupts: caller dependent.
238 Release any memory and IO region resources currently in use by
242 Interrupts: caller dependent.
245 Request any memory and IO region resources required by the port.
246 If any fail, no resources should be registered when this function
247 returns, and it should return -EBUSY on failure.
250 Interrupts: caller dependent.
252 config_port(port,type)
253 Perform any autoconfiguration steps required for the port. `type`
254 contains a bit mask of the required configuration. UART_CONFIG_TYPE
255 indicates that the port requires detection and identification.
256 port->type should be set to the type found, or PORT_UNKNOWN if
257 no port was detected.
259 UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal,
260 which should be probed using standard kernel autoprobing techniques.
261 This is not necessary on platforms where ports have interrupts
262 internally hard wired (eg, system on a chip implementations).
265 Interrupts: caller dependent.
267 verify_port(port,serinfo)
268 Verify the new serial port information contained within serinfo is
269 suitable for this port type.
272 Interrupts: caller dependent.
275 Perform any port specific IOCTLs. IOCTL commands must be defined
276 using the standard numbering system found in <asm/ioctl.h>
279 Interrupts: caller dependent.
284 uart_update_timeout(port,cflag,quot)
285 Update the FIFO drain timeout, port->timeout, according to the
286 number of bits, parity, stop bits and quotient.
288 Locking: caller is expected to take port->lock
291 uart_get_baud_rate(port,termios)
292 Return the numeric baud rate for the specified termios, taking
293 account of the special 38400 baud "kludge". The B0 baud rate
294 is mapped to 9600 baud.
296 Locking: caller dependent.
299 uart_get_divisor(port,termios,oldtermios)
300 Return the divsor (baud_base / baud) for the selected baud rate
301 specified by termios. If the baud rate is out of range, try
302 the original baud rate specified by oldtermios (if non-NULL).
303 If that fails, try 9600 baud.
305 If 38400 baud and custom divisor is selected, return the
306 custom divisor instead.
308 Locking: caller dependent.
314 It is intended some day to drop the 'unused' entries from uart_port, and
315 allow low level drivers to register their own individual uart_port's with
316 the core. This will allow drivers to use uart_port as a pointer to a
317 structure containing both the uart_port entry with their own extensions,
321 struct uart_port port;