107 lines · plain
1====================2Low Level Serial API3====================4 5 6This document is meant as a brief overview of some aspects of the new serial7driver. It is not complete, any questions you have should be directed to8<rmk@arm.linux.org.uk>9 10The reference implementation is contained within amba-pl011.c.11 12 13 14Low Level Serial Hardware Driver15--------------------------------16 17The low level serial hardware driver is responsible for supplying port18information (defined by uart_port) and a set of control methods (defined19by uart_ops) to the core serial driver. The low level driver is also20responsible for handling interrupts for the port, and providing any21console support.22 23 24Console Support25---------------26 27The serial core provides a few helper functions. This includes identifying28the correct port structure (via uart_get_console()) and decoding command line29arguments (uart_parse_options()).30 31There is also a helper function (uart_console_write()) which performs a32character by character write, translating newlines to CRLF sequences.33Driver writers are recommended to use this function rather than implementing34their own version.35 36 37Locking38-------39 40It is the responsibility of the low level hardware driver to perform the41necessary locking using port->lock. There are some exceptions (which42are 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 following47data::48 49 port->mctrl50 port->icount51 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 additional55locking.56 57The port_sem semaphore is used to protect against ports being added/58removed or reconfigured at inappropriate times. Since v2.6.27, this59semaphore has been the 'mutex' member of the tty_port struct, and60commonly referred to as the port mutex.61 62 63uart_ops64--------65 66.. kernel-doc:: include/linux/serial_core.h67 :identifiers: uart_ops68 69Other functions70---------------71 72.. kernel-doc:: drivers/tty/serial/serial_core.c73 :identifiers: uart_update_timeout uart_get_baud_rate uart_get_divisor74 uart_match_port uart_write_wakeup uart_register_driver75 uart_unregister_driver uart_suspend_port uart_resume_port76 uart_add_one_port uart_remove_one_port uart_console_write77 uart_parse_earlycon uart_parse_options uart_set_options78 uart_get_lsr_info uart_handle_dcd_change uart_handle_cts_change79 uart_try_toggle_sysrq uart_get_console80 81.. kernel-doc:: include/linux/serial_core.h82 :identifiers: uart_port_tx_limited uart_port_tx83 84Other notes85-----------86 87It is intended some day to drop the 'unused' entries from uart_port, and88allow low level drivers to register their own individual uart_port's with89the core. This will allow drivers to use uart_port as a pointer to a90structure 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 GPIO99----------------------------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.c104 :identifiers: mctrl_gpio_init mctrl_gpio_free mctrl_gpio_to_gpiod105 mctrl_gpio_set mctrl_gpio_get mctrl_gpio_enable_ms106 mctrl_gpio_disable_ms107