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.. _tuner:
11
12*********************
13Tuners and Modulators
14*********************
15
16
17Tuners
18======
19
20Video input devices can have one or more tuners demodulating a RF
21signal. Each tuner is associated with one or more video inputs,
22depending on the number of RF connectors on the tuner. The ``type``
23field of the respective struct :c:type:`v4l2_input`
24returned by the :ref:`VIDIOC_ENUMINPUT` ioctl is
25set to ``V4L2_INPUT_TYPE_TUNER`` and its ``tuner`` field contains the
26index number of the tuner.
27
28Radio input devices have exactly one tuner with index zero, no video
29inputs.
30
31To query and change tuner properties applications use the
32:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
33:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` ioctls, respectively. The
34struct :c:type:`v4l2_tuner` returned by :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>`
35also contains signal status information applicable when the tuner of the
36current video or radio input is queried.
37
38.. note::
39
40   :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` does not switch the
41   current tuner, when there is more than one. The tuner is solely
42   determined by the current video input. Drivers must support both ioctls
43   and set the ``V4L2_CAP_TUNER`` flag in the struct :c:type:`v4l2_capability`
44   returned by the :ref:`VIDIOC_QUERYCAP` ioctl when the
45   device has one or more tuners.
46
47
48Modulators
49==========
50
51Video output devices can have one or more modulators, that modulate a
52video signal for radiation or connection to the antenna input of a TV
53set or video recorder. Each modulator is associated with one or more
54video outputs, depending on the number of RF connectors on the
55modulator. The ``type`` field of the respective struct
56:c:type:`v4l2_output` returned by the
57:ref:`VIDIOC_ENUMOUTPUT` ioctl is set to
58``V4L2_OUTPUT_TYPE_MODULATOR`` and its ``modulator`` field contains the
59index number of the modulator.
60
61Radio output devices have exactly one modulator with index zero, no
62video outputs.
63
64A video or radio device cannot support both a tuner and a modulator. Two
65separate device nodes will have to be used for such hardware, one that
66supports the tuner functionality and one that supports the modulator
67functionality. The reason is a limitation with the
68:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl where you
69cannot specify whether the frequency is for a tuner or a modulator.
70
71To query and change modulator properties applications use the
72:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` and
73:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Note that
74:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` does not switch the current modulator, when there
75is more than one at all. The modulator is solely determined by the
76current video output. Drivers must support both ioctls and set the
77``V4L2_CAP_MODULATOR`` flag in the struct
78:c:type:`v4l2_capability` returned by the
79:ref:`VIDIOC_QUERYCAP` ioctl when the device has
80one or more modulators.
81
82
83Radio Frequency
84===============
85
86To get and set the tuner or modulator radio frequency applications use
87the :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
88:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl which both take
89a pointer to a struct :c:type:`v4l2_frequency`. These
90ioctls are used for TV and radio devices alike. Drivers must support
91both ioctls when the tuner or modulator ioctls are supported, or when
92the device is a radio device.
93