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         Locking: port->lock taken.
 120         Interrupts: locally disabled.
 121         This call must not sleep
 122
 123   start_tx(port)
 124         start transmitting characters.
 125
 126         Locking: port->lock taken.
 127         Interrupts: locally disabled.
 128         This call must not sleep
 129
 130   stop_rx(port)
 131         Stop receiving characters; the port is in the process of
 132         being closed.
 133
 134         Locking: port->lock taken.
 135         Interrupts: locally disabled.
 136         This call must not sleep
 137
 138   enable_ms(port)
 139         Enable the modem status interrupts.
 140
 141         Locking: port->lock taken.
 142         Interrupts: locally disabled.
 143         This call must not sleep
 144
 145   break_ctl(port,ctl)
 146         Control the transmission of a break signal.  If ctl is
 147         nonzero, the break signal should be transmitted.  The signal
 148         should be terminated when another call is made with a zero
 149         ctl.
 150
 151         Locking: none.
 152         Interrupts: caller dependent.
 153         This call must not sleep
 154
 155   startup(port)
 156         Grab any interrupt resources and initialise any low level driver
 157         state.  Enable the port for reception.  It should not activate
 158         RTS nor DTR; this will be done via a separate call to set_mctrl.
 159
 160         Locking: port_sem taken.
 161         Interrupts: globally disabled.
 162
 163   shutdown(port)
 164         Disable the port, disable any break condition that may be in
 165         effect, and free any interrupt resources.  It should not disable
 166         RTS nor DTR; this will have already been done via a separate
 167         call to set_mctrl.
 168
 169         Locking: port_sem taken.
 170         Interrupts: caller dependent.
 171
 172   set_termios(port,termios,oldtermios)
 173         Change the port parameters, including word length, parity, stop
 174         bits.  Update read_status_mask and ignore_status_mask to indicate
 175         the types of events we are interested in receiving.  Relevant
 176         termios->c_cflag bits are:
 177                 CSIZE   - word size
 178                 CSTOPB  - 2 stop bits
 179                 PARENB  - parity enable
 180                 PARODD  - odd parity (when PARENB is in force)
 181                 CREAD   - enable reception of characters (if not set,
 182                           still receive characters from the port, but
 183                           throw them away.
 184                 CRTSCTS - if set, enable CTS status change reporting
 185                 CLOCAL  - if not set, enable modem status change
 186                           reporting.
 187         Relevant termios->c_iflag bits are:
 188                 INPCK   - enable frame and parity error events to be
 189                           passed to the TTY layer.
 190                 BRKINT
 191                 PARMRK  - both of these enable break events to be
 192                           passed to the TTY layer.
 193
 194                 IGNPAR  - ignore parity and framing errors
 195                 IGNBRK  - ignore break errors,  If IGNPAR is also
 196                           set, ignore overrun errors as well.
 197         The interaction of the iflag bits is as follows (parity error
 198         given as an example):
 199         Parity error    INPCK   IGNPAR
 200         None            n/a     n/a     character received
 201         Yes             n/a     0       character discarded
 202         Yes             0       1       character received, marked as
 203                                         TTY_NORMAL
 204         Yes             1       1       character received, marked as
 205                                         TTY_PARITY
 206
 207         Other flags may be used (eg, xon/xoff characters) if your
 208         hardware supports hardware "soft" flow control.
 209
 210         Locking: none.
 211         Interrupts: caller dependent.
 212         This call must not sleep
 213
 214   pm(port,state,oldstate)
 215         Perform any power management related activities on the specified
 216         port.  State indicates the new state (defined by ACPI D0-D3),
 217         oldstate indicates the previous state.  Essentially, D0 means
 218         fully on, D3 means powered down.
 219
 220         This function should not be used to grab any resources.
 221
 222         This will be called when the port is initially opened and finally
 223         closed, except when the port is also the system console.  This
 224         will occur even if CONFIG_PM is not set.
 225
 226         Locking: none.
 227         Interrupts: caller dependent.
 228
 229   type(port)
 230         Return a pointer to a string constant describing the specified
 231         port, or return NULL, in which case the string 'unknown' is
 232         substituted.
 233
 234         Locking: none.
 235         Interrupts: caller dependent.
 236
 237   release_port(port)
 238         Release any memory and IO region resources currently in use by
 239         the port.
 240
 241         Locking: none.
 242         Interrupts: caller dependent.
 243
 244   request_port(port)
 245         Request any memory and IO region resources required by the port.
 246         If any fail, no resources should be registered when this function
 247         returns, and it should return -EBUSY on failure.
 248
 249         Locking: none.
 250         Interrupts: caller dependent.
 251
 252   config_port(port,type)
 253         Perform any autoconfiguration steps required for the port.  `type`
 254         contains a bit mask of the required configuration.  UART_CONFIG_TYPE
 255         indicates that the port requires detection and identification.
 256         port->type should be set to the type found, or PORT_UNKNOWN if
 257         no port was detected.
 258
 259         UART_CONFIG_IRQ indicates autoconfiguration of the interrupt signal,
 260         which should be probed using standard kernel autoprobing techniques.
 261         This is not necessary on platforms where ports have interrupts
 262         internally hard wired (eg, system on a chip implementations).
 263
 264         Locking: none.
 265         Interrupts: caller dependent.
 266
 267   verify_port(port,serinfo)
 268         Verify the new serial port information contained within serinfo is
 269         suitable for this port type.
 270
 271         Locking: none.
 272         Interrupts: caller dependent.
 273
 274   ioctl(port,cmd,arg)
 275         Perform any port specific IOCTLs.  IOCTL commands must be defined
 276         using the standard numbering system found in <asm/ioctl.h>
 277
 278         Locking: none.
 279         Interrupts: caller dependent.
 280
 281 Other functions
 282 ---------------
 283
 284 uart_update_timeout(port,cflag,quot)
 285         Update the FIFO drain timeout, port->timeout, according to the
 286         number of bits, parity, stop bits and quotient.
 287
 288         Locking: caller is expected to take port->lock
 289         Interrupts: n/a
 290
 291 uart_get_baud_rate(port,termios)
 292         Return the numeric baud rate for the specified termios, taking
 293         account of the special 38400 baud "kludge".  The B0 baud rate
 294         is mapped to 9600 baud.
 295
 296         Locking: caller dependent.
 297         Interrupts: n/a
 298
 299 uart_get_divisor(port,termios,oldtermios)
 300         Return the divsor (baud_base / baud) for the selected baud rate
 301         specified by termios.  If the baud rate is out of range, try
 302         the original baud rate specified by oldtermios (if non-NULL).
 303         If that fails, try 9600 baud.
 304
 305         If 38400 baud and custom divisor is selected, return the
 306         custom divisor instead.
 307
 308         Locking: caller dependent.
 309         Interrupts: n/a
 310
 311 Other notes
 312 -----------
 313
 314 It is intended some day to drop the 'unused' entries from uart_port, and
 315 allow low level drivers to register their own individual uart_port's with
 316 the core.  This will allow drivers to use uart_port as a pointer to a
 317 structure containing both the uart_port entry with their own extensions,
 318 thus:
 319
 320         struct my_port {
 321                 struct uart_port        port;
 322                 int                     my_stuff;
 323         };