vidtv: Virtual Digital TV driver

배경과 구성 요소

이 `GPL-2.0` 문서는 Daniel W. S. Almeida가 2020년 6월 작성했습니다. `vidtv`는 driver 작성자가 template으로 참고할 수 있게 만든 virtual DVB driver이며, 기존 media DVB API도 검증하므로 userspace application 작성자에게도 도움이 됩니다.

현재 구성에는 fake tuner, fake demodulator, fake bridge와 유효한 MPEG Transport Stream encoder가 포함됩니다. Fake tuner는 선택한 frequency가 delivery system별 유효 주파수 표에서 너무 멀면 나쁜 signal quality를 보고합니다.

Fake demodulator는 tuner가 돌려주는 signal quality를 계속 polling합니다. CNR level에 따라 signal lock을 잃거나 다시 획득하는 실제 장치의 동작을 모사합니다. Fake bridge는 tuner와 demod module을 `modprobe`하고 demux logic을 구현하며, 초기화 parameter로 simulation 동작을 결정합니다.

MPEG Transport Stream encoder가 만든 유효 stream은 bridge로 전달됩니다. 현재 hardcoded content는 audio-only channel 하나와 MPEG Elementary Stream 하나이며, 그 ES에는 SMPTE 302M으로 encoding한 sine wave가 들어 있습니다. SMPTE 302M을 선택한 이유는 PCM audio를 MPEG Transport Stream에 넣는 가장 간단한 방법이기 때문입니다.

.. SPDX-License-Identifier: GPL-2.0

================================
vidtv: Virtual Digital TV driver
================================

Author: Daniel W. S. Almeida <dwlsalmeida@gmail.com>, June 2020.

Background
----------

Vidtv is a virtual DVB driver that aims to serve as a reference for driver
writers by serving as a template. It also validates the existing media DVB
APIs, thus helping userspace application writers.

Currently, it consists of:

- A fake tuner driver, which will report a bad signal quality if the chosen
  frequency is too far away from a table of valid frequencies for a
  particular delivery system.

- A fake demod driver, which will constantly poll the fake signal quality
  returned by the tuner, simulating a device that can lose/reacquire a lock
  on the signal depending on the CNR levels.

- A fake bridge driver, which is the module responsible for modprobing the
  fake tuner and demod modules and implementing the demux logic. This module
  takes parameters at initialization that will dictate how the simulation
  behaves.

- Code responsible for encoding a valid MPEG Transport Stream, which is then
  passed to the bridge driver. This fake stream contains some hardcoded content.
  For now, we have a single, audio-only channel containing a single MPEG
  Elementary Stream, which in turn contains a SMPTE 302m encoded sine-wave.
  Note that this particular encoder was chosen because it is the easiest
  way to encode PCM audio data in a MPEG Transport Stream.

Build와 실행

`vidtv`는 test driver이므로 kernel compile 시 기본으로 enable되지 않습니다. 먼저 `DVB_TEST_DRIVERS`를 enable하고 이어서 `DVB_VIDTV`를 enable해야 합니다.

Module로 build하면 `dvb_vidtv_tuner.ko`, `dvb_vidtv_demod.ko`, `dvb_vidtv_bridge.ko`가 생성됩니다. `modprobe vidtv`를 실행하면 bridge driver가 자신의 초기화 과정에서 tuner와 demod driver를 초기화합니다.

기본적으로 DVB-T/T2/C에는 474 MHz를, DVB-S/S2에는 원문 표기 `11,362 GHz`를 허용합니다. Satellite system에서는 10.7 GHz부터 12.75 GHz까지의 Ku-Band frequency를 갖는 universal extended LNBf를 모사합니다. 필요하면 command-line argument로 동작을 바꿀 수 있습니다.

Building vidtv
--------------
vidtv is a test driver and thus is **not** enabled by default when
compiling the kernel.

In order to enable compilation of vidtv:

- Enable **DVB_TEST_DRIVERS**, then
- Enable **DVB_VIDTV**

When compiled as a module, expect the following .ko files:

