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