1 2 Low 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_write_console) 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 three locks. A per-port spinlock, a per-port tmpbuf semaphore, 45and an overall semaphore. 46 47From the core driver perspective, the port->lock locks the following 48data: 49 50 port->mctrl 51 port->icount 52 info->xmit.head (circ->head) 53 info->xmit.tail (circ->tail) 54 55The low level driver is free to use this lock to provide any additional 56locking. 57 58The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded 59access to the info->tmpbuf bouncebuffer used for port writes. 60 61The port_sem semaphore is used to protect against ports being added/ 62removed or reconfigured at inappropriate times. 63 64 65uart_ops 66-------- 67 68The uart_ops structure is the main interface between serial_core and the 69hardware specific driver. It contains all the methods to control the 70hardware. 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 310Other functions 311--------------- 312 313uart_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 320uart_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 335uart_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 345uart_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 352uart_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 359uart_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 369uart_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 377uart_suspend_port() 378 379uart_resume_port() 380 381uart_add_one_port() 382 383uart_remove_one_port() 384 385Other notes 386----------- 387 388It is intended some day to drop the 'unused' entries from uart_port, and 389allow low level drivers to register their own individual uart_port's with 390the core. This will allow drivers to use uart_port as a pointer to a 391structure containing both the uart_port entry with their own extensions, 392thus: 393 394 struct my_port { 395 struct uart_port port; 396 int my_stuff; 397 }; 398