- dvb_vidtv_tuner.ko

- dvb_vidtv_demod.ko

- dvb_vidtv_bridge.ko

Running vidtv
-------------
When compiled as a module, run::

        modprobe vidtv

That's it! The bridge driver will initialize the tuner and demod drivers as
part of its own initialization.

By default, it will accept the following frequencies:

        - 474 MHz for DVB-T/T2/C;
        - 11,362 GHz for DVB-S/S2.

For satellite systems, the driver simulates an universal extended
LNBf, with frequencies at Ku-Band, ranging from 10.7 GHz to 12.75 GHz.

You can optionally define some command-line arguments to vidtv.

vidtv command-line argument

`drop_tslock_prob_on_low_snr`는 signal quality가 나쁠 때 TS lock을 잃을 확률입니다. Fake demodulator가 좋지 않은 signal에서 때때로 status `0`을 반환하는 데 사용합니다. `recover_tslock_prob_on_good_snr`는 signal이 좋아졌을 때 TS lock을 회복할 확률이며, demodulator가 때때로 status `0x1f`를 반환하게 합니다.

`mock_power_up_delay_msec`는 power-up delay를, `mock_tune_delay_msec`는 tune delay를 모사하며 둘의 기본값은 `0`입니다. `vidtv_valid_dvb_t_freqs`와 `vidtv_valid_dvb_c_freqs`는 각각 모사할 유효 DVB-T·DVB-C frequency를 Hz로 지정하고, `vidtv_valid_dvb_s_freqs`는 Ku-Band DVB-S/S2 frequency를 kHz로 지정합니다.

`max_frequency_shift_hz`는 channel tuning 시 허용할 최대 shift를 Hz로 지정합니다. `si_period_msec`는 SI packet 전송 주기, `pcr_period_msec`는 PCR packet 전송 주기이며 둘 다 기본값은 40 ms입니다.

`mux_rate_kbytes_sec`는 필요할 때 TS NULL packet을 삽입해 유지하려는 bit rate이며 기본값은 4096입니다. `pcr_pid`는 모든 channel의 PCR PID로 기본값은 `0x200`입니다. `mux_buf_sz_pkts`는 188-byte packet의 배수로 mux buffer 크기를 지정합니다.

Command-line arguments to vidtv
-------------------------------
Below is a list of all arguments that can be supplied to vidtv:

drop_tslock_prob_on_low_snr
        Probability of losing the TS lock if the signal quality is bad.
        This probability be used by the fake demodulator driver to
        eventually return a status of 0 when the signal quality is not
        good.

recover_tslock_prob_on_good_snr:
        Probability recovering the TS lock when the signal improves. This
        probability be used by the fake demodulator driver to eventually
        return a status of 0x1f when/if the signal quality improves.

mock_power_up_delay_msec
        Simulate a power up delay.  Default: 0.

mock_tune_delay_msec
        Simulate a tune delay.  Default 0.

vidtv_valid_dvb_t_freqs
        Valid DVB-T frequencies to simulate, in Hz.

vidtv_valid_dvb_c_freqs
        Valid DVB-C frequencies to simulate, in Hz.

vidtv_valid_dvb_s_freqs
        Valid DVB-S/S2 frequencies to simulate at Ku-Band, in kHz.

max_frequency_shift_hz,
        Maximum shift in HZ allowed when tuning in a channel.

si_period_msec
        How often to send SI packets.  Default: 40ms.

pcr_period_msec
        How often to send PCR packets.  Default: 40ms.

mux_rate_kbytes_sec
        Attempt to maintain this bit rate by inserting TS null packets, if
        necessary.  Default: 4096.

pcr_pid,
        PCR PID for all channels.  Default: 0x200.

mux_buf_sz_pkts,
        Size for the mux buffer in multiples of 188 bytes.

내부 module과 MPEG 계층

Kernel module 쪽에서 `vidtv_tuner.[ch]`는 fake tuner DVB driver, `vidtv_demod.[ch]`는 fake demodulator DVB driver, `vidtv_bridge.[ch]`는 bridge driver를 구현합니다.

