Documentation/media/uapi/dvb/dvbproperty.rst

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