0001 ====================
0002 Low Level Serial API
0003 ====================
0004
0005
0006 This document is meant as a brief overview of some aspects of the new serial
0007 driver. It is not complete, any questions you have should be directed to
0008 <rmk@arm.linux.org.uk>
0009
0010 The reference implementation is contained within amba-pl011.c.
0011
0012
0013
0014 Low Level Serial Hardware Driver
0015 --------------------------------
0016
0017 The low level serial hardware driver is responsible for supplying port
0018 information (defined by uart_port) and a set of control methods (defined
0019 by uart_ops) to the core serial driver. The low level driver is also
0020 responsible for handling interrupts for the port, and providing any
0021 console support.
0022
0023
0024 Console Support
0025 ---------------
0026
0027 The serial core provides a few helper functions. This includes identifing
0028 the correct port structure (via uart_get_console()) and decoding command line
0029 arguments (uart_parse_options()).
0030
0031 There is also a helper function (uart_console_write()) which performs a
0032 character by character write, translating newlines to CRLF sequences.
0033 Driver writers are recommended to use this function rather than implementing
0034 their own version.
0035
0036
0037 Locking
0038 -------
0039
0040 It is the responsibility of the low level hardware driver to perform the
0041 necessary locking using port->lock. There are some exceptions (which
0042 are described in the struct uart_ops listing below.)
0043
0044 There are two locks. A per-port spinlock, and an overall semaphore.
0045
0046 From the core driver perspective, the port->lock locks the following
0047 data::
0048
0049 port->mctrl
0050 port->icount
0051 port->state->xmit.head (circ_buf->head)
0052 port->state->xmit.tail (circ_buf->tail)
0053
0054 The low level driver is free to use this lock to provide any additional
0055 locking.
0056
0057 The port_sem semaphore is used to protect against ports being added/
0058 removed or reconfigured at inappropriate times. Since v2.6.27, this
0059 semaphore has been the 'mutex' member of the tty_port struct, and
0060 commonly referred to as the port mutex.
0061
0062
0063 uart_ops
0064 --------
0065
0066 .. kernel-doc:: include/linux/serial_core.h
0067 :identifiers: uart_ops
0068
0069 Other functions
0070 ---------------
0071
0072 .. kernel-doc:: drivers/tty/serial/serial_core.c
0073 :identifiers: uart_update_timeout uart_get_baud_rate uart_get_divisor
0074 uart_match_port uart_write_wakeup uart_register_driver
0075 uart_unregister_driver uart_suspend_port uart_resume_port
0076 uart_add_one_port uart_remove_one_port uart_console_write
0077 uart_parse_earlycon uart_parse_options uart_set_options
0078 uart_get_lsr_info uart_handle_dcd_change uart_handle_cts_change
0079 uart_try_toggle_sysrq uart_get_console
0080
0081 Other notes
0082 -----------
0083
0084 It is intended some day to drop the 'unused' entries from uart_port, and
0085 allow low level drivers to register their own individual uart_port's with
0086 the core. This will allow drivers to use uart_port as a pointer to a
0087 structure containing both the uart_port entry with their own extensions,
0088 thus::
0089
0090 struct my_port {
0091 struct uart_port port;
0092 int my_stuff;
0093 };
0094
0095 Modem control lines via GPIO
0096 ----------------------------
0097
0098 Some helpers are provided in order to set/get modem control lines via GPIO.
0099
0100 .. kernel-doc:: drivers/tty/serial/serial_mctrl_gpio.c
0101 :identifiers: mctrl_gpio_init mctrl_gpio_free mctrl_gpio_to_gpiod
0102 mctrl_gpio_set mctrl_gpio_get mctrl_gpio_enable_ms
0103 mctrl_gpio_disable_ms
