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 identifying
  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 struct 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 .. kernel-doc:: drivers/tty/serial/serial_core.c
  73    :identifiers: uart_update_timeout uart_get_baud_rate uart_get_divisor
  74            uart_match_port uart_write_wakeup uart_register_driver
  75            uart_unregister_driver uart_suspend_port uart_resume_port
  76            uart_add_one_port uart_remove_one_port uart_console_write
  77            uart_parse_earlycon uart_parse_options uart_set_options
  78            uart_get_lsr_info uart_handle_dcd_change uart_handle_cts_change
  79            uart_try_toggle_sysrq uart_get_console
  80
  81 .. kernel-doc:: include/linux/serial_core.h
  82    :identifiers: uart_port_tx_limited uart_port_tx
  83
  84 Other notes
  85 -----------
  86
  87 It is intended some day to drop the 'unused' entries from uart_port, and
  88 allow low level drivers to register their own individual uart_port's with
  89 the core.  This will allow drivers to use uart_port as a pointer to a
  90 structure containing both the uart_port entry with their own extensions,
  91 thus::
  92
  93         struct my_port {
  94                 struct uart_port        port;
  95                 int                     my_stuff;
  96         };
  97
  98 Modem control lines via GPIO
  99 ----------------------------
 100
 101 Some helpers are provided in order to set/get modem control lines via GPIO.
 102
 103 .. kernel-doc:: drivers/tty/serial/serial_mctrl_gpio.c
 104    :identifiers: mctrl_gpio_init mctrl_gpio_free mctrl_gpio_to_gpiod
 105            mctrl_gpio_set mctrl_gpio_get mctrl_gpio_enable_ms
 106            mctrl_gpio_disable_ms