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 identifying
28the correct port structure (via uart_get_console()) and decoding command line
29arguments (uart_parse_options()).
30
31There is also a helper function (uart_console_write()) which performs a
32character by character write, translating newlines to CRLF sequences.
33Driver writers are recommended to use this function rather than implementing
34their own version.
35
36
37Locking
38-------
39
40It is the responsibility of the low level hardware driver to perform the
41necessary locking using port->lock.  There are some exceptions (which
42are described in the struct uart_ops listing below.)
43
44There are two locks.  A per-port spinlock, and an overall semaphore.
45
46From the core driver perspective, the port->lock locks the following
47data::
48
49	port->mctrl
50	port->icount
51	port->state->xmit.head (circ_buf->head)
52	port->state->xmit.tail (circ_buf->tail)
53
54The low level driver is free to use this lock to provide any additional
55locking.
56
57The port_sem semaphore is used to protect against ports being added/
58removed or reconfigured at inappropriate times. Since v2.6.27, this
59semaphore has been the 'mutex' member of the tty_port struct, and
60commonly referred to as the port mutex.
61
62
63uart_ops
64--------
65
66.. kernel-doc:: include/linux/serial_core.h
67   :identifiers: uart_ops
68
69Other 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
84Other notes
85-----------
86
87It is intended some day to drop the 'unused' entries from uart_port, and
88allow low level drivers to register their own individual uart_port's with
89the core.  This will allow drivers to use uart_port as a pointer to a
90structure containing both the uart_port entry with their own extensions,
91thus::
92
93	struct my_port {
94		struct uart_port	port;
95		int			my_stuff;
96	};
97
98Modem control lines via GPIO
99----------------------------
100
101Some 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
107