Debian Codegraph @

Documentation/userspace-api/media/v4l/tuner.rst

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