MPEG 관련 code 중 `vidtv_ts.[ch]`는 TS header, adaptation field, PCR packet, NULL packet 같은 MPEG-TS packet을 다룹니다. `vidtv_psi.[ch]`는 userspace가 Transport Stream 정보를 읽고 dummy channel에 tune할 수 있게 PSI를 생성합니다. 별도 파일이므로 media subsystem의 다른 위치에서도 재사용할 수 있습니다.

현재 지원하는 PSI table은 PAT, PMT, SDT, NIT, EIT 다섯 가지입니다. PAT와 PMT 사양은 `ISO 13818-1: Systems`에, SDT·NIT·EIT 사양은 `ETSI EN 300 468: Specification for Service Information (SI) in DVB systems`에 있습니다.

엄격히 필요하지는 않지만 실제 TS file은 PSI table debugging에 유용합니다. Vidtv는 `TS1Globo.ts`의 PSI 구조를 재현하려 하며 원문은 `https://tsduck.io/streams/brazil-isdb-tb/TS1globo.ts`를 가리킵니다. Stream 구조 시각화에는 `DVBInspector`를 사용할 수 있습니다.

`vidtv_pes.[ch]`는 encoder data를 MPEG-TS packet으로 바꾸는 PES logic을 구현하고, 이 packet은 TS multiplexer를 거쳐 userspace로 전달됩니다. `vidtv_encoder.h`는 encoder interface이며 해당 call을 구현해 새 encoder를 추가할 수 있습니다.

`vidtv_s302m.[ch]`는 생성한 MPEG Transport Stream에 PCM audio를 넣는 S302M encoder입니다. 관련 사양은 `SMPTE 302M-2007: Television - Mapping of AES3 Data into MPEG-2 Transport Stream`입니다. 결과 MPEG Elementary Stream은 S302M registration descriptor를 붙인 private stream으로 운반됩니다.

이 audio signal은 userspace로 넘어가 media software에서 decode·play할 수 있습니다. 대응하는 ffmpeg decoder는 `libavcodec/s302m.c`에 있으며 experimental 상태입니다.

vidtv internal structure
------------------------
The kernel modules are split in the following way:

vidtv_tuner.[ch]
        Implements a fake tuner DVB driver.

vidtv_demod.[ch]
        Implements a fake demodulator DVB driver.

vidtv_bridge.[ch]
        Implements a bridge driver.

The MPEG related code is split in the following way:

vidtv_ts.[ch]
        Code to work with MPEG TS packets, such as TS headers, adaptation
        fields, PCR packets and NULL packets.

vidtv_psi.[ch]
        This is the PSI generator.  PSI packets contain general information
        about a MPEG Transport Stream.  A PSI generator is needed so
        userspace apps can retrieve information about the Transport Stream
        and eventually tune into a (dummy) channel.

        Because the generator is implemented in a separate file, it can be
        reused elsewhere in the media subsystem.

        Currently vidtv supports working with 5 PSI tables: PAT, PMT,
        SDT, NIT and EIT.

        The specification for PAT and PMT can be found in *ISO 13818-1:
        Systems*, while the specification for the SDT, NIT, EIT can be found in *ETSI
        EN 300 468: Specification for Service Information (SI) in DVB
        systems*.

        It isn't strictly necessary, but using a real TS file helps when
        debugging PSI tables. Vidtv currently tries to replicate the PSI
        structure found in this file: `TS1Globo.ts
        <https://tsduck.io/streams/brazil-isdb-tb/TS1globo.ts>`_.

        A good way to visualize the structure of streams is by using
        `DVBInspector <https://sourceforge.net/projects/dvbinspector/>`_.

vidtv_pes.[ch]
        Implements the PES logic to convert encoder data into MPEG TS
        packets. These can then be fed into a TS multiplexer and eventually
        into userspace.

vidtv_encoder.h
        An interface for vidtv encoders. New encoders can be added to this
        driver by implementing the calls in this file.

