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
10 The reference implementation is contained within amba_pl011.c.
14 Low Level Serial Hardware Driver
15 --------------------------------
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
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).
35 It is the responsibility of the low level hardware driver to perform the
36 necessary locking using port->lock. There are some exceptions (which
37 are described in the uart_ops listing below.)
39 There are three locks. A per-port spinlock, a per-port tmpbuf semaphore,
40 and an overall semaphore.
42 From the core driver perspective, the port->lock locks the following
47 info->xmit.head (circ->head)
48 info->xmit.tail (circ->tail)
50 The low level driver is free to use this lock to provide any additional
53 The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded
54 access to the info->tmpbuf bouncebuffer used for port writes.
56 The port_sem semaphore is used to protect against ports being added/
57 removed or reconfigured at inappropriate times. Since v2.6.27, this
58 semaphore has been the 'mutex' member of the tty_port struct, and
59 commonly referred to as the port mutex (or port->mutex).
65 The uart_ops structure is the main interface between serial_core and the
66 hardware specific driver. It contains all the methods to control the
70 This function tests whether the transmitter fifo and shifter
71 for the port described by 'port' is empty. If it is empty,
72 this function should return TIOCSER_TEMT, otherwise return 0.
73 If the port does not support this operation, then it should
77 Interrupts: caller dependent.
78 This call must not sleep
80 set_mctrl(port, mctrl)
81 This function sets the modem control lines for port described
82 by 'port' to the state described by mctrl. The relevant bits
84 - TIOCM_RTS RTS signal.
85 - TIOCM_DTR DTR signal.
86 - TIOCM_OUT1 OUT1 signal.
87 - TIOCM_OUT2 OUT2 signal.
88 - TIOCM_LOOP Set the port into loopback mode.
89 If the appropriate bit is set, the signal should be driven
90 active. If the bit is clear, the signal should be driven
93 Locking: port->lock taken.
94 Interrupts: locally disabled.
95 This call must not sleep
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_CAR 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.
110 Locking: port->lock taken.
111 Interrupts: locally disabled.
112 This call must not sleep
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.
119 The driver should stop transmitting characters as soon as
122 Locking: port->lock taken.
123 Interrupts: locally disabled.
124 This call must not sleep
127 Start transmitting characters.
129 Locking: port->lock taken.
130 Interrupts: locally disabled.
131 This call must not sleep
134 Transmit a high priority character, even if the port is stopped.
135 This is used to implement XON/XOFF flow control and tcflow(). If
136 the serial driver does not implement this function, the tty core
137 will append the character to the circular buffer and then call
138 start_tx() / stop_tx() to flush the data out.
140 Do not transmit if ch == '\0' (__DISABLED_CHAR).
143 Interrupts: caller dependent.
146 Stop receiving characters; the port is in the process of
149 Locking: port->lock taken.
150 Interrupts: locally disabled.
151 This call must not sleep
154 Enable the modem status interrupts.
156 This method may be called multiple times. Modem status
157 interrupts should be disabled when the shutdown method is
160 Locking: port->lock taken.
161 Interrupts: locally disabled.
162 This call must not sleep
165 Control the transmission of a break signal. If ctl is
166 nonzero, the break signal should be transmitted. The signal
167 should be terminated when another call is made with a zero
171 Interrupts: caller dependent.
172 This call must not sleep
175 Grab any interrupt resources and initialise any low level driver
176 state. Enable the port for reception. It should not activate
177 RTS nor DTR; this will be done via a separate call to set_mctrl.
179 This method will only be called when the port is initially opened.
181 Locking: port_sem taken.
182 Interrupts: globally disabled.
185 Disable the port, disable any break condition that may be in
186 effect, and free any interrupt resources. It should not disable
187 RTS nor DTR; this will have already been done via a separate
190 Drivers must not access port->info once this call has completed.
192 This method will only be called when there are no more users of
195 Locking: port_sem taken.
196 Interrupts: caller dependent.
199 Flush any write buffers, reset any DMA state and stop any
200 ongoing DMA transfers.
202 This will be called whenever the port->info->xmit circular
205 Locking: port->lock taken.
206 Interrupts: locally disabled.
207 This call must not sleep
209 set_termios(port,termios,oldtermios)
210 Change the port parameters, including word length, parity, stop
211 bits. Update read_status_mask and ignore_status_mask to indicate
212 the types of events we are interested in receiving. Relevant
213 termios->c_cflag bits are:
216 PARENB - parity enable
217 PARODD - odd parity (when PARENB is in force)
218 CREAD - enable reception of characters (if not set,
219 still receive characters from the port, but
221 CRTSCTS - if set, enable CTS status change reporting
222 CLOCAL - if not set, enable modem status change
224 Relevant termios->c_iflag bits are:
225 INPCK - enable frame and parity error events to be
226 passed to the TTY layer.
228 PARMRK - both of these enable break events to be
229 passed to the TTY layer.
231 IGNPAR - ignore parity and framing errors
232 IGNBRK - ignore break errors, If IGNPAR is also
233 set, ignore overrun errors as well.
234 The interaction of the iflag bits is as follows (parity error
235 given as an example):
236 Parity error INPCK IGNPAR
237 n/a 0 n/a character received, marked as
239 None 1 n/a character received, marked as
241 Yes 1 0 character received, marked as
243 Yes 1 1 character discarded
245 Other flags may be used (eg, xon/xoff characters) if your
246 hardware supports hardware "soft" flow control.
248 Locking: caller holds port->mutex
249 Interrupts: caller dependent.
250 This call must not sleep
252 pm(port,state,oldstate)
253 Perform any power management related activities on the specified
254 port. State indicates the new state (defined by
255 enum uart_pm_state), oldstate indicates the previous state.
257 This function should not be used to grab any resources.
259 This will be called when the port is initially opened and finally
260 closed, except when the port is also the system console. This
261 will occur even if CONFIG_PM is not set.
264 Interrupts: caller dependent.
267 Return a pointer to a string constant describing the specified
268 port, or return NULL, in which case the string 'unknown' is
272 Interrupts: caller dependent.
275 Release any memory and IO region resources currently in use by
279 Interrupts: caller dependent.
282 Request any memory and IO region resources required by the port.
283 If any fail, no resources should be registered when this function
284 returns, and it should return -EBUSY on failure.
287 Interrupts: caller dependent.
289 config_port(port,type)
290 Perform any autoconfiguration steps required for the port. `type`
291 contains a bit mask of the required configuration. UART_CONFIG_TYPE
292 indicates that the port requires detection and identification.
293 port->type should be set to the type found, or PORT_UNKNOWN if
294 no port was detected.
296 UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal,
297 which should be probed using standard kernel autoprobing techniques.
298 This is not necessary on platforms where ports have interrupts
299 internally hard wired (eg, system on a chip implementations).
302 Interrupts: caller dependent.
304 verify_port(port,serinfo)
305 Verify the new serial port information contained within serinfo is
306 suitable for this port type.
309 Interrupts: caller dependent.
312 Perform any port specific IOCTLs. IOCTL commands must be defined
313 using the standard numbering system found in <asm/ioctl.h>
316 Interrupts: caller dependent.
319 Called by kgdb to perform the minimal hardware initialization needed
320 to support poll_put_char() and poll_get_char(). Unlike ->startup()
321 this should not request interrupts.
323 Locking: tty_mutex and tty_port->mutex taken.
326 poll_put_char(port,ch)
327 Called by kgdb to write a single character directly to the serial
328 port. It can and should block until there is space in the TX FIFO.
331 Interrupts: caller dependent.
332 This call must not sleep
335 Called by kgdb to read a single character directly from the serial
336 port. If data is available, it should be returned; otherwise
337 the function should return NO_POLL_CHAR immediately.
340 Interrupts: caller dependent.
341 This call must not sleep
346 uart_update_timeout(port,cflag,baud)
347 Update the FIFO drain timeout, port->timeout, according to the
348 number of bits, parity, stop bits and baud rate.
350 Locking: caller is expected to take port->lock
353 uart_get_baud_rate(port,termios,old,min,max)
354 Return the numeric baud rate for the specified termios, taking
355 account of the special 38400 baud "kludge". The B0 baud rate
356 is mapped to 9600 baud.
358 If the baud rate is not within min..max, then if old is non-NULL,
359 the original baud rate will be tried. If that exceeds the
360 min..max constraint, 9600 baud will be returned. termios will
361 be updated to the baud rate in use.
363 Note: min..max must always allow 9600 baud to be selected.
365 Locking: caller dependent.
368 uart_get_divisor(port,baud)
369 Return the divsor (baud_base / baud) for the specified baud
370 rate, appropriately rounded.
372 If 38400 baud and custom divisor is selected, return the
373 custom divisor instead.
375 Locking: caller dependent.
378 uart_match_port(port1,port2)
379 This utility function can be used to determine whether two
380 uart_port structures describe the same port.
385 uart_write_wakeup(port)
386 A driver is expected to call this function when the number of
387 characters in the transmit buffer have dropped below a threshold.
389 Locking: port->lock should be held.
392 uart_register_driver(drv)
393 Register a uart driver with the core driver. We in turn register
394 with the tty layer, and initialise the core driver per-port state.
396 drv->port should be NULL, and the per-port structures should be
397 registered using uart_add_one_port after this call has succeeded.
402 uart_unregister_driver()
403 Remove all references to a driver from the core driver. The low
404 level driver must have removed all its ports via the
405 uart_remove_one_port() if it registered them with uart_add_one_port().
416 uart_remove_one_port()
421 It is intended some day to drop the 'unused' entries from uart_port, and
422 allow low level drivers to register their own individual uart_port's with
423 the core. This will allow drivers to use uart_port as a pointer to a
424 structure containing both the uart_port entry with their own extensions,
428 struct uart_port port;
432 Modem control lines via GPIO
433 ----------------------------
435 Some helpers are provided in order to set/get modem control lines via GPIO.
437 mctrl_gpio_init(port, idx):
438 This will get the {cts,rts,...}-gpios from device tree if they are
439 present and request them, set direction etc, and return an
440 allocated structure. devm_* functions are used, so there's no need
441 to call mctrl_gpio_free().
442 As this sets up the irq handling make sure to not handle changes to the
443 gpio input lines in your driver, too.
445 mctrl_gpio_free(dev, gpios):
446 This will free the requested gpios in mctrl_gpio_init().
447 As devm_* function are used, there's generally no need to call
450 mctrl_gpio_to_gpiod(gpios, gidx)
451 This returns the gpio structure associated to the modem line index.
453 mctrl_gpio_set(gpios, mctrl):
454 This will sets the gpios according to the mctrl state.
456 mctrl_gpio_get(gpios, mctrl):
457 This will update mctrl with the gpios values.
459 mctrl_gpio_enable_ms(gpios):
460 Enables irqs and handling of changes to the ms lines.
462 mctrl_gpio_disable_ms(gpios):
463 Disables irqs and handling of changes to the ms lines.