| 1 | ====================
|
| 2 | Low Level Serial API
|
| 3 | ====================
|
| 4 |
|
| 5 |
|
| 6 | This document is meant as a brief overview of some aspects of the new serial
|
| 7 | driver. It is not complete, any questions you have should be directed to
|
| 8 | <[email protected]>
|
| 9 |
|
| 10 | The reference implementation is contained within amba-pl011.c.
|
| 11 |
|
| 12 |
|
| 13 |
|
| 14 | Low Level Serial Hardware Driver
|
| 15 | --------------------------------
|
| 16 |
|
| 17 | The low level serial hardware driver is responsible for supplying port
|
| 18 | information (defined by uart_port) and a set of control methods (defined
|
| 19 | by uart_ops) to the core serial driver. The low level driver is also
|
| 20 | responsible for handling interrupts for the port, and providing any
|
| 21 | console support.
|
| 22 |
|
| 23 |
|
| 24 | Console Support
|
| 25 | ---------------
|
| 26 |
|
| 27 | The serial core provides a few helper functions. This includes
|
| 28 | decoding command line arguments (uart_parse_options()).
|
| 29 |
|
| 30 | There is also a helper function (uart_console_write()) which performs a
|
| 31 | character by character write, translating newlines to CRLF sequences.
|
| 32 | Driver writers are recommended to use this function rather than implementing
|
| 33 | their own version.
|
| 34 |
|
| 35 |
|
| 36 | Locking
|
| 37 | -------
|
| 38 |
|
| 39 | It is the responsibility of the low level hardware driver to perform the
|
| 40 | necessary locking using port->lock. There are some exceptions (which
|
| 41 | are described in the struct uart_ops listing below.)
|
| 42 |
|
| 43 | There are two locks. A per-port spinlock, and an overall semaphore.
|
| 44 |
|
| 45 | From the core driver perspective, the port->lock locks the following
|
| 46 | data::
|
| 47 |
|
| 48 | port->mctrl
|
| 49 | port->icount
|
| 50 | port->state->xmit.head (circ_buf->head)
|
| 51 | port->state->xmit.tail (circ_buf->tail)
|
| 52 |
|
| 53 | The low level driver is free to use this lock to provide any additional
|
| 54 | locking.
|
| 55 |
|
| 56 | The port_sem semaphore is used to protect against ports being added/
|
| 57 | removed or reconfigured at inappropriate times. Since v2.6.27, this
|
| 58 | semaphore has been the 'mutex' member of the tty_port struct, and
|
| 59 | commonly referred to as the port mutex.
|
| 60 |
|
| 61 |
|
| 62 | uart_ops
|
| 63 | --------
|
| 64 |
|
| 65 | .. kernel-doc:: include/linux/serial_core.h
|
| 66 | :identifiers: uart_ops
|
| 67 |
|
| 68 | Other 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 |
|
| 83 | Other notes
|
| 84 | -----------
|
| 85 |
|
| 86 | It is intended some day to drop the 'unused' entries from uart_port, and
|
| 87 | allow low level drivers to register their own individual uart_port's with
|
| 88 | the core. This will allow drivers to use uart_port as a pointer to a
|
| 89 | structure containing both the uart_port entry with their own extensions,
|
| 90 | thus::
|
| 91 |
|
| 92 | struct my_port {
|
| 93 | struct uart_port port;
|
| 94 | int my_stuff;
|
| 95 | };
|
| 96 |
|
| 97 | Modem control lines via GPIO
|
| 98 | ----------------------------
|
| 99 |
|
| 100 | Some 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
|