linux-stable/Documentation/media/uapi/dvb/dvbproperty.rst

.. -*- coding: utf-8; mode: rst -*-

.. _frontend-properties:

DVB Frontend properties
=======================

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.

In the past (up to DVB API version 3), 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.

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

.. 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 suport or a very limited
      support to new standards and/or new hardware.

   3. Nowadays, most frontends support multiple delivery systems.
      Only with DVB v5 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.

Example: with the properties based approach, in order to set the tuner
to 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`.

.. _dtv-prop-example:

Example: Setting digital TV frontend properties
===============================================

.. code-block:: c

    #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;
    }

.. 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

    dtv-stats
    dtv-fe-stats
    dtv-property
    dtv-properties
    dvbproperty-006
    fe_property_parameters
    frontend-stat-properties
    frontend-property-terrestrial-systems
    frontend-property-cable-systems
    frontend-property-satellite-systems