Linux-2.6.12-rc2
[linux-3.10.git] / Documentation / serial / driver
1
2                         Low Level Serial API
3                         --------------------
4
5
6    $Id: driver,v 1.10 2002/07/22 15:27:30 rmk Exp $
7
8
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>
12
13 The reference implementation is contained within serial_amba.c.
14
15
16
17 Low Level Serial Hardware Driver
18 --------------------------------
19
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
24 console support.
25
26
27 Console Support
28 ---------------
29
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).
33
34
35 Locking
36 -------
37
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.)
41
42 There are three locks.  A per-port spinlock, a per-port tmpbuf semaphore,
43 and an overall semaphore.
44
45 From the core driver perspective, the port->lock locks the following
46 data:
47
48         port->mctrl
49         port->icount
50         info->xmit.head (circ->head)
51         info->xmit.tail (circ->tail)
52
53 The low level driver is free to use this lock to provide any additional
54 locking.
55
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.
58
59 The port_sem semaphore is used to protect against ports being added/
60 removed or reconfigured at inappropriate times.
61
62
63 uart_ops
64 --------
65
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
68 hardware.
69
70   tx_empty(port)
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
75         return TIOCSER_TEMT.
76
77         Locking: none.
78         Interrupts: caller dependent.
79         This call must not sleep
80
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
84         of mctrl are:
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
91         inactive.
92
93         Locking: port->lock taken.
94         Interrupts: locally disabled.
95         This call must not sleep
96
97   get_mctrl(port)
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.
109
110         Locking: none.
111         Interrupts: caller dependent.
112         This call must not sleep
113
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.
118
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).
121
122         Locking: port->lock taken.
123         Interrupts: locally disabled.
124         This call must not sleep
125
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).
129
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)
132
133         Locking: port->lock taken.
134         Interrupts: locally disabled.
135         This call must not sleep
136
137   stop_rx(port)
138         Stop receiving characters; the port is in the process of
139         being closed.
140
141         Locking: port->lock taken.
142         Interrupts: locally disabled.
143         This call must not sleep
144
145   enable_ms(port)
146         Enable the modem status interrupts.
147
148         Locking: port->lock taken.
149         Interrupts: locally disabled.
150         This call must not sleep
151
152   break_ctl(port,ctl)
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
156         ctl.
157
158         Locking: none.
159         Interrupts: caller dependent.
160         This call must not sleep
161
162   startup(port)
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.
166
167         Locking: port_sem taken.
168         Interrupts: globally disabled.
169
170   shutdown(port)
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
174         call to set_mctrl.
175
176         Locking: port_sem taken.
177         Interrupts: caller dependent.
178
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:
184                 CSIZE   - word size
185                 CSTOPB  - 2 stop bits
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
190                           throw them away.
191                 CRTSCTS - if set, enable CTS status change reporting
192                 CLOCAL  - if not set, enable modem status change
193                           reporting.
194         Relevant termios->c_iflag bits are:
195                 INPCK   - enable frame and parity error events to be
196                           passed to the TTY layer.
197                 BRKINT
198                 PARMRK  - both of these enable break events to be
199                           passed to the TTY layer.
200
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
210                                         TTY_NORMAL
211         Yes             1       1       character received, marked as
212                                         TTY_PARITY
213
214         Other flags may be used (eg, xon/xoff characters) if your
215         hardware supports hardware "soft" flow control.
216
217         Locking: none.
218         Interrupts: caller dependent.
219         This call must not sleep
220
221   pm(port,state,oldstate)
222         Perform any power management related activities on the specified
223         port.  State indicates the new state (defined by ACPI D0-D3),
224         oldstate indicates the previous state.  Essentially, D0 means
225         fully on, D3 means powered down.
226
227         This function should not be used to grab any resources.
228
229         This will be called when the port is initially opened and finally
230         closed, except when the port is also the system console.  This
231         will occur even if CONFIG_PM is not set.
232
233         Locking: none.
234         Interrupts: caller dependent.
235
236   type(port)
237         Return a pointer to a string constant describing the specified
238         port, or return NULL, in which case the string 'unknown' is
239         substituted.
240
241         Locking: none.
242         Interrupts: caller dependent.
243
244   release_port(port)
245         Release any memory and IO region resources currently in use by
246         the port.
247
248         Locking: none.
249         Interrupts: caller dependent.
250
251   request_port(port)
252         Request any memory and IO region resources required by the port.
253         If any fail, no resources should be registered when this function
254         returns, and it should return -EBUSY on failure.
255
256         Locking: none.
257         Interrupts: caller dependent.
258
259   config_port(port,type)
260         Perform any autoconfiguration steps required for the port.  `type`
261         contains a bit mask of the required configuration.  UART_CONFIG_TYPE
262         indicates that the port requires detection and identification.
263         port->type should be set to the type found, or PORT_UNKNOWN if
264         no port was detected.
265
266         UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal,
267         which should be probed using standard kernel autoprobing techniques.
268         This is not necessary on platforms where ports have interrupts
269         internally hard wired (eg, system on a chip implementations).
270
271         Locking: none.
272         Interrupts: caller dependent.
273
274   verify_port(port,serinfo)
275         Verify the new serial port information contained within serinfo is
276         suitable for this port type.
277
278         Locking: none.
279         Interrupts: caller dependent.
280
281   ioctl(port,cmd,arg)
282         Perform any port specific IOCTLs.  IOCTL commands must be defined
283         using the standard numbering system found in <asm/ioctl.h>
284
285         Locking: none.
286         Interrupts: caller dependent.
287
288 Other functions
289 ---------------
290
291 uart_update_timeout(port,cflag,quot)
292         Update the FIFO drain timeout, port->timeout, according to the
293         number of bits, parity, stop bits and quotient.
294
295         Locking: caller is expected to take port->lock
296         Interrupts: n/a
297
298 uart_get_baud_rate(port,termios)
299         Return the numeric baud rate for the specified termios, taking
300         account of the special 38400 baud "kludge".  The B0 baud rate
301         is mapped to 9600 baud.
302
303         Locking: caller dependent.
304         Interrupts: n/a
305
306 uart_get_divisor(port,termios,oldtermios)
307         Return the divsor (baud_base / baud) for the selected baud rate
308         specified by termios.  If the baud rate is out of range, try
309         the original baud rate specified by oldtermios (if non-NULL).
310         If that fails, try 9600 baud.
311
312         If 38400 baud and custom divisor is selected, return the
313         custom divisor instead.
314
315         Locking: caller dependent.
316         Interrupts: n/a
317
318 Other notes
319 -----------
320
321 It is intended some day to drop the 'unused' entries from uart_port, and
322 allow low level drivers to register their own individual uart_port's with
323 the core.  This will allow drivers to use uart_port as a pointer to a
324 structure containing both the uart_port entry with their own extensions,
325 thus:
326
327         struct my_port {
328                 struct uart_port        port;
329                 int                     my_stuff;
330         };