Documentation/driver-api/serial/driver.rst

   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 .. kernel-doc:: include/linux/serial_core.h
  67    :identifiers: uart_ops
  68
  69 Other functions
  70 ---------------
  71
  72 uart_update_timeout(port,cflag,baud)
  73         Update the frame timing information according to the number of bits,
  74         parity, stop bits and baud rate. The FIFO drain timeout is derived
  75         from the frame timing information.
  76
  77         Locking: caller is expected to take port->lock
  78
  79         Interrupts: n/a
  80
  81 uart_get_baud_rate(port,termios,old,min,max)
  82         Return the numeric baud rate for the specified termios, taking
  83         account of the special 38400 baud "kludge".  The B0 baud rate
  84         is mapped to 9600 baud.
  85
  86         If the baud rate is not within min..max, then if old is non-NULL,
  87         the original baud rate will be tried.  If that exceeds the
  88         min..max constraint, 9600 baud will be returned.  termios will
  89         be updated to the baud rate in use.
  90
  91         Note: min..max must always allow 9600 baud to be selected.
  92
  93         Locking: caller dependent.
  94
  95         Interrupts: n/a
  96
  97 uart_get_divisor(port,baud)
  98         Return the divisor (baud_base / baud) for the specified baud
  99         rate, appropriately rounded.
 100
 101         If 38400 baud and custom divisor is selected, return the
 102         custom divisor instead.
 103
 104         Locking: caller dependent.
 105
 106         Interrupts: n/a
 107
 108 uart_match_port(port1,port2)
 109         This utility function can be used to determine whether two
 110         uart_port structures describe the same port.
 111
 112         Locking: n/a
 113
 114         Interrupts: n/a
 115
 116 uart_write_wakeup(port)
 117         A driver is expected to call this function when the number of
 118         characters in the transmit buffer have dropped below a threshold.
 119
 120         Locking: port->lock should be held.
 121
 122         Interrupts: n/a
 123
 124 uart_register_driver(drv)
 125         Register a uart driver with the core driver.  We in turn register
 126         with the tty layer, and initialise the core driver per-port state.
 127
 128         drv->port should be NULL, and the per-port structures should be
 129         registered using uart_add_one_port after this call has succeeded.
 130
 131         Locking: none
 132
 133         Interrupts: enabled
 134
 135 uart_unregister_driver()
 136         Remove all references to a driver from the core driver.  The low
 137         level driver must have removed all its ports via the
 138         uart_remove_one_port() if it registered them with uart_add_one_port().
 139
 140         Locking: none
 141
 142         Interrupts: enabled
 143
 144 **uart_suspend_port()**
 145
 146 **uart_resume_port()**
 147
 148 **uart_add_one_port()**
 149
 150 **uart_remove_one_port()**
 151
 152 Other notes
 153 -----------
 154
 155 It is intended some day to drop the 'unused' entries from uart_port, and
 156 allow low level drivers to register their own individual uart_port's with
 157 the core.  This will allow drivers to use uart_port as a pointer to a
 158 structure containing both the uart_port entry with their own extensions,
 159 thus::
 160
 161         struct my_port {
 162                 struct uart_port        port;
 163                 int                     my_stuff;
 164         };
 165
 166 Modem control lines via GPIO
 167 ----------------------------
 168
 169 Some helpers are provided in order to set/get modem control lines via GPIO.
 170
 171 mctrl_gpio_init(port, idx):
 172         This will get the {cts,rts,...}-gpios from device tree if they are
 173         present and request them, set direction etc, and return an
 174         allocated structure. `devm_*` functions are used, so there's no need
 175         to call mctrl_gpio_free().
 176         As this sets up the irq handling make sure to not handle changes to the
 177         gpio input lines in your driver, too.
 178
 179 mctrl_gpio_free(dev, gpios):
 180         This will free the requested gpios in mctrl_gpio_init().
 181         As `devm_*` functions are used, there's generally no need to call
 182         this function.
 183
 184 mctrl_gpio_to_gpiod(gpios, gidx)
 185         This returns the gpio_desc structure associated to the modem line
 186         index.
 187
 188 mctrl_gpio_set(gpios, mctrl):
 189         This will sets the gpios according to the mctrl state.
 190
 191 mctrl_gpio_get(gpios, mctrl):
 192         This will update mctrl with the gpios values.
 193
 194 mctrl_gpio_enable_ms(gpios):
 195         Enables irqs and handling of changes to the ms lines.
 196
 197 mctrl_gpio_disable_ms(gpios):
 198         Disables irqs and handling of changes to the ms lines.