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 106