Documentation/serial/driver

   1
   2                         Low Level Serial API
   3                         --------------------
   4
   5
   6    $Id: driver,v 1.10 2002/07/22 15:27:30 rmk Exp $
   7
   8
   9 This document is meant as a brief overview of some aspects of the new serial
  10 driver.  It is not complete, any questions you have should be directed to
  11 <rmk@arm.linux.org.uk>
  12
  13 The reference implementation is contained within serial_amba.c.
  14
  15
  16
  17 Low Level Serial Hardware Driver
  18 --------------------------------
  19
  20 The low level serial hardware driver is responsible for supplying port
  21 information (defined by uart_port) and a set of control methods (defined
  22 by uart_ops) to the core serial driver.  The low level driver is also
  23 responsible for handling interrupts for the port, and providing any
  24 console support.
  25
  26
  27 Console Support
  28 ---------------
  29
  30 The serial core provides a few helper functions.  This includes identifing
  31 the correct port structure (via uart_get_console) and decoding command line
  32 arguments (uart_parse_options).
  33
  34
  35 Locking
  36 -------
  37
  38 It is the responsibility of the low level hardware driver to perform the
  39 necessary locking using port->lock.  There are some exceptions (which
  40 are described in the uart_ops listing below.)
  41
  42 There are three locks.  A per-port spinlock, a per-port tmpbuf semaphore,
  43 and an overall semaphore.
  44
  45 From the core driver perspective, the port->lock locks the following
  46 data:
  47
  48         port->mctrl
  49         port->icount
  50         info->xmit.head (circ->head)
  51         info->xmit.tail (circ->tail)
  52
  53 The low level driver is free to use this lock to provide any additional
  54 locking.
  55
  56 The core driver uses the info->tmpbuf_sem lock to prevent multi-threaded
  57 access to the info->tmpbuf bouncebuffer used for port writes.
  58
  59 The port_sem semaphore is used to protect against ports being added/
  60 removed or reconfigured at inappropriate times.
  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         If the appropriate bit is set, the signal should be driven
  90         active.  If the bit is clear, the signal should be driven
  91         inactive.
  92
  93         Locking: port->lock taken.
  94         Interrupts: locally disabled.
  95         This call must not sleep
  96
  97   get_mctrl(port)
  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_DCD     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.
 109
 110         Locking: port->lock taken.
 111         Interrupts: locally disabled.
 112         This call must not sleep
 113
 114   stop_tx(port)
 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.
 118
 119         The driver should stop transmitting characters as soon as
 120         possible.
 121
 122         Locking: port->lock taken.
 123         Interrupts: locally disabled.
 124         This call must not sleep
 125
 126   start_tx(port)
 127         Start transmitting characters.
 128
 129         Locking: port->lock taken.
 130         Interrupts: locally disabled.
 131         This call must not sleep
 132
 133   stop_rx(port)
 134         Stop receiving characters; the port is in the process of
 135         being closed.
 136
 137         Locking: port->lock taken.
 138         Interrupts: locally disabled.
 139         This call must not sleep
 140
 141   enable_ms(port)
 142         Enable the modem status interrupts.
 143
 144         Locking: port->lock taken.
 145         Interrupts: locally disabled.
 146         This call must not sleep
 147
 148   break_ctl(port,ctl)
 149         Control the transmission of a break signal.  If ctl is
 150         nonzero, the break signal should be transmitted.  The signal
 151         should be terminated when another call is made with a zero
 152         ctl.
 153
 154         Locking: none.
 155         Interrupts: caller dependent.
 156         This call must not sleep
 157
 158   startup(port)
 159         Grab any interrupt resources and initialise any low level driver
 160         state.  Enable the port for reception.  It should not activate
 161         RTS nor DTR; this will be done via a separate call to set_mctrl.
 162
 163         Locking: port_sem taken.
 164         Interrupts: globally disabled.
 165
 166   shutdown(port)
 167         Disable the port, disable any break condition that may be in
 168         effect, and free any interrupt resources.  It should not disable
 169         RTS nor DTR; this will have already been done via a separate
 170         call to set_mctrl.
 171
 172         Locking: port_sem taken.
 173         Interrupts: caller dependent.
 174
 175   set_termios(port,termios,oldtermios)
 176         Change the port parameters, including word length, parity, stop
 177         bits.  Update read_status_mask and ignore_status_mask to indicate
 178         the types of events we are interested in receiving.  Relevant
 179         termios->c_cflag bits are:
 180                 CSIZE   - word size
 181                 CSTOPB  - 2 stop bits
 182                 PARENB  - parity enable
 183                 PARODD  - odd parity (when PARENB is in force)
 184                 CREAD   - enable reception of characters (if not set,
 185                           still receive characters from the port, but
 186                           throw them away.
 187                 CRTSCTS - if set, enable CTS status change reporting
 188                 CLOCAL  - if not set, enable modem status change
 189                           reporting.
 190         Relevant termios->c_iflag bits are:
 191                 INPCK   - enable frame and parity error events to be
 192                           passed to the TTY layer.
 193                 BRKINT
 194                 PARMRK  - both of these enable break events to be
 195                           passed to the TTY layer.
 196
 197                 IGNPAR  - ignore parity and framing errors
 198                 IGNBRK  - ignore break errors,  If IGNPAR is also
 199                           set, ignore overrun errors as well.
 200         The interaction of the iflag bits is as follows (parity error
 201         given as an example):
 202         Parity error    INPCK   IGNPAR
 203         None            n/a     n/a     character received
 204         Yes             n/a     0       character discarded
 205         Yes             0       1       character received, marked as
 206                                         TTY_NORMAL
 207         Yes             1       1       character received, marked as
 208                                         TTY_PARITY
 209
 210         Other flags may be used (eg, xon/xoff characters) if your
 211         hardware supports hardware "soft" flow control.
 212
 213         Locking: none.
 214         Interrupts: caller dependent.
 215         This call must not sleep
 216
 217   pm(port,state,oldstate)
 218         Perform any power management related activities on the specified
 219         port.  State indicates the new state (defined by ACPI D0-D3),
 220         oldstate indicates the previous state.  Essentially, D0 means
 221         fully on, D3 means powered down.
 222
 223         This function should not be used to grab any resources.
 224
 225         This will be called when the port is initially opened and finally
 226         closed, except when the port is also the system console.  This
 227         will occur even if CONFIG_PM is not set.
 228
 229         Locking: none.
 230         Interrupts: caller dependent.
 231
 232   type(port)
 233         Return a pointer to a string constant describing the specified
 234         port, or return NULL, in which case the string 'unknown' is
 235         substituted.
 236
 237         Locking: none.
 238         Interrupts: caller dependent.
 239
 240   release_port(port)
 241         Release any memory and IO region resources currently in use by
 242         the port.
 243
 244         Locking: none.
 245         Interrupts: caller dependent.
 246
 247   request_port(port)
 248         Request any memory and IO region resources required by the port.
 249         If any fail, no resources should be registered when this function
 250         returns, and it should return -EBUSY on failure.
 251
 252         Locking: none.
 253         Interrupts: caller dependent.
 254
 255   config_port(port,type)
 256         Perform any autoconfiguration steps required for the port.  `type`
 257         contains a bit mask of the required configuration.  UART_CONFIG_TYPE
 258         indicates that the port requires detection and identification.
 259         port->type should be set to the type found, or PORT_UNKNOWN if
 260         no port was detected.
 261
 262         UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal,
 263         which should be probed using standard kernel autoprobing techniques.
 264         This is not necessary on platforms where ports have interrupts
 265         internally hard wired (eg, system on a chip implementations).
 266
 267         Locking: none.
 268         Interrupts: caller dependent.
 269
 270   verify_port(port,serinfo)
 271         Verify the new serial port information contained within serinfo is
 272         suitable for this port type.
 273
 274         Locking: none.
 275         Interrupts: caller dependent.
 276
 277   ioctl(port,cmd,arg)
 278         Perform any port specific IOCTLs.  IOCTL commands must be defined
 279         using the standard numbering system found in <asm/ioctl.h>
 280
 281         Locking: none.
 282         Interrupts: caller dependent.
 283
 284 Other functions
 285 ---------------
 286
 287 uart_update_timeout(port,cflag,baud)
 288         Update the FIFO drain timeout, port->timeout, according to the
 289         number of bits, parity, stop bits and baud rate.
 290
 291         Locking: caller is expected to take port->lock
 292         Interrupts: n/a
 293
 294 uart_get_baud_rate(port,termios,old,min,max)
 295         Return the numeric baud rate for the specified termios, taking
 296         account of the special 38400 baud "kludge".  The B0 baud rate
 297         is mapped to 9600 baud.
 298
 299         If the baud rate is not within min..max, then if old is non-NULL,
 300         the original baud rate will be tried.  If that exceeds the
 301         min..max constraint, 9600 baud will be returned.  termios will
 302         be updated to the baud rate in use.
 303
 304         Note: min..max must always allow 9600 baud to be selected.
 305
 306         Locking: caller dependent.
 307         Interrupts: n/a
 308
 309 uart_get_divisor(port,baud)
 310         Return the divsor (baud_base / baud) for the specified baud
 311         rate, appropriately rounded.
 312
 313         If 38400 baud and custom divisor is selected, return the
 314         custom divisor instead.
 315
 316         Locking: caller dependent.
 317         Interrupts: n/a
 318
 319 uart_match_port(port1,port2)
 320         This utility function can be used to determine whether two
 321         uart_port structures describe the same port.
 322
 323         Locking: n/a
 324         Interrupts: n/a
 325
 326 uart_write_wakeup(port)
 327         A driver is expected to call this function when the number of
 328         characters in the transmit buffer have dropped below a threshold.
 329
 330         Locking: port->lock should be held.
 331         Interrupts: n/a
 332
 333 uart_register_driver(drv)
 334         Register a uart driver with the core driver.  We in turn register
 335         with the tty layer, and initialise the core driver per-port state.
 336
 337         drv->port should be NULL, and the per-port structures should be
 338         registered using uart_add_one_port after this call has succeeded.
 339
 340         Locking: none
 341         Interrupts: enabled
 342
 343 uart_unregister_driver()
 344         Remove all references to a driver from the core driver.  The low
 345         level driver must have removed all its ports via the
 346         uart_remove_one_port() if it registered them with uart_add_one_port().
 347
 348         Locking: none
 349         Interrupts: enabled
 350
 351 uart_suspend_port()
 352
 353 uart_resume_port()
 354
 355 uart_add_one_port()
 356
 357 uart_remove_one_port()
 358
 359 Other notes
 360 -----------
 361
 362 It is intended some day to drop the 'unused' entries from uart_port, and
 363 allow low level drivers to register their own individual uart_port's with
 364 the core.  This will allow drivers to use uart_port as a pointer to a
 365 structure containing both the uart_port entry with their own extensions,
 366 thus:
 367
 368         struct my_port {
 369                 struct uart_port        port;
 370                 int                     my_stuff;
 371         };