Property types

튜닝 property가 제어하는 하드웨어

이 문서는 GFDL-1.1-no-invariants-or-later 라이선스를 따르며 `frontend-properties` 참조 대상으로 frontend property 형식을 설명합니다.

Digital TV 물리 채널에 맞춰 튜닝하고 디코딩을 시작하려면 tuner, demodulator, Linear Low-noise Amplifier(LNA)를 제어하는 여러 매개변수를 바꿔야 합니다.

위성 시스템에서는 Satellite Equipment Control(SEC)을 통해 안테나 하위 시스템도 설정합니다.

실제 매개변수는 각 Digital TV 표준에 따라 다르며 표준 사양이 발전함에 따라 바뀔 수 있습니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _frontend-properties:

**************
Property types
**************

Tuning into a Digital TV physical channel and starting decoding it
requires changing a set of parameters, in order to control the tuner,
the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
antenna subsystem via Satellite Equipment Control - SEC (on satellite
systems). The actual parameters are specific to each particular digital
TV standards, and may change as the digital TV specs evolves.

DVBv3 union에서 property 집합으로

과거 DVB API version 3(DVBv3)까지는 DVB-S, DVB-C, DVB-T, ATSC delivery system의 튜닝 매개변수를 하나의 union에 묶었습니다.

2세대 표준이 등장하자 새 구조체를 모두 넣기에 union 크기가 부족했고, 크기를 확장하면 기존 사용자 공간 ABI가 깨지는 문제가 생겼습니다.

따라서 legacy union/struct 방식은 폐기 예정이 되었고 property set 방식으로 대체되었습니다. `FE_GET_PROPERTY`와 `FE_SET_PROPERTY`로 frontend를 구성하고 상태를 읽습니다.

실제 동작은 `dtv_property`의 cmd/data 쌍 집합으로 정합니다. 한 번의 ioctl로 최대 64개 property를 가져오거나 설정할 수 있습니다.

이 절은 모든 Digital TV delivery system을 지원하는 새롭고 권장되는 frontend 설정 방식을 설명합니다.

In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a
union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and
ATSC delivery systems grouped there. The problem is that, as the second
generation standards appeared, the size of such union was not big
enough to group the structs that would be required for those new
standards. Also, extending it would break userspace.

So, the legacy union/struct based approach was deprecated, in favor
of a properties set approach. On such approach,
:ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>` are used
to setup the frontend and read its status.

The actual action is determined by a set of dtv_property cmd/data pairs.
With one single ioctl, is possible to get/set up to 64 properties.

This section describes the new and recommended way to set the frontend,
with supports all digital TV delivery systems.

DVB API version 3과 5 선택

Linux DVB API version 3에서는 `struct dvb_frontend_parameters`로 frontend를 설정했습니다.

새 표준을 지원하는 하드웨어에서는 version 3 호출을 사용하지 않아야 합니다. 새 표준과 새 하드웨어를 지원하지 못하거나 지원 범위가 매우 제한적입니다.

오늘날 대부분의 frontend는 여러 delivery system을 지원하며, frontend가 제공하는 시스템 사이를 전환하려면 DVB API version 5 호출이 필요합니다.

DVB API version 5는 처음 추가된 새 표준이 DVB-S2였기 때문에 `S2API`라고도 합니다.

.. note::

   1. On Linux DVB API version 3, setting a frontend was done via
      struct :c:type:`dvb_frontend_parameters`.

   2. Don't use DVB API version 3 calls on hardware with supports
      newer standards. Such API provides no support or a very limited
      support to new standards and/or new hardware.

   3. Nowadays, most frontends support multiple delivery systems.
      Only with DVB API version 5 calls it is possible to switch between
      the multiple delivery systems supported by a frontend.

   4. DVB API version 5 is also called *S2API*, as the first
      new standard added to it was DVB-S2.

DVB-C 튜닝 property 예

예제는 256-QAM, FEC 3/4, symbol rate 5.217 Mbaud인 DVB-C 채널에 맞춰 하드웨어를 튜닝하는 property 목록을 제시합니다.

원문 본문은 채널을 651 kHz라고 적지만 `DTV_FREQUENCY` 값은 `651000000`입니다. 두 값을 자동으로 고치거나 통일하지 않고 원문상 불일치로 표시합니다.

설정은 delivery system, frequency, modulation, inversion, symbol rate, inner FEC를 지정한 뒤 `DTV_TUNE`으로 끝납니다.

이어지는 `dtv-prop-example` 코드가 위 동작을 구현합니다.

**Example**: in order to set the hardware to tune into a DVB-C channel
at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.217
Mbauds, those properties should be sent to
:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:

  :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` = SYS_DVBC_ANNEX_A

  :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000

  :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256

  :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO

  :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000

  :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4

  :ref:`DTV_TUNE <DTV-TUNE>`

