1==================== 2Low Level Serial API 3==================== 4 5 6This document is meant as a brief overview of some aspects of the new serial 7driver. It is not complete, any questions you have should be directed to 8<rmk@arm.linux.org.uk> 9 10The reference implementation is contained within amba-pl011.c. 11 12 13 14Low Level Serial Hardware Driver 15-------------------------------- 16 17The low level serial hardware driver is responsible for supplying port 18information (defined by uart_port) and a set of control methods (defined 19by uart_ops) to the core serial driver. The low level driver is also 20responsible for handling interrupts for the port, and providing any 21console support. 22 23 24Console Support 25--------------- 26 27The serial core provides a few helper functions. This includes identifing 28the correct port structure (via uart_get_console) and decoding command line 29arguments (uart_parse_options). 30 31There is also a helper function (uart_console_write) which performs a 32character by character write, translating newlines to CRLF sequences. 33Driver writers are recommended to use this function rather than implementing 34their own version. 35 36 37Locking 38------- 39 40It is the responsibility of the low level hardware driver to perform the 41necessary locking using port->lock. There are some exceptions (which 42are described in the uart_ops listing below.) 43 44There are two locks. A per-port spinlock, and an overall semaphore. 45 46From the core driver perspective, the port->lock locks the following 47data:: 48 49 port->mctrl 50 port->icount 51 port->state->xmit.head (circ_buf->head) 52 port->state->xmit.tail (circ_buf->tail) 53 54The low level driver is free to use this lock to provide any additional 55locking. 56 57The port_sem semaphore is used to protect against ports being added/ 58removed or reconfigured at inappropriate times. Since v2.6.27, this 59semaphore has been the 'mutex' member of the tty_port struct, and 60commonly referred to as the port mutex. 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 79 Interrupts: caller dependent. 80 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 88 - TIOCM_RTS RTS signal. 89 - TIOCM_DTR DTR signal. 90 - TIOCM_OUT1 OUT1 signal. 91 - TIOCM_OUT2 OUT2 signal. 92 - TIOCM_LOOP Set the port into loopback mode. 93 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. 99 100 Interrupts: locally disabled. 101 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: 108 109 - TIOCM_CAR state of DCD signal 110 - TIOCM_CTS state of CTS signal 111 - TIOCM_DSR state of DSR signal 112 - TIOCM_RI state of RI signal 113 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 119 Locking: port->lock taken. 120 121 Interrupts: locally disabled. 122 123 This call must not sleep 124 125 stop_tx(port) 126 Stop transmitting characters. This might be due to the CTS 127 line becoming inactive or the tty layer indicating we want 128 to stop transmission due to an XOFF character. 129 130 The driver should stop transmitting characters as soon as 131 possible. 132 133 Locking: port->lock taken. 134 135 Interrupts: locally disabled. 136 137 This call must not sleep 138 139 start_tx(port) 140 Start transmitting characters. 141 142 Locking: port->lock taken. 143 144 Interrupts: locally disabled. 145 146 This call must not sleep 147 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. 152 This will be called only if hardware assisted flow control is enabled. 153 154 Locking: serialized with .unthrottle() and termios modification by the 155 tty layer. 156 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. 161 162 This will be called only if hardware assisted flow control is enabled. 163 164 Locking: serialized with .throttle() and termios modification by the 165 tty layer. 166 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 174 Do not transmit if ch == '\0' (__DISABLED_CHAR). 175 176 Locking: none. 177 178 Interrupts: caller dependent. 179 180 stop_rx(port) 181 Stop receiving characters; the port is in the process of 182 being closed. 183 184 Locking: port->lock taken. 185 186 Interrupts: locally disabled. 187 188 This call must not sleep 189 190 enable_ms(port) 191 Enable the modem status interrupts. 192 193 This method may be called multiple times. Modem status 194 interrupts should be disabled when the shutdown method is 195 called. 196 197 Locking: port->lock taken. 198 199 Interrupts: locally disabled. 200 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 209 Locking: caller holds tty_port->mutex 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 216 This method will only be called when the port is initially opened. 217 218 Locking: port_sem taken. 219 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 228 Drivers must not access port->state once this call has completed. 229 230 This method will only be called when there are no more users of 231 this port. 232 233 Locking: port_sem taken. 234 235 Interrupts: caller dependent. 236 237 flush_buffer(port) 238 Flush any write buffers, reset any DMA state and stop any 239 ongoing DMA transfers. 240 241 This will be called whenever the port->state->xmit circular 242 buffer is cleared. 243 244 Locking: port->lock taken. 245 246 Interrupts: locally disabled. 247 248 This call must not sleep 249 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: 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, 266 still receive characters from the port, but 267 throw them away. 268 CRTSCTS 269 - if set, enable CTS status change reporting 270 CLOCAL 271 - if not set, enable modem status change 272 reporting. 273 274 Relevant termios->c_iflag bits are: 275 276 INPCK 277 - enable frame and parity error events to be 278 passed to the TTY layer. 279 BRKINT / PARMRK 280 - both of these enable break events to be 281 passed to the TTY layer. 282 283 IGNPAR 284 - ignore parity and framing errors 285 IGNBRK 286 - ignore break errors, If IGNPAR is also 287 set, ignore overrun errors as well. 288 289 The interaction of the iflag bits is as follows (parity error 290 given as an example): 291 292 =============== ======= ====== ============================= 293 Parity error INPCK IGNPAR 294 =============== ======= ====== ============================= 295 n/a 0 n/a character received, marked as 296 TTY_NORMAL 297 None 1 n/a character received, marked as 298 TTY_NORMAL 299 Yes 1 0 character received, marked as 300 TTY_PARITY 301 Yes 1 1 character discarded 302 =============== ======= ====== ============================= 303 304 Other flags may be used (eg, xon/xoff characters) if your 305 hardware supports hardware "soft" flow control. 306 307 Locking: caller holds tty_port->mutex 308 309 Interrupts: caller dependent. 310 311 This call must not sleep 312 313 set_ldisc(port,termios) 314 Notifier for discipline change. See Documentation/driver-api/serial/tty.rst. 315 316 Locking: caller holds tty_port->mutex 317 318 pm(port,state,oldstate) 319 Perform any power management related activities on the specified 320 port. State indicates the new state (defined by 321 enum uart_pm_state), oldstate indicates the previous state. 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. 330 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. 339 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. 347 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. 356 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. 372 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. 380 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. 388 389 Interrupts: caller dependent. 390 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. 397 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. 405 406 Interrupts: caller dependent. 407 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. 416 417 Interrupts: caller dependent. 418 419 This call must not sleep 420 421Other functions 422--------------- 423 424uart_update_timeout(port,cflag,baud) 425 Update the FIFO drain timeout, port->timeout, according to the 426 number of bits, parity, stop bits and baud rate. 427 428 Locking: caller is expected to take port->lock 429 430 Interrupts: n/a 431 432uart_get_baud_rate(port,termios,old,min,max) 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 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 444 Locking: caller dependent. 445 446 Interrupts: n/a 447 448uart_get_divisor(port,baud) 449 Return the divisor (baud_base / baud) for the specified baud 450 rate, appropriately rounded. 451 452 If 38400 baud and custom divisor is selected, return the 453 custom divisor instead. 454 455 Locking: caller dependent. 456 457 Interrupts: n/a 458 459uart_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 464 465 Interrupts: n/a 466 467uart_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. 472 473 Interrupts: n/a 474 475uart_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 483 484 Interrupts: enabled 485 486uart_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 492 493 Interrupts: enabled 494 495**uart_suspend_port()** 496 497**uart_resume_port()** 498 499**uart_add_one_port()** 500 501**uart_remove_one_port()** 502 503Other notes 504----------- 505 506It is intended some day to drop the 'unused' entries from uart_port, and 507allow low level drivers to register their own individual uart_port's with 508the core. This will allow drivers to use uart_port as a pointer to a 509structure containing both the uart_port entry with their own extensions, 510thus:: 511 512 struct my_port { 513 struct uart_port port; 514 int my_stuff; 515 }; 516 517Modem control lines via GPIO 518---------------------------- 519 520Some helpers are provided in order to set/get modem control lines via GPIO. 521 522mctrl_gpio_init(port, idx): 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 525 allocated structure. `devm_*` functions are used, so there's no need 526 to call mctrl_gpio_free(). 527 As this sets up the irq handling make sure to not handle changes to the 528 gpio input lines in your driver, too. 529 530mctrl_gpio_free(dev, gpios): 531 This will free the requested gpios in mctrl_gpio_init(). 532 As `devm_*` functions are used, there's generally no need to call 533 this function. 534 535mctrl_gpio_to_gpiod(gpios, gidx) 536 This returns the gpio_desc structure associated to the modem line 537 index. 538 539mctrl_gpio_set(gpios, mctrl): 540 This will sets the gpios according to the mctrl state. 541 542mctrl_gpio_get(gpios, mctrl): 543 This will update mctrl with the gpios values. 544 545mctrl_gpio_enable_ms(gpios): 546 Enables irqs and handling of changes to the ms lines. 547 548mctrl_gpio_disable_ms(gpios): 549 Disables irqs and handling of changes to the ms lines. 550