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