요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
Digital TV Demux kABI
---------------------
Digital TV Demux
~~~~~~~~~~~~~~~~
The Kernel Digital TV Demux kABI defines a driver-internal interface for
registering low-level, hardware specific driver to a hardware independent
demux layer. It is only of interest for Digital TV device driver writers.
The header file for this kABI is named ``demux.h`` and located in
``include/media``.
The demux kABI should be implemented for each demux in the system. It is
used to select the TS source of a demux and to manage the demux resources.
When the demux client allocates a resource via the demux kABI, it receives
a pointer to the kABI of that resource.
Each demux receives its TS input from a DVB front-end or from memory, as
set via this demux kABI. In a system with more than one front-end, the kABI
can be used to select one of the DVB front-ends as a TS source for a demux,
unless this is fixed in the HW platform.
The demux kABI only controls front-ends regarding to their connections with
demuxes; the kABI used to set the other front-end parameters, such as
tuning, are defined via the Digital TV Frontend kABI.
The functions that implement the abstract interface demux should be defined
static or module private and registered to the Demux core for external
access. It is not necessary to implement every function in the struct
:c:type:`dmx_demux`. For example, a demux interface might support Section filtering,
but not PES filtering. The kABI client is expected to check the value of any
function pointer before calling the function: the value of ``NULL`` means
that the function is not available.
Whenever the functions of the demux API modify shared data, the
possibilities of lost update and race condition problems should be
addressed, e.g. by protecting parts of code with mutexes.
Note that functions called from a bottom half context must not sleep.
Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a
kernel thread being put to sleep if swapping is needed. For example, the
Linux Kernel calls the functions of a network device interface from a
bottom half context. Thus, if a demux kABI function is called from network
device code, the function must not sleep.
Demux Callback API
~~~~~~~~~~~~~~~~~~
This kernel-space API comprises the callback functions that deliver filtered
data to the demux client. Unlike the other DVB kABIs, these functions are
provided by the client and called from the demux code.
The function pointers of this abstract interface are not packed into a
structure as in the other demux APIs, because the callback functions are
registered and used independent of each other. As an example, it is possible
for the API client to provide several callback functions for receiving TS
packets and no callbacks for PES packets or sections.
The functions that implement the callback API need not be re-entrant: when
a demux driver calls one of these functions, the driver is not allowed to
call the function again before the original call returns. If a callback is
triggered by a hardware interrupt, it is recommended to use the Linux
bottom half mechanism or start a tasklet instead of making the callback
function call directly from a hardware interrupt.
This mechanism is implemented by :c:func:`dmx_ts_cb()` and :c:func:`dmx_section_cb()`
callbacks.
Digital TV Demux device registration functions and data structures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/media/dmxdev.h
High-level Digital TV demux interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/media/dvb_demux.h
Driver-internal low-level hardware specific driver demux interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/media/demux.h
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Digital TV Demux kABI의 역할
1-27Digital TV Demux kernel ABI는 low-level hardware-specific driver를 hardware-independent demux layer에 등록하는 driver 내부 interface입니다. Digital TV device driver 작성자를 위한 API이며 header는 `include/media/demux.h`입니다.
System의 각 demux는 이 kABI를 구현해야 합니다. Interface는 demux의 TS source를 선택하고 demux resource를 관리합니다. Client가 kABI로 resource를 할당하면 해당 resource kABI를 가리키는 pointer를 받습니다.
각 demux는 이 kABI 설정에 따라 DVB frontend 또는 memory에서 TS input을 받습니다. Frontend가 여러 개인 system에서는 hardware platform이 고정하지 않은 한 그중 하나를 demux의 TS source로 선택할 수 있습니다.
Demux kABI가 frontend에 대해 제어하는 것은 demux와의 연결뿐입니다. Tuning 같은 다른 frontend parameter를 설정하는 kABI는 Digital TV Frontend kABI에 별도로 정의됩니다.
Demux kABI가 연결을 선택하고 resource interface를 client에 돌려줍니다.
.. SPDX-License-Identifier: GPL-2.0
Digital TV Demux kABI
---------------------
Digital TV Demux
~~~~~~~~~~~~~~~~
The Kernel Digital TV Demux kABI defines a driver-internal interface for
registering low-level, hardware specific driver to a hardware independent
demux layer. It is only of interest for Digital TV device driver writers.
The header file for this kABI is named ``demux.h`` and located in
``include/media``.
The demux kABI should be implemented for each demux in the system. It is
used to select the TS source of a demux and to manage the demux resources.
When the demux client allocates a resource via the demux kABI, it receives
a pointer to the kABI of that resource.
Each demux receives its TS input from a DVB front-end or from memory, as
set via this demux kABI. In a system with more than one front-end, the kABI
can be used to select one of the DVB front-ends as a TS source for a demux,
unless this is fixed in the HW platform.
The demux kABI only controls front-ends regarding to their connections with
demuxes; the kABI used to set the other front-end parameters, such as
tuning, are defined via the Digital TV Frontend kABI.Interface 구현과 concurrency 제약
28-47Abstract demux interface를 구현하는 function은 `static` 또는 module-private으로 정의하고 외부 접근을 위해 Demux core에 등록해야 합니다. `dmx_demux` structure의 모든 function을 구현할 필요는 없습니다. 예를 들어 section filtering만 지원하고 PES filtering은 지원하지 않을 수 있습니다.
kABI client는 function pointer를 호출하기 전에 값을 확인해야 합니다. `NULL`이면 해당 function을 사용할 수 없습니다.
Demux API function이 shared data를 수정하면 lost update와 race condition 가능성을 다뤄야 하며, 예를 들어 관련 code를 mutex로 보호합니다.
Bottom-half context에서 호출되는 function은 sleep하면 안 됩니다. `GFP_ATOMIC` 없이 단순 memory allocation만 해도 swap이 필요하면 kernel thread가 sleep할 수 있습니다. Network device interface function은 bottom half에서 호출되므로 network device code가 demux kABI function을 부르면 그 function도 절대 sleep하지 않아야 합니다.
The functions that implement the abstract interface demux should be defined
static or module private and registered to the Demux core for external
access. It is not necessary to implement every function in the struct
:c:type:`dmx_demux`. For example, a demux interface might support Section filtering,
but not PES filtering. The kABI client is expected to check the value of any
function pointer before calling the function: the value of ``NULL`` means
that the function is not available.
Whenever the functions of the demux API modify shared data, the
possibilities of lost update and race condition problems should be
addressed, e.g. by protecting parts of code with mutexes.
Note that functions called from a bottom half context must not sleep.
Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a
kernel thread being put to sleep if swapping is needed. For example, the
Linux Kernel calls the functions of a network device interface from a
bottom half context. Thus, if a demux kABI function is called from network
device code, the function must not sleep.
Demux callback API
48-70이 kernel-space API는 filtering한 data를 demux client에 전달하는 callback function으로 구성됩니다. 다른 DVB kABI와 달리 client가 function을 제공하고 demux code가 호출합니다.
Callback은 서로 독립적으로 등록·사용되므로 function pointer를 다른 demux API처럼 하나의 structure에 묶지 않습니다. Client는 TS packet 수신 callback을 여러 개 제공하면서 PES packet이나 section callback은 하나도 제공하지 않을 수 있습니다.
Callback implementation은 re-entrant일 필요가 없습니다. Demux driver는 원래 호출이 반환되기 전에 같은 function을 다시 호출할 수 없습니다.
Hardware interrupt가 callback을 trigger하면 interrupt handler에서 직접 callback을 호출하기보다 Linux bottom-half mechanism이나 tasklet을 사용하는 것이 권장됩니다. 이 mechanism은 `dmx_ts_cb()`와 `dmx_section_cb()` callback으로 구현됩니다.
Client가 callback을 제공하고 demux가 filtering 결과를 전달합니다.
Demux Callback API
~~~~~~~~~~~~~~~~~~
This kernel-space API comprises the callback functions that deliver filtered
data to the demux client. Unlike the other DVB kABIs, these functions are
provided by the client and called from the demux code.
The function pointers of this abstract interface are not packed into a
structure as in the other demux APIs, because the callback functions are
registered and used independent of each other. As an example, it is possible
for the API client to provide several callback functions for receiving TS
packets and no callbacks for PES packets or sections.
The functions that implement the callback API need not be re-entrant: when
a demux driver calls one of these functions, the driver is not allowed to
call the function again before the original call returns. If a callback is
triggered by a hardware interrupt, it is recommended to use the Linux
bottom half mechanism or start a tasklet instead of making the callback
function call directly from a hardware interrupt.
This mechanism is implemented by :c:func:`dmx_ts_cb()` and :c:func:`dmx_section_cb()`
callbacks.
Demux registration과 interface header
71-84Digital TV Demux device registration function과 data structure는 `include/media/dmxdev.h`에 있습니다. High-level Digital TV demux interface는 `include/media/dvb_demux.h`에 있습니다.
Driver 내부의 low-level hardware-specific demux interface는 `include/media/demux.h`에 있으며 앞 절에서 설명한 kABI의 원본 정의를 제공합니다.
Digital TV Demux device registration functions and data structures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/media/dmxdev.h
High-level Digital TV demux interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/media/dvb_demux.h
Driver-internal low-level hardware specific driver demux interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/media/demux.h
요약과 해설
dtv-demux.rst:1-84Demux kABI는 frontend 또는 memory TS source를 hardware-independent demux에 연결하고 resource를 client에 제공합니다. Optional function은 `NULL`일 수 있으므로 caller가 검사하며, shared data와 bottom-half context에는 각각 locking과 비수면 규칙을 적용해야 합니다.