요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
====================
Low Level Serial API
====================
This document is meant as a brief overview of some aspects of the new serial
driver. It is not complete, any questions you have should be directed to
The reference implementation is contained within amba-pl011.c.
Low Level Serial Hardware Driver
--------------------------------
The low level serial hardware driver is responsible for supplying port
information (defined by uart_port) and a set of control methods (defined
by uart_ops) to the core serial driver. The low level driver is also
responsible for handling interrupts for the port, and providing any
console support.
Console Support
---------------
The serial core provides a few helper functions. This includes
decoding command line arguments (uart_parse_options()).
There is also a helper function (uart_console_write()) which performs a
character by character write, translating newlines to CRLF sequences.
Driver writers are recommended to use this function rather than implementing
their own version.
Locking
-------
It is the responsibility of the low level hardware driver to perform the
necessary locking using port->lock. There are some exceptions (which
are described in the struct uart_ops listing below.)
There are two locks. A per-port spinlock, and an overall semaphore.
From the core driver perspective, the port->lock locks the following
data::
port->mctrl
port->icount
port->state->xmit.head (circ_buf->head)
port->state->xmit.tail (circ_buf->tail)
The low level driver is free to use this lock to provide any additional
locking.
The port_sem semaphore is used to protect against ports being added/
removed or reconfigured at inappropriate times. Since v2.6.27, this
semaphore has been the 'mutex' member of the tty_port struct, and
commonly referred to as the port mutex.
uart_ops
--------
.. kernel-doc:: include/linux/serial_core.h
:identifiers: uart_ops
Other functions
---------------
.. kernel-doc:: drivers/tty/serial/serial_core.c
:identifiers: uart_update_timeout uart_get_baud_rate uart_get_divisor
uart_match_port uart_write_wakeup uart_register_driver
uart_unregister_driver uart_suspend_port uart_resume_port
uart_add_one_port uart_remove_one_port uart_console_write
uart_parse_earlycon uart_parse_options uart_set_options
uart_get_lsr_info uart_handle_dcd_change uart_handle_cts_change
uart_try_toggle_sysrq
.. kernel-doc:: include/linux/serial_core.h
:identifiers: uart_port_tx_limited uart_port_tx
Other notes
-----------
It is intended some day to drop the 'unused' entries from uart_port, and
allow low level drivers to register their own individual uart_port's with
the core. This will allow drivers to use uart_port as a pointer to a
structure containing both the uart_port entry with their own extensions,
thus::
struct my_port {
struct uart_port port;
int my_stuff;
};
Modem control lines via GPIO
----------------------------
Some helpers are provided in order to set/get modem control lines via GPIO.
.. kernel-doc:: drivers/tty/serial/serial_mctrl_gpio.c
:identifiers: mctrl_gpio_init mctrl_gpio_to_gpiod
mctrl_gpio_set mctrl_gpio_get mctrl_gpio_enable_ms
mctrl_gpio_disable_ms_sync mctrl_gpio_disable_ms_no_sync
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Low Level Serial API 문서 범위
1-13이 문서는 새로운 serial driver의 일부 측면을 간략히 개관합니다. 완전한 문서가 아니며 질문은 `[email protected]`로 보내야 합니다.
Reference implementation은 `amba-pl011.c`에 들어 있습니다.
====================
Low Level Serial API
====================
This document is meant as a brief overview of some aspects of the new serial
driver. It is not complete, any questions you have should be directed to
<[email protected]>
The reference implementation is contained within amba-pl011.c.
Low-level serial hardware driver 책임
14-23Low-level serial hardware driver는 `uart_port`로 정의되는 port 정보와 `uart_ops`로 정의되는 control method 집합을 core serial driver에 제공해야 합니다.
Low-level driver는 해당 port의 interrupt를 처리하고 필요한 console support도 제공할 책임이 있습니다.
Hardware driver가 port state와 operation callback을 serial core에 제공하고 interrupt·console 경로를 담당합니다.
Low Level Serial Hardware Driver
--------------------------------
The low level serial hardware driver is responsible for supplying port
information (defined by uart_port) and a set of control methods (defined
by uart_ops) to the core serial driver. The low level driver is also
responsible for handling interrupts for the port, and providing any
console support.
Console helper
24-35Serial core는 command-line argument를 decode하는 `uart_parse_options()`를 비롯한 여러 helper function을 제공합니다.
`uart_console_write()`는 character 단위 write를 수행하고 newline을 CRLF sequence로 변환합니다. Driver 작성자는 자체 구현 대신 이 function을 사용하는 것이 권장됩니다.
Core helper가 option parsing과 newline 변환을 공통 구현으로 제공합니다.
Console Support
---------------
The serial core provides a few helper functions. This includes
decoding command line arguments (uart_parse_options()).
There is also a helper function (uart_console_write()) which performs a
character by character write, translating newlines to CRLF sequences.
Driver writers are recommended to use this function rather than implementing
their own version.
Per-port spinlock과 port mutex
36-61필요한 locking을 `port->lock`으로 수행하는 것은 low-level hardware driver의 책임입니다. 다만 아래 `struct uart_ops` 목록에 설명된 일부 예외가 있습니다.
Lock은 per-port spinlock과 전체 semaphore 두 종류입니다. Core driver 관점에서 `port->lock`은 `port->mctrl`, `port->icount`, transmit circular buffer의 `head`와 `tail`을 보호합니다. Low-level driver는 추가 data를 보호하는 데도 이 lock을 사용할 수 있습니다.
`port_sem` semaphore는 부적절한 시점에 port를 add·remove·reconfigure하지 못하게 보호합니다. Linux v2.6.27부터 이 semaphore는 `tty_port` structure의 `mutex` member이며 보통 port mutex라고 부릅니다.
Per-port spinlock은 fast state를, port mutex는 구조 변경 lifecycle을 직렬화합니다.
Locking
-------
It is the responsibility of the low level hardware driver to perform the
necessary locking using port->lock. There are some exceptions (which
are described in the struct uart_ops listing below.)
There are two locks. A per-port spinlock, and an overall semaphore.
From the core driver perspective, the port->lock locks the following
data::
port->mctrl
port->icount
port->state->xmit.head (circ_buf->head)
port->state->xmit.tail (circ_buf->tail)
The low level driver is free to use this lock to provide any additional
locking.
The port_sem semaphore is used to protect against ports being added/
removed or reconfigured at inappropriate times. Since v2.6.27, this
semaphore has been the 'mutex' member of the tty_port struct, and
commonly referred to as the port mutex.
uart_ops callback
62-67Low-level serial control method 집합인 `uart_ops`는 `include/linux/serial_core.h`의 kernel-doc identifier로 문서화됩니다.
uart_ops
--------
.. kernel-doc:: include/linux/serial_core.h
:identifiers: uart_ops
Serial core와 TX helper
68-82`drivers/tty/serial/serial_core.c`에서 timeout·baud rate·divisor 계산, port matching, write wakeup, driver 등록·해제, port suspend·resume·add·remove, console write와 option parsing, line status, DCD·CTS change, SysRq toggle 관련 function을 kernel-doc으로 가져옵니다.
`include/linux/serial_core.h`에서는 제한된 TX와 일반 TX helper인 `uart_port_tx_limited`, `uart_port_tx`를 가져옵니다.
Other functions
---------------
.. kernel-doc:: drivers/tty/serial/serial_core.c
:identifiers: uart_update_timeout uart_get_baud_rate uart_get_divisor
uart_match_port uart_write_wakeup uart_register_driver
uart_unregister_driver uart_suspend_port uart_resume_port
uart_add_one_port uart_remove_one_port uart_console_write
uart_parse_earlycon uart_parse_options uart_set_options
uart_get_lsr_info uart_handle_dcd_change uart_handle_cts_change
uart_try_toggle_sysrq
.. kernel-doc:: include/linux/serial_core.h
:identifiers: uart_port_tx_limited uart_port_tx
uart_port 확장 구조
83-96향후 `uart_port`의 unused entry를 제거하고 low-level driver가 개별 `uart_port`를 core에 직접 등록할 수 있게 하는 것이 의도되어 있습니다.
그러면 driver는 `uart_port` entry와 자체 extension을 함께 담는 구조체를 정의하고, 그 구조체를 가리키는 pointer로 `uart_port`를 사용할 수 있습니다.
Common structure를 첫 member로 포함해 core contract와 driver-private state를 한 allocation에 둡니다.
Other notes
-----------
It is intended some day to drop the 'unused' entries from uart_port, and
allow low level drivers to register their own individual uart_port's with
the core. This will allow drivers to use uart_port as a pointer to a
structure containing both the uart_port entry with their own extensions,
thus::
struct my_port {
struct uart_port port;
int my_stuff;
};
GPIO modem-control line
97-105GPIO를 통해 modem-control line을 설정하거나 읽기 위한 helper가 제공됩니다.
`drivers/tty/serial/serial_mctrl_gpio.c`에서 초기화, GPIO descriptor 변환, set·get, modem-status enable과 동기·비동기 disable helper를 kernel-doc으로 가져옵니다.
공통 helper가 UART modem signal과 GPIO descriptor·value operation을 연결합니다.
Modem control lines via GPIO
----------------------------
Some helpers are provided in order to set/get modem control lines via GPIO.
.. kernel-doc:: drivers/tty/serial/serial_mctrl_gpio.c
:identifiers: mctrl_gpio_init mctrl_gpio_to_gpiod
mctrl_gpio_set mctrl_gpio_get mctrl_gpio_enable_ms
mctrl_gpio_disable_ms_sync mctrl_gpio_disable_ms_no_sync
요약과 해설
driver.rst:1-105Low-level UART driver는 `uart_port` state와 `uart_ops` callback을 serial core에 제공하고 interrupt·console을 담당합니다. Fast port state는 `port->lock`, add·remove·reconfigure lifecycle은 port mutex가 보호하며, core helper와 GPIO modem-control API를 재사용하는 것이 핵심입니다.