vidtv_s302m.[ch]
        Implements a S302M encoder to make it possible to insert PCM audio
        data in the generated MPEG Transport Stream. The relevant
        specification is available online as *SMPTE 302M-2007: Television -
        Mapping of AES3 Data into MPEG-2 Transport Stream*.


        The resulting MPEG Elementary Stream is conveyed in a private
        stream with a S302M registration descriptor attached.

        This shall enable passing an audio signal into userspace so it can
        be decoded and played by media software. The corresponding decoder
        in ffmpeg is located in 'libavcodec/s302m.c' and is experimental.

Channel 구성과 TS mux loop

`vidtv_channel.[ch]`는 channel abstraction을 구현합니다. Vidtv가 boot하면 hardcoded channel을 만들고, service를 이어 붙여 SDT를, program을 이어 붙여 PAT를, event를 이어 붙여 EIT를 채웁니다.

PAT의 각 program마다 PMT section을 만들고, channel의 PMT section에 stream을 할당합니다. 각 stream의 encoder를 loop에서 polling해 TS packet을 생성합니다. Muxer는 packet을 서로 interleave할 수 있고, 최종 packet을 bridge로 전달합니다.

`vidtv_mux.[ch]`는 ffmpeg의 `libavcodec/mpegtsenc.c`를 느슨하게 참고한 MPEG-TS mux입니다. Loop는 마지막 iteration 이후 흐른 시간을 추적하고, encoder에서 그 `elapsed_time`만큼의 data를 가져옵니다.

필요하면 PSI 또는 PCR packet을 삽입하고, 선택한 bit rate를 유지해야 하면 결과 stream을 NULL packet으로 padding합니다. 완성한 TS packet은 bridge driver에 전달되고 bridge가 demux로 넘깁니다.

vidtv_channel.[ch]
        Implements a 'channel' abstraction.

        When vidtv boots, it will create some hardcoded channels:

        #. Their services will be concatenated to populate the SDT.

        #. Their programs will be concatenated to populate the PAT

        #. Their events will be concatenated to populate the EIT

        #. For each program in the PAT, a PMT section will be created

        #. The PMT section for a channel will be assigned its streams.

        #. Every stream will have its corresponding encoder polled in a
           loop to produce TS packets.
           These packets may be interleaved by the muxer and then delivered
           to the bridge.

vidtv_mux.[ch]
        Implements a MPEG TS mux, loosely based on the ffmpeg
        implementation in "libavcodec/mpegtsenc.c"

        The muxer runs a loop which is responsible for:

        #. Keeping track of the amount of time elapsed since the last
           iteration.

        #. Polling encoders in order to fetch 'elapsed_time' worth of data.

        #. Inserting PSI and/or PCR packets, if needed.

        #. Padding the resulting stream with NULL packets if
           necessary in order to maintain the chosen bit rate.

        #. Delivering the resulting TS packets to the bridge
           driver so it can pass them to the demux.

v4l-utils와 dvb-fe-tool로 frontend 확인

`v4l-utils` 도구는 vidtv 출력을 시험하고 검사하기에 적합합니다. 이 project는 대부분의 distribution에서 package로 제공되며 media device의 여러 측면을 제어하는 library와 utility를 포함합니다. 원문은 v4l-utils documentation과 `http://git.linuxtv.org/v4l-utils.git`를 안내합니다.

먼저 v4l-utils를 설치하고 `modprobe dvb_vidtv_bridge`를 실행합니다. Driver가 정상이라면 probe code가 실행되며 tuner와 demod driver를 함께 불러옵니다.

Demod가 성공적으로 load됐는지 확인하려면 `dvb-fe-tool`을 실행합니다. 예제 출력은 `/dev/dvb/adapter0/frontend0`의 `Dummy demod for DVB-T/T2/C/S/S2`가 FEC 1/2부터 8/9, automatic FEC·guard interval·hierarchy·inversion·transmission mode, QAM 16/32/64/128/256/AUTO와 QPSK capability를 제공함을 보여 줍니다.

