1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
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 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
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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.