Documentation/media/uapi/dvb/dvbproperty.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _frontend-properties:
  11
  12 **************
  13 Property types
  14 **************
  15
  16 Tuning into a Digital TV physical channel and starting decoding it
  17 requires changing a set of parameters, in order to control the tuner,
  18 the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
  19 antenna subsystem via Satellite Equipment Control - SEC (on satellite
  20 systems). The actual parameters are specific to each particular digital
  21 TV standards, and may change as the digital TV specs evolves.
  22
  23 In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a
  24 union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and
  25 ATSC delivery systems grouped there. The problem is that, as the second
  26 generation standards appeared, the size of such union was not big
  27 enough to group the structs that would be required for those new
  28 standards. Also, extending it would break userspace.
  29
  30 So, the legacy union/struct based approach was deprecated, in favor
  31 of a properties set approach. On such approach,
  32 :ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>` are used
  33 to setup the frontend and read its status.
  34
  35 The actual action is determined by a set of dtv_property cmd/data pairs.
  36 With one single ioctl, is possible to get/set up to 64 properties.
  37
  38 This section describes the new and recommended way to set the frontend,
  39 with supports all digital TV delivery systems.
  40
  41 .. note::
  42
  43    1. On Linux DVB API version 3, setting a frontend was done via
  44       struct :c:type:`dvb_frontend_parameters`.
  45
  46    2. Don't use DVB API version 3 calls on hardware with supports
  47       newer standards. Such API provides no suport or a very limited
  48       support to new standards and/or new hardware.
  49
  50    3. Nowadays, most frontends support multiple delivery systems.
  51       Only with DVB API version 5 calls it is possible to switch between
  52       the multiple delivery systems supported by a frontend.
  53
  54    4. DVB API version 5 is also called *S2API*, as the first
  55       new standard added to it was DVB-S2.
  56
  57 **Example**: in order to set the hardware to tune into a DVB-C channel
  58 at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.217
  59 Mbauds, those properties should be sent to
  60 :ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:
  61
  62   :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` = SYS_DVBC_ANNEX_A
  63
  64   :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000
  65
  66   :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256
  67
  68   :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO
  69
  70   :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000
  71
  72   :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4
  73
  74   :ref:`DTV_TUNE <DTV-TUNE>`
  75
  76 The code that would that would do the above is show in
  77 :ref:`dtv-prop-example`.
  78
  79 .. code-block:: c
  80     :caption: Example: Setting digital TV frontend properties
  81     :name: dtv-prop-example
  82
  83     #include <stdio.h>
  84     #include <fcntl.h>
  85     #include <sys/ioctl.h>
  86     #include <linux/dvb/frontend.h>
  87
  88     static struct dtv_property props[] = {
  89         { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },
  90         { .cmd = DTV_FREQUENCY,       .u.data = 651000000 },
  91         { .cmd = DTV_MODULATION,      .u.data = QAM_256 },
  92         { .cmd = DTV_INVERSION,       .u.data = INVERSION_AUTO },
  93         { .cmd = DTV_SYMBOL_RATE,     .u.data = 5217000 },
  94         { .cmd = DTV_INNER_FEC,       .u.data = FEC_3_4 },
  95         { .cmd = DTV_TUNE }
  96     };
  97
  98     static struct dtv_properties dtv_prop = {
  99         .num = 6, .props = props
 100     };
 101
 102     int main(void)
 103     {
 104         int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);
 105
 106         if (!fd) {
 107             perror ("open");
 108             return -1;
 109         }
 110         if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {
 111             perror("ioctl");
 112             return -1;
 113         }
 114         printf("Frontend set\\n");
 115         return 0;
 116     }
 117
 118 .. attention:: While it is possible to directly call the Kernel code like the
 119    above example, it is strongly recommended to use
 120    `libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it
 121    provides abstraction to work with the supported digital TV standards and
 122    provides methods for usual operations like program scanning and to
 123    read/write channel descriptor files.
 124
 125 .. toctree::
 126     :maxdepth: 1
 127
 128     fe_property_parameters
 129     frontend-stat-properties
 130     frontend-property-terrestrial-systems
 131     frontend-property-cable-systems
 132     frontend-property-satellite-systems
 133     frontend-header