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