TTY Line Discipline

TTY line discipline 개요

TTY line discipline은 TTY device로 들어오고 나가는 모든 문자를 처리합니다. 기본 line discipline은 `N_TTY`이며 `n_tty` 문서에서 자세히 설명합니다. 다른 discipline을 TTY에 설정하지 못했을 때도 `N_TTY`가 fallback으로 사용됩니다.

`N_TTY`조차 설정에 실패하면 항상 설정 가능한 `N_NULL`이 대신합니다. 다만 `N_NULL`은 문자를 처리하지 않고 모두 버립니다.

.. SPDX-License-Identifier: GPL-2.0

===================
TTY Line Discipline
===================

.. contents:: :local:

TTY line discipline process all incoming and outgoing character from/to a tty
device. The default line discipline is :doc:`N_TTY <n_tty>`. It is also a
fallback if establishing any other discipline for a tty fails. If even N_TTY
fails, N_NULL takes over. That never fails, but also does not process any
characters -- it throws them away.

등록과 참조 계수

Line discipline은 ldisc 구조체를 `tty_register_ldisc()`에 전달해 등록합니다. 등록 시점에는 discipline이 즉시 사용 가능한 상태여야 합니다. 함수가 성공을 반환하기 전에도 사용될 수 있지만, 오류를 반환하면 호출되지 않습니다.

ldisc number는 userspace ABI의 일부이므로 재사용하면 안 됩니다. 기존 ldisc를 덮어쓰거나 같은 데이터로 다시 등록하는 행위도 금지됩니다. 원문은 이를 어기면 컴퓨터를 악마들이 먹어 치울 것이라는 강한 표현으로 경고합니다. 제거할 때는 `tty_unregister_ldisc()`를 호출합니다.

ldisc table에 등록된 `tty_ldisc` 사본의 reference count는 이 discipline을 사용하는 line 수를 셉니다. 반면 각 TTY 안의 `tty_ldisc` 구조체 reference count는 바로 그 순간 활성 상태인 ldisc 사용자를 셉니다. 실질적으로는 ldisc method 안에서 실행 중인 thread 수와 진입·종료 직전의 thread를 포함합니다.

Registration
============

Line disciplines are registered with tty_register_ldisc() passing the ldisc
structure. At the point of registration the discipline must be ready to use and
it is possible it will get used before the call returns success. If the call
returns an error then it won’t get called. Do not re-use ldisc numbers as they
are part of the userspace ABI and writing over an existing ldisc will cause
demons to eat your computer. You must not re-register over the top of the line
discipline even with the same data or your computer again will be eaten by
demons. In order to remove a line discipline call tty_unregister_ldisc().

Heed this warning: the reference count field of the registered copies of the
tty_ldisc structure in the ldisc table counts the number of lines using this
discipline. The reference count of the tty_ldisc structure within a tty counts
the number of active users of the ldisc at this instant. In effect it counts
the number of threads of execution within an ldisc method (plus those about to
enter and exit although this detail matters not).

.. kernel-doc:: drivers/tty/tty_ldisc.c
   :identifiers: tty_register_ldisc tty_unregister_ldisc

기타 함수와 operation reference

`drivers/tty/tty_ldisc.c`에서 `tty_set_ldisc`와 `tty_ldisc_flush`의 kernel-doc을 가져옵니다. 각각 TTY의 line discipline 변경과 line discipline 관련 flush 경로를 설명합니다.

Line discipline operation 전체 계약은 `include/linux/tty_ldisc.h`의 `tty_ldisc_ops` kernel-doc에서 생성됩니다.

Other Functions
===============

.. kernel-doc:: drivers/tty/tty_ldisc.c
   :identifiers: tty_set_ldisc tty_ldisc_flush

Line Discipline Operations Reference
====================================

.. kernel-doc:: include/linux/tty_ldisc.h
   :identifiers: tty_ldisc_ops

Driver 접근과 TTY flags

Line discipline method는 아래쪽 hardware driver의 method를 호출할 수 있습니다. 이 method들은 `struct tty_operations` 문서의 일부로 설명됩니다.

또한 line discipline method는 `tty_struct.flags` field에 접근할 수 있습니다. 관련 구조와 flag 문맥은 `tty_struct` 문서를 참조합니다.

Driver Access
=============

Line discipline methods can call the methods of the underlying hardware driver.
These are documented as a part of struct tty_operations.

TTY Flags
=========

Line discipline methods have access to :c:member:`tty_struct.flags` field. See
:doc:`tty_struct`.

Locking과 호출 예외

TTY layer에서 line discipline 함수를 호출하는 쪽은 line discipline lock을 획득해야 합니다. Driver 쪽 호출에도 같은 규칙이 적용되지만 아직 강제되지는 않습니다.

`tty_ldisc_ref_wait`, `tty_ldisc_ref`, `tty_ldisc_deref`는 이전 코드보다 조금 느리지만 영향은 작아야 합니다. 대부분의 receive logic은 flip buffer를 사용하며 driver를 통해 데이터를 위로 밀어 올릴 때만 reference를 얻으면 되기 때문입니다.

주의할 예외가 있습니다. `tty_ldisc_ops.open()`, `tty_ldisc_ops.close()`, `tty_driver.set_ldisc()`는 ldisc를 사용할 수 없는 상태에서 호출됩니다. 따라서 이 함수 안에서 `tty_ldisc_ref()`를 사용하면 실패합니다. Ldisc와 driver code가 자기 함수를 호출할 때도 이 조건을 고려해야 합니다.

Locking
=======

Callers to the line discipline functions from the tty layer are required to
take line discipline locks. The same is true of calls from the driver side
but not yet enforced.

.. kernel-doc:: drivers/tty/tty_ldisc.c
   :identifiers: tty_ldisc_ref_wait tty_ldisc_ref tty_ldisc_deref

While these functions are slightly slower than the old code they should have
minimal impact as most receive logic uses the flip buffers and they only
need to take a reference when they push bits up through the driver.

A caution: The :c:member:`tty_ldisc_ops.open()`,
:c:member:`tty_ldisc_ops.close()` and :c:member:`tty_driver.set_ldisc()`
functions are called with the ldisc unavailable. Thus tty_ldisc_ref() will fail
in this situation if used within these functions.  Ldisc and driver code
calling its own functions must be careful in this case.

내부 함수

마지막 절은 `drivers/tty/tty_ldisc.c`에서 `:internal:`로 분류된 kernel-doc을 포함합니다. 외부 operation reference와 구분되는 line discipline core 구현 내부 함수가 이 범위에 렌더링됩니다.

Internal Functions
==================

.. kernel-doc:: drivers/tty/tty_ldisc.c
   :internal: