]>
Commit | Line | Data |
---|---|---|
f1374017 MCC |
1 | ==================== |
2 | Low Level Serial API | |
3 | ==================== | |
1da177e4 LT |
4 | |
5 | ||
1da177e4 LT |
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 | ||
c1a02c21 | 10 | The reference implementation is contained within amba-pl011.c. |
1da177e4 LT |
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 | ||
d124fd3b GU |
31 | There is also a helper function (uart_console_write) 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 | ||
1da177e4 LT |
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 | ||
4895b1d7 | 44 | There are two locks. A per-port spinlock, and an overall semaphore. |
1da177e4 LT |
45 | |
46 | From the core driver perspective, the port->lock locks the following | |
f1374017 | 47 | data:: |
1da177e4 LT |
48 | |
49 | port->mctrl | |
50 | port->icount | |
b79ef07d GU |
51 | port->state->xmit.head (circ_buf->head) |
52 | port->state->xmit.tail (circ_buf->tail) | |
1da177e4 LT |
53 | |
54 | The low level driver is free to use this lock to provide any additional | |
55 | locking. | |
56 | ||
1da177e4 | 57 | The port_sem semaphore is used to protect against ports being added/ |
7c8ab967 PH |
58 | removed or reconfigured at inappropriate times. Since v2.6.27, this |
59 | semaphore has been the 'mutex' member of the tty_port struct, and | |
95f981f2 | 60 | commonly referred to as the port mutex. |
1da177e4 LT |
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. | |
f1374017 | 78 | |
1da177e4 | 79 | Interrupts: caller dependent. |
f1374017 | 80 | |
1da177e4 LT |
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: | |
f1374017 | 87 | |
1da177e4 LT |
88 | - TIOCM_RTS RTS signal. |
89 | - TIOCM_DTR DTR signal. | |
90 | - TIOCM_OUT1 OUT1 signal. | |
91 | - TIOCM_OUT2 OUT2 signal. | |
67ab7f59 | 92 | - TIOCM_LOOP Set the port into loopback mode. |
f1374017 | 93 | |
1da177e4 LT |
94 | If the appropriate bit is set, the signal should be driven |
95 | active. If the bit is clear, the signal should be driven | |
96 | inactive. | |
97 | ||
98 | Locking: port->lock taken. | |
f1374017 | 99 | |
1da177e4 | 100 | Interrupts: locally disabled. |
f1374017 | 101 | |
1da177e4 LT |
102 | This call must not sleep |
103 | ||
104 | get_mctrl(port) | |
105 | Returns the current state of modem control inputs. The state | |
106 | of the outputs should not be returned, since the core keeps | |
107 | track of their state. The state information should include: | |
f1374017 | 108 | |
343fe407 | 109 | - TIOCM_CAR state of DCD signal |
1da177e4 LT |
110 | - TIOCM_CTS state of CTS signal |
111 | - TIOCM_DSR state of DSR signal | |
112 | - TIOCM_RI state of RI signal | |
f1374017 | 113 | |
1da177e4 LT |
114 | The bit is set if the signal is currently driven active. If |
115 | the port does not support CTS, DCD or DSR, the driver should | |
116 | indicate that the signal is permanently active. If RI is | |
117 | not available, the signal should not be indicated as active. | |
118 | ||
c5f4644e | 119 | Locking: port->lock taken. |
f1374017 | 120 | |
c5f4644e | 121 | Interrupts: locally disabled. |
f1374017 | 122 | |
1da177e4 LT |
123 | This call must not sleep |
124 | ||
b129a8cc | 125 | stop_tx(port) |
1da177e4 LT |
126 | Stop transmitting characters. This might be due to the CTS |
127 | line becoming inactive or the tty layer indicating we want | |
b129a8cc | 128 | to stop transmission due to an XOFF character. |
1da177e4 | 129 | |
6a8f8d72 RK |
130 | The driver should stop transmitting characters as soon as |
131 | possible. | |
132 | ||
1da177e4 | 133 | Locking: port->lock taken. |
f1374017 | 134 | |
1da177e4 | 135 | Interrupts: locally disabled. |
f1374017 | 136 | |
1da177e4 LT |
137 | This call must not sleep |
138 | ||
b129a8cc | 139 | start_tx(port) |
6a8f8d72 | 140 | Start transmitting characters. |
1da177e4 LT |
141 | |
142 | Locking: port->lock taken. | |
f1374017 | 143 | |
1da177e4 | 144 | Interrupts: locally disabled. |
f1374017 | 145 | |
1da177e4 LT |
146 | This call must not sleep |
147 | ||
39c5144e GU |
148 | throttle(port) |
149 | Notify the serial driver that input buffers for the line discipline are | |
150 | close to full, and it should somehow signal that no more characters | |
151 | should be sent to the serial port. | |
a3bedc3b | 152 | This will be called only if hardware assisted flow control is enabled. |
39c5144e | 153 | |
18717b06 | 154 | Locking: serialized with .unthrottle() and termios modification by the |
f1374017 | 155 | tty layer. |
39c5144e | 156 | |
e27585c7 GU |
157 | unthrottle(port) |
158 | Notify the serial driver that characters can now be sent to the serial | |
159 | port without fear of overrunning the input buffers of the line | |
160 | disciplines. | |
f1374017 | 161 | |
a3bedc3b | 162 | This will be called only if hardware assisted flow control is enabled. |
e27585c7 | 163 | |
18717b06 | 164 | Locking: serialized with .throttle() and termios modification by the |
f1374017 | 165 | tty layer. |
e27585c7 | 166 | |
e759d7c5 KC |
167 | send_xchar(port,ch) |
168 | Transmit a high priority character, even if the port is stopped. | |
169 | This is used to implement XON/XOFF flow control and tcflow(). If | |
170 | the serial driver does not implement this function, the tty core | |
171 | will append the character to the circular buffer and then call | |
172 | start_tx() / stop_tx() to flush the data out. | |
173 | ||
db106df3 PH |
174 | Do not transmit if ch == '\0' (__DISABLED_CHAR). |
175 | ||
e759d7c5 | 176 | Locking: none. |
f1374017 | 177 | |
e759d7c5 KC |
178 | Interrupts: caller dependent. |
179 | ||
1da177e4 LT |
180 | stop_rx(port) |
181 | Stop receiving characters; the port is in the process of | |
182 | being closed. | |
183 | ||
184 | Locking: port->lock taken. | |
f1374017 | 185 | |
1da177e4 | 186 | Interrupts: locally disabled. |
f1374017 | 187 | |
1da177e4 LT |
188 | This call must not sleep |
189 | ||
190 | enable_ms(port) | |
191 | Enable the modem status interrupts. | |
192 | ||
67ab7f59 RK |
193 | This method may be called multiple times. Modem status |
194 | interrupts should be disabled when the shutdown method is | |
195 | called. | |
196 | ||
1da177e4 | 197 | Locking: port->lock taken. |
f1374017 | 198 | |
1da177e4 | 199 | Interrupts: locally disabled. |
f1374017 | 200 | |
1da177e4 LT |
201 | This call must not sleep |
202 | ||
203 | break_ctl(port,ctl) | |
204 | Control the transmission of a break signal. If ctl is | |
205 | nonzero, the break signal should be transmitted. The signal | |
206 | should be terminated when another call is made with a zero | |
207 | ctl. | |
208 | ||
95f981f2 | 209 | Locking: caller holds tty_port->mutex |
1da177e4 LT |
210 | |
211 | startup(port) | |
212 | Grab any interrupt resources and initialise any low level driver | |
213 | state. Enable the port for reception. It should not activate | |
214 | RTS nor DTR; this will be done via a separate call to set_mctrl. | |
215 | ||
67ab7f59 RK |
216 | This method will only be called when the port is initially opened. |
217 | ||
1da177e4 | 218 | Locking: port_sem taken. |
f1374017 | 219 | |
1da177e4 LT |
220 | Interrupts: globally disabled. |
221 | ||
222 | shutdown(port) | |
223 | Disable the port, disable any break condition that may be in | |
224 | effect, and free any interrupt resources. It should not disable | |
225 | RTS nor DTR; this will have already been done via a separate | |
226 | call to set_mctrl. | |
227 | ||
b79ef07d | 228 | Drivers must not access port->state once this call has completed. |
67ab7f59 RK |
229 | |
230 | This method will only be called when there are no more users of | |
231 | this port. | |
232 | ||
1da177e4 | 233 | Locking: port_sem taken. |
f1374017 | 234 | |
1da177e4 LT |
235 | Interrupts: caller dependent. |
236 | ||
6bb0e3a5 HS |
237 | flush_buffer(port) |
238 | Flush any write buffers, reset any DMA state and stop any | |
239 | ongoing DMA transfers. | |
240 | ||
b79ef07d | 241 | This will be called whenever the port->state->xmit circular |
6bb0e3a5 HS |
242 | buffer is cleared. |
243 | ||
244 | Locking: port->lock taken. | |
f1374017 | 245 | |
6bb0e3a5 | 246 | Interrupts: locally disabled. |
f1374017 | 247 | |
6bb0e3a5 HS |
248 | This call must not sleep |
249 | ||
1da177e4 LT |
250 | set_termios(port,termios,oldtermios) |
251 | Change the port parameters, including word length, parity, stop | |
252 | bits. Update read_status_mask and ignore_status_mask to indicate | |
253 | the types of events we are interested in receiving. Relevant | |
254 | termios->c_cflag bits are: | |
f1374017 MCC |
255 | |
256 | CSIZE | |
257 | - word size | |
258 | CSTOPB | |
259 | - 2 stop bits | |
260 | PARENB | |
261 | - parity enable | |
262 | PARODD | |
263 | - odd parity (when PARENB is in force) | |
264 | CREAD | |
265 | - enable reception of characters (if not set, | |
1da177e4 LT |
266 | still receive characters from the port, but |
267 | throw them away. | |
f1374017 MCC |
268 | CRTSCTS |
269 | - if set, enable CTS status change reporting | |
270 | CLOCAL | |
271 | - if not set, enable modem status change | |
1da177e4 | 272 | reporting. |
f1374017 | 273 | |
1da177e4 | 274 | Relevant termios->c_iflag bits are: |
f1374017 MCC |
275 | |
276 | INPCK | |
277 | - enable frame and parity error events to be | |
1da177e4 | 278 | passed to the TTY layer. |
f1374017 MCC |
279 | BRKINT / PARMRK |
280 | - both of these enable break events to be | |
1da177e4 LT |
281 | passed to the TTY layer. |
282 | ||
f1374017 MCC |
283 | IGNPAR |
284 | - ignore parity and framing errors | |
285 | IGNBRK | |
286 | - ignore break errors, If IGNPAR is also | |
1da177e4 | 287 | set, ignore overrun errors as well. |
f1374017 | 288 | |
1da177e4 LT |
289 | The interaction of the iflag bits is as follows (parity error |
290 | given as an example): | |
f1374017 MCC |
291 | |
292 | =============== ======= ====== ============================= | |
1da177e4 | 293 | Parity error INPCK IGNPAR |
f1374017 | 294 | =============== ======= ====== ============================= |
89f3da3e | 295 | n/a 0 n/a character received, marked as |
1da177e4 | 296 | TTY_NORMAL |
89f3da3e PK |
297 | None 1 n/a character received, marked as |
298 | TTY_NORMAL | |
299 | Yes 1 0 character received, marked as | |
1da177e4 | 300 | TTY_PARITY |
89f3da3e | 301 | Yes 1 1 character discarded |
f1374017 | 302 | =============== ======= ====== ============================= |
1da177e4 LT |
303 | |
304 | Other flags may be used (eg, xon/xoff characters) if your | |
305 | hardware supports hardware "soft" flow control. | |
306 | ||
95f981f2 | 307 | Locking: caller holds tty_port->mutex |
f1374017 | 308 | |
1da177e4 | 309 | Interrupts: caller dependent. |
f1374017 | 310 | |
1da177e4 LT |
311 | This call must not sleep |
312 | ||
0adc301e | 313 | set_ldisc(port,termios) |
f1374017 | 314 | Notifier for discipline change. See Documentation/serial/tty.rst. |
0adc301e | 315 | |
95f981f2 | 316 | Locking: caller holds tty_port->mutex |
0adc301e | 317 | |
1da177e4 LT |
318 | pm(port,state,oldstate) |
319 | Perform any power management related activities on the specified | |
6f538fe3 LW |
320 | port. State indicates the new state (defined by |
321 | enum uart_pm_state), oldstate indicates the previous state. | |
1da177e4 LT |
322 | |
323 | This function should not be used to grab any resources. | |
324 | ||
325 | This will be called when the port is initially opened and finally | |
326 | closed, except when the port is also the system console. This | |
327 | will occur even if CONFIG_PM is not set. | |
328 | ||
329 | Locking: none. | |
f1374017 | 330 | |
1da177e4 LT |
331 | Interrupts: caller dependent. |
332 | ||
333 | type(port) | |
334 | Return a pointer to a string constant describing the specified | |
335 | port, or return NULL, in which case the string 'unknown' is | |
336 | substituted. | |
337 | ||
338 | Locking: none. | |
f1374017 | 339 | |
1da177e4 LT |
340 | Interrupts: caller dependent. |
341 | ||
342 | release_port(port) | |
343 | Release any memory and IO region resources currently in use by | |
344 | the port. | |
345 | ||
346 | Locking: none. | |
f1374017 | 347 | |
1da177e4 LT |
348 | Interrupts: caller dependent. |
349 | ||
350 | request_port(port) | |
351 | Request any memory and IO region resources required by the port. | |
352 | If any fail, no resources should be registered when this function | |
353 | returns, and it should return -EBUSY on failure. | |
354 | ||
355 | Locking: none. | |
f1374017 | 356 | |
1da177e4 LT |
357 | Interrupts: caller dependent. |
358 | ||
359 | config_port(port,type) | |
360 | Perform any autoconfiguration steps required for the port. `type` | |
361 | contains a bit mask of the required configuration. UART_CONFIG_TYPE | |
362 | indicates that the port requires detection and identification. | |
363 | port->type should be set to the type found, or PORT_UNKNOWN if | |
364 | no port was detected. | |
365 | ||
366 | UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal, | |
367 | which should be probed using standard kernel autoprobing techniques. | |
368 | This is not necessary on platforms where ports have interrupts | |
369 | internally hard wired (eg, system on a chip implementations). | |
370 | ||
371 | Locking: none. | |
f1374017 | 372 | |
1da177e4 LT |
373 | Interrupts: caller dependent. |
374 | ||
375 | verify_port(port,serinfo) | |
376 | Verify the new serial port information contained within serinfo is | |
377 | suitable for this port type. | |
378 | ||
379 | Locking: none. | |
f1374017 | 380 | |
1da177e4 LT |
381 | Interrupts: caller dependent. |
382 | ||
383 | ioctl(port,cmd,arg) | |
384 | Perform any port specific IOCTLs. IOCTL commands must be defined | |
385 | using the standard numbering system found in <asm/ioctl.h> | |
386 | ||
387 | Locking: none. | |
f1374017 | 388 | |
1da177e4 LT |
389 | Interrupts: caller dependent. |
390 | ||
e759d7c5 KC |
391 | poll_init(port) |
392 | Called by kgdb to perform the minimal hardware initialization needed | |
393 | to support poll_put_char() and poll_get_char(). Unlike ->startup() | |
394 | this should not request interrupts. | |
395 | ||
396 | Locking: tty_mutex and tty_port->mutex taken. | |
f1374017 | 397 | |
e759d7c5 KC |
398 | Interrupts: n/a. |
399 | ||
400 | poll_put_char(port,ch) | |
401 | Called by kgdb to write a single character directly to the serial | |
402 | port. It can and should block until there is space in the TX FIFO. | |
403 | ||
404 | Locking: none. | |
f1374017 | 405 | |
e759d7c5 | 406 | Interrupts: caller dependent. |
f1374017 | 407 | |
e759d7c5 KC |
408 | This call must not sleep |
409 | ||
410 | poll_get_char(port) | |
411 | Called by kgdb to read a single character directly from the serial | |
412 | port. If data is available, it should be returned; otherwise | |
413 | the function should return NO_POLL_CHAR immediately. | |
414 | ||
415 | Locking: none. | |
f1374017 | 416 | |
e759d7c5 | 417 | Interrupts: caller dependent. |
f1374017 | 418 | |
e759d7c5 KC |
419 | This call must not sleep |
420 | ||
1da177e4 LT |
421 | Other functions |
422 | --------------- | |
423 | ||
6a8f8d72 | 424 | uart_update_timeout(port,cflag,baud) |
1da177e4 | 425 | Update the FIFO drain timeout, port->timeout, according to the |
6a8f8d72 | 426 | number of bits, parity, stop bits and baud rate. |
1da177e4 LT |
427 | |
428 | Locking: caller is expected to take port->lock | |
f1374017 | 429 | |
1da177e4 LT |
430 | Interrupts: n/a |
431 | ||
6a8f8d72 | 432 | uart_get_baud_rate(port,termios,old,min,max) |
1da177e4 LT |
433 | Return the numeric baud rate for the specified termios, taking |
434 | account of the special 38400 baud "kludge". The B0 baud rate | |
435 | is mapped to 9600 baud. | |
436 | ||
6a8f8d72 RK |
437 | If the baud rate is not within min..max, then if old is non-NULL, |
438 | the original baud rate will be tried. If that exceeds the | |
439 | min..max constraint, 9600 baud will be returned. termios will | |
440 | be updated to the baud rate in use. | |
441 | ||
442 | Note: min..max must always allow 9600 baud to be selected. | |
443 | ||
1da177e4 | 444 | Locking: caller dependent. |
f1374017 | 445 | |
1da177e4 LT |
446 | Interrupts: n/a |
447 | ||
6a8f8d72 | 448 | uart_get_divisor(port,baud) |
93a2f632 | 449 | Return the divisor (baud_base / baud) for the specified baud |
6a8f8d72 | 450 | rate, appropriately rounded. |
1da177e4 LT |
451 | |
452 | If 38400 baud and custom divisor is selected, return the | |
453 | custom divisor instead. | |
454 | ||
455 | Locking: caller dependent. | |
f1374017 | 456 | |
1da177e4 LT |
457 | Interrupts: n/a |
458 | ||
6a8f8d72 RK |
459 | uart_match_port(port1,port2) |
460 | This utility function can be used to determine whether two | |
461 | uart_port structures describe the same port. | |
462 | ||
463 | Locking: n/a | |
f1374017 | 464 | |
6a8f8d72 RK |
465 | Interrupts: n/a |
466 | ||
467 | uart_write_wakeup(port) | |
468 | A driver is expected to call this function when the number of | |
469 | characters in the transmit buffer have dropped below a threshold. | |
470 | ||
471 | Locking: port->lock should be held. | |
f1374017 | 472 | |
6a8f8d72 RK |
473 | Interrupts: n/a |
474 | ||
475 | uart_register_driver(drv) | |
476 | Register a uart driver with the core driver. We in turn register | |
477 | with the tty layer, and initialise the core driver per-port state. | |
478 | ||
479 | drv->port should be NULL, and the per-port structures should be | |
480 | registered using uart_add_one_port after this call has succeeded. | |
481 | ||
482 | Locking: none | |
f1374017 | 483 | |
6a8f8d72 RK |
484 | Interrupts: enabled |
485 | ||
486 | uart_unregister_driver() | |
487 | Remove all references to a driver from the core driver. The low | |
488 | level driver must have removed all its ports via the | |
489 | uart_remove_one_port() if it registered them with uart_add_one_port(). | |
490 | ||
491 | Locking: none | |
f1374017 | 492 | |
6a8f8d72 RK |
493 | Interrupts: enabled |
494 | ||
f1374017 | 495 | **uart_suspend_port()** |
6a8f8d72 | 496 | |
f1374017 | 497 | **uart_resume_port()** |
6a8f8d72 | 498 | |
f1374017 | 499 | **uart_add_one_port()** |
6a8f8d72 | 500 | |
f1374017 | 501 | **uart_remove_one_port()** |
6a8f8d72 | 502 | |
1da177e4 LT |
503 | Other notes |
504 | ----------- | |
505 | ||
506 | It is intended some day to drop the 'unused' entries from uart_port, and | |
507 | allow low level drivers to register their own individual uart_port's with | |
508 | the core. This will allow drivers to use uart_port as a pointer to a | |
509 | structure containing both the uart_port entry with their own extensions, | |
f1374017 | 510 | thus:: |
1da177e4 LT |
511 | |
512 | struct my_port { | |
513 | struct uart_port port; | |
514 | int my_stuff; | |
515 | }; | |
84130aac RG |
516 | |
517 | Modem control lines via GPIO | |
518 | ---------------------------- | |
519 | ||
520 | Some helpers are provided in order to set/get modem control lines via GPIO. | |
521 | ||
ce59e48f | 522 | mctrl_gpio_init(port, idx): |
84130aac RG |
523 | This will get the {cts,rts,...}-gpios from device tree if they are |
524 | present and request them, set direction etc, and return an | |
f1374017 | 525 | allocated structure. `devm_*` functions are used, so there's no need |
84130aac | 526 | to call mctrl_gpio_free(). |
ce59e48f UKK |
527 | As this sets up the irq handling make sure to not handle changes to the |
528 | gpio input lines in your driver, too. | |
84130aac RG |
529 | |
530 | mctrl_gpio_free(dev, gpios): | |
531 | This will free the requested gpios in mctrl_gpio_init(). | |
f1374017 | 532 | As `devm_*` functions are used, there's generally no need to call |
84130aac RG |
533 | this function. |
534 | ||
535 | mctrl_gpio_to_gpiod(gpios, gidx) | |
4817ebb1 GU |
536 | This returns the gpio_desc structure associated to the modem line |
537 | index. | |
84130aac RG |
538 | |
539 | mctrl_gpio_set(gpios, mctrl): | |
540 | This will sets the gpios according to the mctrl state. | |
541 | ||
542 | mctrl_gpio_get(gpios, mctrl): | |
543 | This will update mctrl with the gpios values. | |
ce59e48f UKK |
544 | |
545 | mctrl_gpio_enable_ms(gpios): | |
546 | Enables irqs and handling of changes to the ms lines. | |
547 | ||
548 | mctrl_gpio_disable_ms(gpios): | |
549 | Disables irqs and handling of changes to the ms lines. |