예제의 DVB API version은 5.11이고 현재 delivery system은 `DVBC/ANNEX_A`입니다. 지원 system은 `DVBT`, `DVBT2`, `DVBC/ANNEX_A`, `DVBS`, `DVBS2`입니다. 현재 standard의 frequency 범위는 51.0 MHz부터 2.15 GHz, step은 62.5 kHz, tolerance는 29.5 MHz입니다. Symbol rate 범위는 1.00 MBauds부터 45.0 MBauds입니다.

이 출력은 `static const struct dvb_frontend_ops vidtv_demod_ops`의 설정을 반영합니다. `.delsys` 배열은 다섯 delivery system을, `.info`는 name, `frequency_min_hz`, `frequency_max_hz`, `frequency_stepsize_hz`, `frequency_tolerance_hz`, `symbol_rate_min`, `symbol_rate_max`와 `FE_CAN_*` capability bit를 정의합니다.

자세한 사용법은 원문의 `dvb-fe-tool Documentation` 링크에서 확인할 수 있습니다.

Testing vidtv with v4l-utils
----------------------------

Using the tools in v4l-utils is a great way to test and inspect the output of
vidtv. It is hosted here: `v4l-utils Documentation
<https://linuxtv.org/wiki/index.php/V4l-utils>`_.

From its webpage::

        The v4l-utils are a series of packages for handling media devices.

        It is hosted at http://git.linuxtv.org/v4l-utils.git, and packaged
        on most distributions.

        It provides a series of libraries and utilities to be used to
        control several aspect of the media boards.


Start by installing v4l-utils and then modprobing vidtv::

        modprobe dvb_vidtv_bridge

If the driver is OK, it should load and its probing code will run. This will
pull in the tuner and demod drivers.

Using dvb-fe-tool
~~~~~~~~~~~~~~~~~

The first step to check whether the demod loaded successfully is to run::

        $ dvb-fe-tool
        Device Dummy demod for DVB-T/T2/C/S/S2 (/dev/dvb/adapter0/frontend0) capabilities:
            CAN_FEC_1_2
            CAN_FEC_2_3
            CAN_FEC_3_4
            CAN_FEC_4_5
            CAN_FEC_5_6
            CAN_FEC_6_7
            CAN_FEC_7_8
            CAN_FEC_8_9
            CAN_FEC_AUTO
            CAN_GUARD_INTERVAL_AUTO
            CAN_HIERARCHY_AUTO
            CAN_INVERSION_AUTO
            CAN_QAM_16
            CAN_QAM_32
            CAN_QAM_64
            CAN_QAM_128
            CAN_QAM_256
            CAN_QAM_AUTO
            CAN_QPSK
            CAN_TRANSMISSION_MODE_AUTO
        DVB API Version 5.11, Current v5 delivery system: DVBC/ANNEX_A
        Supported delivery systems:
            DVBT
            DVBT2
            [DVBC/ANNEX_A]
            DVBS
            DVBS2
        Frequency range for the current standard:
        From:            51.0 MHz
        To:              2.15 GHz
        Step:            62.5 kHz
        Tolerance:       29.5 MHz
        Symbol rate ranges for the current standard:
        From:            1.00 MBauds
        To:              45.0 MBauds

