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: port->lock taken.
111 Interrupts: locally disabled.
112 This call must not sleep
113
114 stop_tx(port)
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 due to an XOFF character.
118
119 Locking: port->lock taken.
120 Interrupts: locally disabled.
121 This call must not sleep
122
123 start_tx(port)
124 start transmitting characters.
125
126 Locking: port->lock taken.
127 Interrupts: locally disabled.
128 This call must not sleep
129
130 stop_rx(port)
131 Stop receiving characters; the port is in the process of
132 being closed.
133
134 Locking: port->lock taken.
135 Interrupts: locally disabled.
136 This call must not sleep
137
138 enable_ms(port)
139 Enable the modem status interrupts.
140
141 Locking: port->lock taken.
142 Interrupts: locally disabled.
143 This call must not sleep
144
145 break_ctl(port,ctl)
146 Control the transmission of a break signal. If ctl is
147 nonzero, the break signal should be transmitted. The signal
148 should be terminated when another call is made with a zero
149 ctl.
150
151 Locking: none.
152 Interrupts: caller dependent.
153 This call must not sleep
154
155 startup(port)
156 Grab any interrupt resources and initialise any low level driver
157 state. Enable the port for reception. It should not activate
158 RTS nor DTR; this will be done via a separate call to set_mctrl.
159
160 Locking: port_sem taken.
161 Interrupts: globally disabled.
162
163 shutdown(port)
164 Disable the port, disable any break condition that may be in
165 effect, and free any interrupt resources. It should not disable
166 RTS nor DTR; this will have already been done via a separate
167 call to set_mctrl.
168
169 Locking: port_sem taken.
170 Interrupts: caller dependent.
171
172 set_termios(port,termios,oldtermios)
173 Change the port parameters, including word length, parity, stop
174 bits. Update read_status_mask and ignore_status_mask to indicate
175 the types of events we are interested in receiving. Relevant
176 termios->c_cflag bits are:
177 CSIZE - word size
178 CSTOPB - 2 stop bits
179 PARENB - parity enable
180 PARODD - odd parity (when PARENB is in force)
181 CREAD - enable reception of characters (if not set,
182 still receive characters from the port, but
183 throw them away.
184 CRTSCTS - if set, enable CTS status change reporting
185 CLOCAL - if not set, enable modem status change
186 reporting.
187 Relevant termios->c_iflag bits are:
188 INPCK - enable frame and parity error events to be
189 passed to the TTY layer.
190 BRKINT
191 PARMRK - both of these enable break events to be
192 passed to the TTY layer.
193
194 IGNPAR - ignore parity and framing errors
195 IGNBRK - ignore break errors, If IGNPAR is also
196 set, ignore overrun errors as well.
197 The interaction of the iflag bits is as follows (parity error
198 given as an example):
199 Parity error INPCK IGNPAR
200 None n/a n/a character received
201 Yes n/a 0 character discarded
202 Yes 0 1 character received, marked as
203 TTY_NORMAL
204 Yes 1 1 character received, marked as
205 TTY_PARITY
206
207 Other flags may be used (eg, xon/xoff characters) if your
208 hardware supports hardware "soft" flow control.
209
210 Locking: none.
211 Interrupts: caller dependent.
212 This call must not sleep
213
214 pm(port,state,oldstate)
215 Perform any power management related activities on the specified
216 port. State indicates the new state (defined by ACPI D0-D3),
217 oldstate indicates the previous state. Essentially, D0 means
218 fully on, D3 means powered down.
219
220 This function should not be used to grab any resources.
221
222 This will be called when the port is initially opened and finally
223 closed, except when the port is also the system console. This
224 will occur even if CONFIG_PM is not set.
225
226 Locking: none.
227 Interrupts: caller dependent.
228
229 type(port)
230 Return a pointer to a string constant describing the specified
231 port, or return NULL, in which case the string 'unknown' is
232 substituted.
233
234 Locking: none.
235 Interrupts: caller dependent.
236
237 release_port(port)
238 Release any memory and IO region resources currently in use by
239 the port.
240
241 Locking: none.
242 Interrupts: caller dependent.
243
244 request_port(port)
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.
248
249 Locking: none.
250 Interrupts: caller dependent.
251
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.
258
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).
263
264 Locking: none.
265 Interrupts: caller dependent.
266
267 verify_port(port,serinfo)
268 Verify the new serial port information contained within serinfo is
269 suitable for this port type.
270
271 Locking: none.
272 Interrupts: caller dependent.
273
274 ioctl(port,cmd,arg)
275 Perform any port specific IOCTLs. IOCTL commands must be defined
276 using the standard numbering system found in <asm/ioctl.h>
277
278 Locking: none.
279 Interrupts: caller dependent.
280
281Other functions
282---------------
283
284uart_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.
287
288 Locking: caller is expected to take port->lock
289 Interrupts: n/a
290
291uart_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.
295
296 Locking: caller dependent.
297 Interrupts: n/a
298
299uart_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.
304
305 If 38400 baud and custom divisor is selected, return the
306 custom divisor instead.
307
308 Locking: caller dependent.
309 Interrupts: n/a
310
311Other notes
312-----------
313
314It is intended some day to drop the 'unused' entries from uart_port, and
315allow low level drivers to register their own individual uart_port's with
316the core. This will allow drivers to use uart_port as a pointer to a
317structure containing both the uart_port entry with their own extensions,
318thus:
319
320 struct my_port {
321 struct uart_port port;
322 int my_stuff;
323 };