Documentation/media/uapi/dvb/dvbproperty.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _frontend-properties:
   4
   5 DVB Frontend properties
   6 =======================
   7
   8 Tuning into a Digital TV physical channel and starting decoding it
   9 requires changing a set of parameters, in order to control the tuner,
  10 the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
  11 antenna subsystem via Satellite Equipment Control (SEC), on satellite
  12 systems. The actual parameters are specific to each particular digital
  13 TV standards, and may change as the digital TV specs evolves.
  14
  15 In the past, the strategy used was to have a union with the parameters
  16 needed to tune for DVB-S, DVB-C, DVB-T and ATSC delivery systems grouped
  17 there. The problem is that, as the second generation standards appeared,
  18 those structs were not big enough to contain the additional parameters.
  19 Also, the union didn't have any space left to be expanded without
  20 breaking userspace. So, the decision was to deprecate the legacy
  21 union/struct based approach, in favor of a properties set approach.
  22
  23 .. note::
  24
  25    On Linux DVB API version 3, setting a frontend were done via
  26    struct :c:type:`dvb_frontend_parameters`.
  27    This got replaced on version 5 (also called "S2API", as this API were
  28    added originally_enabled to provide support for DVB-S2), because the
  29    old API has a very limited support to new standards and new hardware.
  30    This section describes the new and recommended way to set the frontend,
  31    with suppports all digital TV delivery systems.
  32
  33 Example: with the properties based approach, in order to set the tuner
  34 to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and
  35 symbol rate of 5.217 Mbauds, those properties should be sent to
  36 :ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:
  37
  38 -  :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` =
  39    SYS_DVBC_ANNEX_A
  40
  41 -  :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000
  42
  43 -  :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256
  44
  45 -  :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO
  46
  47 -  :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000
  48
  49 -  :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4
  50
  51 -  :ref:`DTV_TUNE <DTV-TUNE>`
  52
  53 The code that would that would do the above is show in
  54 :ref:`dtv-prop-example`.
  55
  56 .. _dtv-prop-example:
  57
  58 Example: Setting digital TV frontend properties
  59 ===============================================
  60
  61 .. code-block:: c
  62
  63     #include <stdio.h>
  64     #include <fcntl.h>
  65     #include <sys/ioctl.h>
  66     #include <linux/dvb/frontend.h>
  67
  68     static struct dtv_property props[] = {
  69         { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },
  70         { .cmd = DTV_FREQUENCY,       .u.data = 651000000 },
  71         { .cmd = DTV_MODULATION,      .u.data = QAM_256 },
  72         { .cmd = DTV_INVERSION,       .u.data = INVERSION_AUTO },
  73         { .cmd = DTV_SYMBOL_RATE,     .u.data = 5217000 },
  74         { .cmd = DTV_INNER_FEC,       .u.data = FEC_3_4 },
  75         { .cmd = DTV_TUNE }
  76     };
  77
  78     static struct dtv_properties dtv_prop = {
  79         .num = 6, .props = props
  80     };
  81
  82     int main(void)
  83     {
  84         int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);
  85
  86         if (!fd) {
  87             perror ("open");
  88             return -1;
  89         }
  90         if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {
  91             perror("ioctl");
  92             return -1;
  93         }
  94         printf("Frontend set\\n");
  95         return 0;
  96     }
  97
  98 .. attention:: While it is possible to directly call the Kernel code like the
  99    above example, it is strongly recommended to use
 100    `libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it
 101    provides abstraction to work with the supported digital TV standards and
 102    provides methods for usual operations like program scanning and to
 103    read/write channel descriptor files.
 104
 105
 106 .. toctree::
 107     :maxdepth: 1
 108
 109     dtv-stats
 110     dtv-fe-stats
 111     dtv-property
 112     dtv-properties
 113     dvbproperty-006
 114     fe_property_parameters
 115     frontend-stat-properties
 116     frontend-property-terrestrial-systems
 117     frontend-property-cable-systems
 118     frontend-property-satellite-systems