1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _frontend-properties:
4
5**************
6Property types
7**************
8
9Tuning into a Digital TV physical channel and starting decoding it
10requires changing a set of parameters, in order to control the tuner,
11the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
12antenna subsystem via Satellite Equipment Control - SEC (on satellite
13systems). The actual parameters are specific to each particular digital
14TV standards, and may change as the digital TV specs evolves.
15
16In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a
17union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and
18ATSC delivery systems grouped there. The problem is that, as the second
19generation standards appeared, the size of such union was not big
20enough to group the structs that would be required for those new
21standards. Also, extending it would break userspace.
22
23So, the legacy union/struct based approach was deprecated, in favor
24of a properties set approach. On such approach,
25:ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>` are used
26to setup the frontend and read its status.
27
28The actual action is determined by a set of dtv_property cmd/data pairs.
29With one single ioctl, is possible to get/set up to 64 properties.
30
31This section describes the new and recommended way to set the frontend,
32with 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 support 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
51at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.217
52Mbauds, 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
69The 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
127