Documentation/media/uapi/v4l/tuner.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _tuner:
   4
   5 *********************
   6 Tuners and Modulators
   7 *********************
   8
   9
  10 Tuners
  11 ======
  12
  13 Video input devices can have one or more tuners demodulating a RF
  14 signal. Each tuner is associated with one or more video inputs,
  15 depending on the number of RF connectors on the tuner. The ``type``
  16 field of the respective struct :c:type:`v4l2_input`
  17 returned by the :ref:`VIDIOC_ENUMINPUT` ioctl is
  18 set to ``V4L2_INPUT_TYPE_TUNER`` and its ``tuner`` field contains the
  19 index number of the tuner.
  20
  21 Radio input devices have exactly one tuner with index zero, no video
  22 inputs.
  23
  24 To 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
  27 struct :c:type:`v4l2_tuner` returned by :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>`
  28 also contains signal status information applicable when the tuner of the
  29 current 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 at all. 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
  41 Modulators
  42 ==========
  43
  44 Video output devices can have one or more modulators, uh, modulating a
  45 video signal for radiation or connection to the antenna input of a TV
  46 set or video recorder. Each modulator is associated with one or more
  47 video outputs, depending on the number of RF connectors on the
  48 modulator. 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
  52 index number of the modulator.
  53
  54 Radio output devices have exactly one modulator with index zero, no
  55 video outputs.
  56
  57 A video or radio device cannot support both a tuner and a modulator. Two
  58 separate device nodes will have to be used for such hardware, one that
  59 supports the tuner functionality and one that supports the modulator
  60 functionality. The reason is a limitation with the
  61 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl where you
  62 cannot specify whether the frequency is for a tuner or a modulator.
  63
  64 To 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
  68 is more than one at all. The modulator is solely determined by the
  69 current 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
  73 one or more modulators.
  74
  75
  76 Radio Frequency
  77 ===============
  78
  79 To get and set the tuner or modulator radio frequency applications use
  80 the :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
  81 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl which both take
  82 a pointer to a struct :c:type:`v4l2_frequency`. These
  83 ioctls are used for TV and radio devices alike. Drivers must support
  84 both ioctls when the tuner or modulator ioctls are supported, or when
  85 the device is a radio device.