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