This should return what is currently set up at the demod struct, i.e.::

        static const struct dvb_frontend_ops vidtv_demod_ops = {
                .delsys = {
                        SYS_DVBT,
                        SYS_DVBT2,
                        SYS_DVBC_ANNEX_A,
                        SYS_DVBS,
                        SYS_DVBS2,
                },

                .info = {
                        .name                   = "Dummy demod for DVB-T/T2/C/S/S2",
                        .frequency_min_hz       = 51 * MHz,
                        .frequency_max_hz       = 2150 * MHz,
                        .frequency_stepsize_hz  = 62500,
                        .frequency_tolerance_hz = 29500 * kHz,
                        .symbol_rate_min        = 1000000,
                        .symbol_rate_max        = 45000000,

                        .caps = FE_CAN_FEC_1_2 |
                                FE_CAN_FEC_2_3 |
                                FE_CAN_FEC_3_4 |
                                FE_CAN_FEC_4_5 |
                                FE_CAN_FEC_5_6 |
                                FE_CAN_FEC_6_7 |
                                FE_CAN_FEC_7_8 |
                                FE_CAN_FEC_8_9 |
                                FE_CAN_QAM_16 |
                                FE_CAN_QAM_64 |
                                FE_CAN_QAM_32 |
                                FE_CAN_QAM_128 |
                                FE_CAN_QAM_256 |
                                FE_CAN_QAM_AUTO |
                                FE_CAN_QPSK |
                                FE_CAN_FEC_AUTO |
                                FE_CAN_INVERSION_AUTO |
                                FE_CAN_TRANSMISSION_MODE_AUTO |
                                FE_CAN_GUARD_INTERVAL_AUTO |
                                FE_CAN_HIERARCHY_AUTO,
                }

                ....

For more information on dvb-fe-tools check its online documentation here:
`dvb-fe-tool Documentation
<https://www.linuxtv.org/wiki/index.php/Dvb-fe-tool>`_.

dvb-scan으로 tune하고 PSI 읽기

Channel에 tune하고 PSI table을 읽으려면 `dvb-scan`을 사용할 수 있습니다. 이를 위해 scan file이라는 configuration file을 제공합니다. 예제 `[Channel]`은 `FREQUENCY = 474000000`, `MODULATION = QAM/AUTO`, `SYMBOL_RATE = 6940000`, `INNER_FEC = AUTO`, `DELIVERY_SYSTEM = DVBC/ANNEX_A`를 지정합니다.

Parameter는 시험하는 video standard에 따라 달라집니다. Vidtv는 fake driver라 scan file 정보를 많이 검증하지 않습니다. DVB-T/DVB-T2에는 `FREQUENCY`와 `DELIVERY_SYSTEM`만으로 충분하지만, DVB-S/DVB-C에는 `SYMBOL_RATE`도 제공해야 합니다. 원문은 online `dvb-scan-tables` repository를 안내합니다.

File 이름을 `channel.conf`로 정했다면 `dvbv5-scan channel.conf`를 실행합니다. 예제 출력은 bandwidth 또는 symbol-rate가 아직 없어 frequency shift를 계산하지 못했다는 message 뒤 330000000 Hz에서 약한 signal을 보고하고, 474000000 Hz에서 status `0x1f`로 lock한 뒤 `Beethoven` service와 provider `LinuxTV.org`를 찾습니다.

더 자세한 내용은 원문의 `dvb-scan Documentation` 링크에서 확인할 수 있습니다.

Using dvb-scan
~~~~~~~~~~~~~~

In order to tune into a channel and read the PSI tables, we can use dvb-scan.

For this, one should provide a configuration file known as a 'scan file',
here's an example::

        [Channel]
        FREQUENCY = 474000000
        MODULATION = QAM/AUTO
        SYMBOL_RATE = 6940000
        INNER_FEC = AUTO
        DELIVERY_SYSTEM = DVBC/ANNEX_A

.. note::
        The parameters depend on the video standard you're testing.

.. note::
        Vidtv is a fake driver and does not validate much of the information
        in the scan file. Just specifying 'FREQUENCY' and 'DELIVERY_SYSTEM'
        should be enough for DVB-T/DVB-T2. For DVB-S/DVB-C however, you
        should also provide 'SYMBOL_RATE'.

You can browse scan tables online here: `dvb-scan-tables
<https://git.linuxtv.org/dtv-scan-tables.git>`_.

Assuming this channel is named 'channel.conf', you can then run::

        $ dvbv5-scan channel.conf
        dvbv5-scan ~/vidtv.conf
        ERROR    command BANDWIDTH_HZ (5) not found during retrieve
        Cannot calc frequency shift. Either bandwidth/symbol-rate is unavailable (yet).
        Scanning frequency #1 330000000
            (0x00) Signal= -68.00dBm
        Scanning frequency #2 474000000
        Lock   (0x1f) Signal= -34.45dBm C/N= 33.74dB UCB= 0
        Service Beethoven, provider LinuxTV.org: digital television

For more information on dvb-scan, check its documentation online here:
`dvb-scan Documentation <https://www.linuxtv.org/wiki/index.php/Dvbscan>`_.

dvbv5-zap으로 MPEG-TS 기록과 재생

`dvbv5-zap`은 channel에 tune한 뒤 record mode로 MPEG-TS를 disk에 저장하는 command-line tool입니다. 예제 `dvbv5-zap -c dvb_channel.conf "beethoven" -o music.ts -P -t 10`은 모든 program ID를 포함해 10초 동안 `music.ts`에 기록합니다.

출력은 `dvb0.demux0` 사용, channel file 읽기, 474000000 Hz tuning, 모든 PID를 TS에 전달, PES filter 8192와 buffer size 6160384 설정을 보여 줍니다. Lock quality와 signal·C/N·UCB·BER·PER를 보고한 뒤 recording을 시작하며 예제에서는 24,587,768 byte를 약 2401 Kbytes/sec로 받습니다.

기록한 stream은 MPEG-TS를 인식하는 `mplayer`나 `vlc`로 재생해 vidtv 동작을 살펴볼 수 있습니다. `mplayer music.ts`로 file을 직접 재생할 수 있습니다.

또는 첫 terminal에서 `dvbv5-zap -c dvb_channel.conf "beethoven" -P -r &`를 실행하고, 둘째 terminal에서 `mplayer /dev/dvb/adapter0/dvr0`로 DVR interface의 내용을 재생할 수 있습니다. 원문은 `dvb-zap Documentation`, `Dvbv5-zap`, `Zap` 링크를 제공합니다.

Using dvb-zap
~~~~~~~~~~~~~

dvbv5-zap is a command line tool that can be used to record MPEG-TS to disk. The
typical use is to tune into a channel and put it into record mode. The example
below - which is taken from the documentation - illustrates that\ [1]_::

        $ dvbv5-zap -c dvb_channel.conf "beethoven" -o music.ts -P -t 10
        using demux 'dvb0.demux0'
        reading channels from file 'dvb_channel.conf'
        tuning to 474000000 Hz
        pass all PID's to TS
        dvb_set_pesfilter 8192
        dvb_dev_set_bufsize: buffer set to 6160384
        Lock   (0x1f) Quality= Good Signal= -34.66dBm C/N= 33.41dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0
        Lock   (0x1f) Quality= Good Signal= -34.57dBm C/N= 33.46dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0
        Record to file 'music.ts' started
        received 24587768 bytes (2401 Kbytes/sec)
        Lock   (0x1f) Quality= Good Signal= -34.42dBm C/N= 33.89dB UCB= 0 postBER= 0 preBER= 2.44x10^-3 PER= 0

.. [1] In this example, it records 10 seconds with all program ID's stored
       at the music.ts file.


The channel can be watched by playing the contents of the stream with some
player that  recognizes the MPEG-TS format, such as ``mplayer`` or ``vlc``.

By playing the contents of the stream one can visually inspect the workings of
vidtv, e.g., to play a recorded TS file with::

        $ mplayer music.ts

or, alternatively, running this command on one terminal::

        $ dvbv5-zap -c dvb_channel.conf "beethoven" -P -r &

And, on a second terminal, playing the contents from DVR interface with::

        $ mplayer /dev/dvb/adapter0/dvr0

For more information on dvb-zap check its online documentation here:
`dvb-zap Documentation
<https://www.linuxtv.org/wiki/index.php/Dvbv5-zap>`_.
See also: `zap <https://www.linuxtv.org/wiki/index.php/Zap>`_.

vidtv의 개선 과제

첫 번째 과제는 `debugfs` integration입니다. Frontend driver는 `.read_status` call을 통해 DVBv5 statistics를 제공하지만, debug purpose용 RAM-based filesystem인 debugfs로 추가 driver-specific statistics를 userspace에 제공하면 유용합니다.

이 logic은 frontend driver를 복잡하게 하지 않도록 별도 파일에 구현해야 합니다. Siano driver가 debugfs로 driver-specific statistics를 userspace에 전달하는 참고 사례이며, 편의를 위해 별도 Kconfig option으로 enable·disable할 수 있어야 합니다.

두 번째 과제는 video test입니다. 현재 vidtv는 PCM audio만 encoding합니다. MPEG Transport Stream에서 compressed video encoding을 다루는 `ISO 13818-2: Information technology - Generic coding of moving pictures and associated audio information - Part 2: Video`를 바탕으로 최소 MPEG-2 video encoder를 구현할 수 있습니다.

Video source에는 `drivers/media/common/v4l2-tpg/`의 Video4Linux2 Test Pattern Generator인 `v4l2-tpg`를 선택적으로 사용할 수 있습니다.

세 번째 과제는 white noise simulation입니다. 현재 tuner는 선택 frequency가 유효 frequency 표에서 너무 먼지 판별하고, 나쁜 signal quality를 보고해 demodulator가 결국 lock을 잃게 할 수 있습니다.

Signal quality가 나쁠 때 noise를 모사하려면 TS packet을 무작위로 drop할 수 있습니다. Continuity counter는 갱신됐지만 packet이 demux로 전달되지 않으면 continuity error가 발생합니다. 또한 BER 같은 error statistics를 갱신하고 encoded data 자체에 noise를 모사할 수 있습니다.

What can still be improved in vidtv
-----------------------------------

Add *debugfs* integration
~~~~~~~~~~~~~~~~~~~~~~~~~

Although frontend drivers provide DVBv5 statistics via the .read_status
call, a nice addition would be to make additional statistics available to
userspace via debugfs, which is a simple-to-use, RAM-based filesystem
specifically designed for debug purposes.

The logic for this would be implemented on a separate file so as not to
pollute the frontend driver.  These statistics are driver-specific and can
be useful during tests.

The Siano driver is one example of a driver using
debugfs to convey driver-specific statistics to userspace and it can be
used as a reference.

This should be further enabled and disabled via a Kconfig
option for convenience.

Add a way to test video
~~~~~~~~~~~~~~~~~~~~~~~

Currently, vidtv can only encode PCM audio. It would be great to implement
a barebones version of MPEG-2 video encoding so we can also test video. The
first place to look into is *ISO 13818-2: Information technology — Generic
coding of moving pictures and associated audio information — Part 2: Video*,
which covers the encoding of compressed video in MPEG Transport Streams.

This might optionally use the Video4Linux2 Test Pattern Generator, v4l2-tpg,
which resides at::

        drivers/media/common/v4l2-tpg/


Add white noise simulation
~~~~~~~~~~~~~~~~~~~~~~~~~~

The vidtv tuner already has code to identify whether the chosen frequency
is too far away from a table of valid frequencies. For now, this means that
the demodulator can eventually lose the lock on the signal, since the tuner will
report a bad signal quality.

A nice addition is to simulate some noise when the signal quality is bad by:

- Randomly dropping some TS packets. This will trigger a continuity error if the
  continuity counter is updated but the packet is not passed on to the demux.

- Updating the error statistics accordingly (e.g. BER, etc).

- Simulating some noise in the encoded data.

vidtv에서 사용하는 function과 struct

마지막 절은 vidtv implementation의 function과 struct를 kernel-doc으로 포함합니다. Header는 bridge, channel, demod, encoder, mux, PES, PSI, S302M, TS, tuner interface를 문서화합니다.

Source file에서는 공통 helper를 담은 `vidtv_common.c`와 tuner implementation인 `vidtv_tuner.c`의 kernel-doc을 포함합니다. 모든 path는 `drivers/media/test-drivers/vidtv/` 아래에 있습니다.

Functions and structs used within vidtv
---------------------------------------

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_bridge.h

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_channel.h

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_demod.h

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_encoder.h

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_mux.h

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_pes.h

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_psi.h

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_s302m.h

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_ts.h

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.h

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_common.c

.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.c