The code that would that would do the above is show in
:ref:`dtv-prop-example`.

C 코드의 설정과 호출

예제 코드는 `stdio.h`, `fcntl.h`, `sys/ioctl.h`, `linux/dvb/frontend.h`를 포함합니다.

정적 `props` 배열에는 여섯 개의 값 property와 마지막 `DTV_TUNE` 항목이 들어 있습니다.

`struct dtv_properties dtv_prop`은 원문 코드에서 `.num = 6`과 `.props = props`로 초기화합니다. 배열에는 `DTV_TUNE`까지 7개 항목이 보이지만 원문 코드는 수정하지 않고 검수 주의점으로 남깁니다.

`main()`은 `/dev/dvb/adapter0/frontend0`을 `O_RDWR`로 열고 실패 시 `perror("open")` 뒤 -1을 반환합니다. 원문의 `if (!fd)` 조건도 그대로 보존합니다.

그 다음 `ioctl(fd, FE_SET_PROPERTY, &dtv_prop)`을 호출하고 실패 시 오류를 출력하며, 성공하면 `Frontend set`을 출력하고 0을 반환합니다.

.. code-block:: c
    :caption: Example: Setting digital TV frontend properties
    :name: dtv-prop-example

    #include <stdio.h>
    #include <fcntl.h>
    #include <sys/ioctl.h>
    #include <linux/dvb/frontend.h>

    static struct dtv_property props[] = {
	{ .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },
	{ .cmd = DTV_FREQUENCY,       .u.data = 651000000 },
	{ .cmd = DTV_MODULATION,      .u.data = QAM_256 },
	{ .cmd = DTV_INVERSION,       .u.data = INVERSION_AUTO },
	{ .cmd = DTV_SYMBOL_RATE,     .u.data = 5217000 },
	{ .cmd = DTV_INNER_FEC,       .u.data = FEC_3_4 },
	{ .cmd = DTV_TUNE }
    };

    static struct dtv_properties dtv_prop = {
	.num = 6, .props = props
    };

    int main(void)
    {
	int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);

	if (!fd) {
	    perror ("open");
	    return -1;
	}
	if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {
	    perror("ioctl");
	    return -1;
	}
	printf("Frontend set\\n");
	return 0;
    }

libdvbv5 권장과 하위 문서

예제처럼 커널 API를 직접 호출할 수 있지만 문서는 `libdvbv5` 사용을 강하게 권장합니다.

libdvbv5는 지원되는 Digital TV 표준을 다루는 추상화, 프로그램 검색, 채널 descriptor 파일 읽기·쓰기 같은 일반 작업 방법을 제공합니다.

하위 목차는 property 매개변수, frontend 통계 지표, 지상파·케이블·위성 property, frontend 헤더 문서로 이어지며 최대 깊이는 1입니다.

.. attention:: While it is possible to directly call the Kernel code like the
   above example, it is strongly recommended to use
   `libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it
   provides abstraction to work with the supported digital TV standards and
   provides methods for usual operations like program scanning and to
   read/write channel descriptor files.

.. toctree::
    :maxdepth: 1

    fe_property_parameters
    frontend-stat-properties
    frontend-property-terrestrial-systems
    frontend-property-cable-systems
    frontend-property-satellite-systems
    frontend-header