driver.rst

  1====================
  2Low 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
 28decoding command line arguments (uart_parse_options()).
 29
 30There is also a helper function (uart_console_write()) which performs a
 31character by character write, translating newlines to CRLF sequences.
 32Driver writers are recommended to use this function rather than implementing
 33their own version.
 34
 35
 36Locking
 37-------
 38
 39It is the responsibility of the low level hardware driver to perform the
 40necessary locking using port->lock.  There are some exceptions (which
 41are described in the struct uart_ops listing below.)
 42
 43There are two locks.  A per-port spinlock, and an overall semaphore.
 44
 45From the core driver perspective, the port->lock locks the following
 46data::
 47
 48	port->mctrl
 49	port->icount
 50	port->state->xmit.head (circ_buf->head)
 51	port->state->xmit.tail (circ_buf->tail)
 52
 53The low level driver is free to use this lock to provide any additional
 54locking.
 55
 56The port_sem semaphore is used to protect against ports being added/
 57removed or reconfigured at inappropriate times. Since v2.6.27, this
 58semaphore has been the 'mutex' member of the tty_port struct, and
 59commonly referred to as the port mutex.
 60
 61
 62uart_ops
 63--------
 64
 65.. kernel-doc:: include/linux/serial_core.h
 66   :identifiers: uart_ops
 67
 68Other functions
 69---------------
 70
 71.. kernel-doc:: drivers/tty/serial/serial_core.c
 72   :identifiers: uart_update_timeout uart_get_baud_rate uart_get_divisor
 73           uart_match_port uart_write_wakeup uart_register_driver
 74           uart_unregister_driver uart_suspend_port uart_resume_port
 75           uart_add_one_port uart_remove_one_port uart_console_write
 76           uart_parse_earlycon uart_parse_options uart_set_options
 77           uart_get_lsr_info uart_handle_dcd_change uart_handle_cts_change
 78           uart_try_toggle_sysrq
 79
 80.. kernel-doc:: include/linux/serial_core.h
 81   :identifiers: uart_port_tx_limited uart_port_tx
 82
 83Other notes
 84-----------
 85
 86It is intended some day to drop the 'unused' entries from uart_port, and
 87allow low level drivers to register their own individual uart_port's with
 88the core.  This will allow drivers to use uart_port as a pointer to a
 89structure containing both the uart_port entry with their own extensions,
 90thus::
 91
 92	struct my_port {
 93		struct uart_port	port;
 94		int			my_stuff;
 95	};
 96
 97Modem control lines via GPIO
 98----------------------------
 99
100Some helpers are provided in order to set/get modem control lines via GPIO.
101
102.. kernel-doc:: drivers/tty/serial/serial_mctrl_gpio.c
103   :identifiers: mctrl_gpio_init mctrl_gpio_to_gpiod
104           mctrl_gpio_set mctrl_gpio_get mctrl_gpio_enable_ms
105           mctrl_gpio_disable_ms_sync mctrl_gpio_disable_ms_no_sync