Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
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
9This document is meant as a brief overview of some aspects of the new serial
10driver. It is not complete, any questions you have should be directed to
11<rmk@arm.linux.org.uk>
12
13The reference implementation is contained within serial_amba.c.
14
15
16
17Low Level Serial Hardware Driver
18--------------------------------
19
20The low level serial hardware driver is responsible for supplying port
21information (defined by uart_port) and a set of control methods (defined
22by uart_ops) to the core serial driver. The low level driver is also
23responsible for handling interrupts for the port, and providing any
24console support.
25
26
27Console Support
28---------------
29
30The serial core provides a few helper functions. This includes identifing
31the correct port structure (via uart_get_console) and decoding command line
32arguments (uart_parse_options).
33
34
35Locking
36-------
37
38It is the responsibility of the low level hardware driver to perform the
39necessary locking using port->lock. There are some exceptions (which
40are described in the uart_ops listing below.)
41
42There are three locks. A per-port spinlock, a per-port tmpbuf semaphore,
43and an overall semaphore.
44
45From the core driver perspective, the port->lock locks the following
46data:
47
48 port->mctrl
49 port->icount
50 info->xmit.head (circ->head)
51 info->xmit.tail (circ->tail)
52
53The low level driver is free to use this lock to provide any additional
54locking.
55
56The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded
57access to the info->tmpbuf bouncebuffer used for port writes.
58
59The port_sem semaphore is used to protect against ports being added/
60removed or reconfigured at inappropriate times.
61
62
63uart_ops
64--------
65
66The uart_ops structure is the main interface between serial_core and the
67hardware specific driver. It contains all the methods to control the
68hardware.
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
288Other functions
289---------------
290
291uart_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
298uart_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
306uart_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
318Other notes
319-----------
320
321It is intended some day to drop the 'unused' entries from uart_port, and
322allow low level drivers to register their own individual uart_port's with
323the core. This will allow drivers to use uart_port as a pointer to a
324structure containing both the uart_port entry with their own extensions,
325thus:
326
327 struct my_port {
328 struct uart_port port;
329 int my_stuff;
330 };