Root/
1 | |
2 | Low Level Serial API |
3 | -------------------- |
4 | |
5 | |
6 | This document is meant as a brief overview of some aspects of the new serial |
7 | driver. It is not complete, any questions you have should be directed to |
8 | <rmk@arm.linux.org.uk> |
9 | |
10 | The reference implementation is contained within amba_pl011.c. |
11 | |
12 | |
13 | |
14 | Low Level Serial Hardware Driver |
15 | -------------------------------- |
16 | |
17 | The low level serial hardware driver is responsible for supplying port |
18 | information (defined by uart_port) and a set of control methods (defined |
19 | by uart_ops) to the core serial driver. The low level driver is also |
20 | responsible for handling interrupts for the port, and providing any |
21 | console support. |
22 | |
23 | |
24 | Console Support |
25 | --------------- |
26 | |
27 | The serial core provides a few helper functions. This includes identifing |
28 | the correct port structure (via uart_get_console) and decoding command line |
29 | arguments (uart_parse_options). |
30 | |
31 | There is also a helper function (uart_write_console) which performs a |
32 | character by character write, translating newlines to CRLF sequences. |
33 | Driver writers are recommended to use this function rather than implementing |
34 | their own version. |
35 | |
36 | |
37 | Locking |
38 | ------- |
39 | |
40 | It is the responsibility of the low level hardware driver to perform the |
41 | necessary locking using port->lock. There are some exceptions (which |
42 | are described in the uart_ops listing below.) |
43 | |
44 | There are three locks. A per-port spinlock, a per-port tmpbuf semaphore, |
45 | and an overall semaphore. |
46 | |
47 | From the core driver perspective, the port->lock locks the following |
48 | data: |
49 | |
50 | port->mctrl |
51 | port->icount |
52 | info->xmit.head (circ->head) |
53 | info->xmit.tail (circ->tail) |
54 | |
55 | The low level driver is free to use this lock to provide any additional |
56 | locking. |
57 | |
58 | The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded |
59 | access to the info->tmpbuf bouncebuffer used for port writes. |
60 | |
61 | The port_sem semaphore is used to protect against ports being added/ |
62 | removed or reconfigured at inappropriate times. |
63 | |
64 | |
65 | uart_ops |
66 | -------- |
67 | |
68 | The uart_ops structure is the main interface between serial_core and the |
69 | hardware specific driver. It contains all the methods to control the |
70 | hardware. |
71 | |
72 | tx_empty(port) |
73 | This function tests whether the transmitter fifo and shifter |
74 | for the port described by 'port' is empty. If it is empty, |
75 | this function should return TIOCSER_TEMT, otherwise return 0. |
76 | If the port does not support this operation, then it should |
77 | return TIOCSER_TEMT. |
78 | |
79 | Locking: none. |
80 | Interrupts: caller dependent. |
81 | This call must not sleep |
82 | |
83 | set_mctrl(port, mctrl) |
84 | This function sets the modem control lines for port described |
85 | by 'port' to the state described by mctrl. The relevant bits |
86 | of mctrl are: |
87 | - TIOCM_RTS RTS signal. |
88 | - TIOCM_DTR DTR signal. |
89 | - TIOCM_OUT1 OUT1 signal. |
90 | - TIOCM_OUT2 OUT2 signal. |
91 | - TIOCM_LOOP Set the port into loopback mode. |
92 | If the appropriate bit is set, the signal should be driven |
93 | active. If the bit is clear, the signal should be driven |
94 | inactive. |
95 | |
96 | Locking: port->lock taken. |
97 | Interrupts: locally disabled. |
98 | This call must not sleep |
99 | |
100 | get_mctrl(port) |
101 | Returns the current state of modem control inputs. The state |
102 | of the outputs should not be returned, since the core keeps |
103 | track of their state. The state information should include: |
104 | - TIOCM_DCD state of DCD signal |
105 | - TIOCM_CTS state of CTS signal |
106 | - TIOCM_DSR state of DSR signal |
107 | - TIOCM_RI state of RI signal |
108 | The bit is set if the signal is currently driven active. If |
109 | the port does not support CTS, DCD or DSR, the driver should |
110 | indicate that the signal is permanently active. If RI is |
111 | not available, the signal should not be indicated as active. |
112 | |
113 | Locking: port->lock taken. |
114 | Interrupts: locally disabled. |
115 | This call must not sleep |
116 | |
117 | stop_tx(port) |
118 | Stop transmitting characters. This might be due to the CTS |
119 | line becoming inactive or the tty layer indicating we want |
120 | to stop transmission due to an XOFF character. |
121 | |
122 | The driver should stop transmitting characters as soon as |
123 | possible. |
124 | |
125 | Locking: port->lock taken. |
126 | Interrupts: locally disabled. |
127 | This call must not sleep |
128 | |
129 | start_tx(port) |
130 | Start transmitting characters. |
131 | |
132 | Locking: port->lock taken. |
133 | Interrupts: locally disabled. |
134 | This call must not sleep |
135 | |
136 | stop_rx(port) |
137 | Stop receiving characters; the port is in the process of |
138 | being closed. |
139 | |
140 | Locking: port->lock taken. |
141 | Interrupts: locally disabled. |
142 | This call must not sleep |
143 | |
144 | enable_ms(port) |
145 | Enable the modem status interrupts. |
146 | |
147 | This method may be called multiple times. Modem status |
148 | interrupts should be disabled when the shutdown method is |
149 | called. |
150 | |
151 | Locking: port->lock taken. |
152 | Interrupts: locally disabled. |
153 | This call must not sleep |
154 | |
155 | break_ctl(port,ctl) |
156 | Control the transmission of a break signal. If ctl is |
157 | nonzero, the break signal should be transmitted. The signal |
158 | should be terminated when another call is made with a zero |
159 | ctl. |
160 | |
161 | Locking: none. |
162 | Interrupts: caller dependent. |
163 | This call must not sleep |
164 | |
165 | startup(port) |
166 | Grab any interrupt resources and initialise any low level driver |
167 | state. Enable the port for reception. It should not activate |
168 | RTS nor DTR; this will be done via a separate call to set_mctrl. |
169 | |
170 | This method will only be called when the port is initially opened. |
171 | |
172 | Locking: port_sem taken. |
173 | Interrupts: globally disabled. |
174 | |
175 | shutdown(port) |
176 | Disable the port, disable any break condition that may be in |
177 | effect, and free any interrupt resources. It should not disable |
178 | RTS nor DTR; this will have already been done via a separate |
179 | call to set_mctrl. |
180 | |
181 | Drivers must not access port->info once this call has completed. |
182 | |
183 | This method will only be called when there are no more users of |
184 | this port. |
185 | |
186 | Locking: port_sem taken. |
187 | Interrupts: caller dependent. |
188 | |
189 | flush_buffer(port) |
190 | Flush any write buffers, reset any DMA state and stop any |
191 | ongoing DMA transfers. |
192 | |
193 | This will be called whenever the port->info->xmit circular |
194 | buffer is cleared. |
195 | |
196 | Locking: port->lock taken. |
197 | Interrupts: locally disabled. |
198 | This call must not sleep |
199 | |
200 | set_termios(port,termios,oldtermios) |
201 | Change the port parameters, including word length, parity, stop |
202 | bits. Update read_status_mask and ignore_status_mask to indicate |
203 | the types of events we are interested in receiving. Relevant |
204 | termios->c_cflag bits are: |
205 | CSIZE - word size |
206 | CSTOPB - 2 stop bits |
207 | PARENB - parity enable |
208 | PARODD - odd parity (when PARENB is in force) |
209 | CREAD - enable reception of characters (if not set, |
210 | still receive characters from the port, but |
211 | throw them away. |
212 | CRTSCTS - if set, enable CTS status change reporting |
213 | CLOCAL - if not set, enable modem status change |
214 | reporting. |
215 | Relevant termios->c_iflag bits are: |
216 | INPCK - enable frame and parity error events to be |
217 | passed to the TTY layer. |
218 | BRKINT |
219 | PARMRK - both of these enable break events to be |
220 | passed to the TTY layer. |
221 | |
222 | IGNPAR - ignore parity and framing errors |
223 | IGNBRK - ignore break errors, If IGNPAR is also |
224 | set, ignore overrun errors as well. |
225 | The interaction of the iflag bits is as follows (parity error |
226 | given as an example): |
227 | Parity error INPCK IGNPAR |
228 | n/a 0 n/a character received, marked as |
229 | TTY_NORMAL |
230 | None 1 n/a character received, marked as |
231 | TTY_NORMAL |
232 | Yes 1 0 character received, marked as |
233 | TTY_PARITY |
234 | Yes 1 1 character discarded |
235 | |
236 | Other flags may be used (eg, xon/xoff characters) if your |
237 | hardware supports hardware "soft" flow control. |
238 | |
239 | Locking: none. |
240 | Interrupts: caller dependent. |
241 | This call must not sleep |
242 | |
243 | pm(port,state,oldstate) |
244 | Perform any power management related activities on the specified |
245 | port. State indicates the new state (defined by ACPI D0-D3), |
246 | oldstate indicates the previous state. Essentially, D0 means |
247 | fully on, D3 means powered down. |
248 | |
249 | This function should not be used to grab any resources. |
250 | |
251 | This will be called when the port is initially opened and finally |
252 | closed, except when the port is also the system console. This |
253 | will occur even if CONFIG_PM is not set. |
254 | |
255 | Locking: none. |
256 | Interrupts: caller dependent. |
257 | |
258 | type(port) |
259 | Return a pointer to a string constant describing the specified |
260 | port, or return NULL, in which case the string 'unknown' is |
261 | substituted. |
262 | |
263 | Locking: none. |
264 | Interrupts: caller dependent. |
265 | |
266 | release_port(port) |
267 | Release any memory and IO region resources currently in use by |
268 | the port. |
269 | |
270 | Locking: none. |
271 | Interrupts: caller dependent. |
272 | |
273 | request_port(port) |
274 | Request any memory and IO region resources required by the port. |
275 | If any fail, no resources should be registered when this function |
276 | returns, and it should return -EBUSY on failure. |
277 | |
278 | Locking: none. |
279 | Interrupts: caller dependent. |
280 | |
281 | config_port(port,type) |
282 | Perform any autoconfiguration steps required for the port. `type` |
283 | contains a bit mask of the required configuration. UART_CONFIG_TYPE |
284 | indicates that the port requires detection and identification. |
285 | port->type should be set to the type found, or PORT_UNKNOWN if |
286 | no port was detected. |
287 | |
288 | UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal, |
289 | which should be probed using standard kernel autoprobing techniques. |
290 | This is not necessary on platforms where ports have interrupts |
291 | internally hard wired (eg, system on a chip implementations). |
292 | |
293 | Locking: none. |
294 | Interrupts: caller dependent. |
295 | |
296 | verify_port(port,serinfo) |
297 | Verify the new serial port information contained within serinfo is |
298 | suitable for this port type. |
299 | |
300 | Locking: none. |
301 | Interrupts: caller dependent. |
302 | |
303 | ioctl(port,cmd,arg) |
304 | Perform any port specific IOCTLs. IOCTL commands must be defined |
305 | using the standard numbering system found in <asm/ioctl.h> |
306 | |
307 | Locking: none. |
308 | Interrupts: caller dependent. |
309 | |
310 | Other functions |
311 | --------------- |
312 | |
313 | uart_update_timeout(port,cflag,baud) |
314 | Update the FIFO drain timeout, port->timeout, according to the |
315 | number of bits, parity, stop bits and baud rate. |
316 | |
317 | Locking: caller is expected to take port->lock |
318 | Interrupts: n/a |
319 | |
320 | uart_get_baud_rate(port,termios,old,min,max) |
321 | Return the numeric baud rate for the specified termios, taking |
322 | account of the special 38400 baud "kludge". The B0 baud rate |
323 | is mapped to 9600 baud. |
324 | |
325 | If the baud rate is not within min..max, then if old is non-NULL, |
326 | the original baud rate will be tried. If that exceeds the |
327 | min..max constraint, 9600 baud will be returned. termios will |
328 | be updated to the baud rate in use. |
329 | |
330 | Note: min..max must always allow 9600 baud to be selected. |
331 | |
332 | Locking: caller dependent. |
333 | Interrupts: n/a |
334 | |
335 | uart_get_divisor(port,baud) |
336 | Return the divsor (baud_base / baud) for the specified baud |
337 | rate, appropriately rounded. |
338 | |
339 | If 38400 baud and custom divisor is selected, return the |
340 | custom divisor instead. |
341 | |
342 | Locking: caller dependent. |
343 | Interrupts: n/a |
344 | |
345 | uart_match_port(port1,port2) |
346 | This utility function can be used to determine whether two |
347 | uart_port structures describe the same port. |
348 | |
349 | Locking: n/a |
350 | Interrupts: n/a |
351 | |
352 | uart_write_wakeup(port) |
353 | A driver is expected to call this function when the number of |
354 | characters in the transmit buffer have dropped below a threshold. |
355 | |
356 | Locking: port->lock should be held. |
357 | Interrupts: n/a |
358 | |
359 | uart_register_driver(drv) |
360 | Register a uart driver with the core driver. We in turn register |
361 | with the tty layer, and initialise the core driver per-port state. |
362 | |
363 | drv->port should be NULL, and the per-port structures should be |
364 | registered using uart_add_one_port after this call has succeeded. |
365 | |
366 | Locking: none |
367 | Interrupts: enabled |
368 | |
369 | uart_unregister_driver() |
370 | Remove all references to a driver from the core driver. The low |
371 | level driver must have removed all its ports via the |
372 | uart_remove_one_port() if it registered them with uart_add_one_port(). |
373 | |
374 | Locking: none |
375 | Interrupts: enabled |
376 | |
377 | uart_suspend_port() |
378 | |
379 | uart_resume_port() |
380 | |
381 | uart_add_one_port() |
382 | |
383 | uart_remove_one_port() |
384 | |
385 | Other notes |
386 | ----------- |
387 | |
388 | It is intended some day to drop the 'unused' entries from uart_port, and |
389 | allow low level drivers to register their own individual uart_port's with |
390 | the core. This will allow drivers to use uart_port as a pointer to a |
391 | structure containing both the uart_port entry with their own extensions, |
392 | thus: |
393 | |
394 | struct my_port { |
395 | struct uart_port port; |
396 | int my_stuff; |
397 | }; |
398 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9