Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_S_HW_FREQ_SEEK:
   4
   5 ***************************
   6 ioctl VIDIOC_S_HW_FREQ_SEEK
   7 ***************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_hw_freq_seek *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_S_HW_FREQ_SEEK
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 Start a hardware frequency seek from the current frequency. To do this
  37 applications initialize the ``tuner``, ``type``, ``seek_upward``,
  38 ``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
  39 zero out the ``reserved`` array of a struct
  40 :ref:`v4l2_hw_freq_seek <v4l2-hw-freq-seek>` and call the
  41 ``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.
  42
  43 The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
  44 to tell the driver to search a specific band. If the struct
  45 :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
  46 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
  47 within one of the bands returned by
  48 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
  49 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
  50 must exactly match those of one of the bands returned by
  51 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
  52 current frequency of the tuner does not fall within the selected band it
  53 will be clamped to fit in the band before the seek is started.
  54
  55 If an error is returned, then the original frequency will be restored.
  56
  57 This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
  58 set.
  59
  60 If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
  61 error code is returned and no seek takes place.
  62
  63
  64 .. _v4l2-hw-freq-seek:
  65
  66 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  67
  68 .. flat-table:: struct v4l2_hw_freq_seek
  69     :header-rows:  0
  70     :stub-columns: 0
  71     :widths:       1 1 2
  72
  73
  74     -  .. row 1
  75
  76        -  __u32
  77
  78        -  ``tuner``
  79
  80        -  The tuner index number. This is the same value as in the struct
  81           :ref:`v4l2_input <v4l2-input>` ``tuner`` field and the struct
  82           :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field.
  83
  84     -  .. row 2
  85
  86        -  __u32
  87
  88        -  ``type``
  89
  90        -  The tuner type. This is the same value as in the struct
  91           :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. See
  92           :ref:`v4l2-tuner-type`
  93
  94     -  .. row 3
  95
  96        -  __u32
  97
  98        -  ``seek_upward``
  99
 100        -  If non-zero, seek upward from the current frequency, else seek
 101           downward.
 102
 103     -  .. row 4
 104
 105        -  __u32
 106
 107        -  ``wrap_around``
 108
 109        -  If non-zero, wrap around when at the end of the frequency range,
 110           else stop seeking. The struct :ref:`v4l2_tuner <v4l2-tuner>`
 111           ``capability`` field will tell you what the hardware supports.
 112
 113     -  .. row 5
 114
 115        -  __u32
 116
 117        -  ``spacing``
 118
 119        -  If non-zero, defines the hardware seek resolution in Hz. The
 120           driver selects the nearest value that is supported by the device.
 121           If spacing is zero a reasonable default value is used.
 122
 123     -  .. row 6
 124
 125        -  __u32
 126
 127        -  ``rangelow``
 128
 129        -  If non-zero, the lowest tunable frequency of the band to search in
 130           units of 62.5 kHz, or if the struct
 131           :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
 132           ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
 133           struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has
 134           the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
 135           ``rangelow`` is zero a reasonable default value is used.
 136
 137     -  .. row 7
 138
 139        -  __u32
 140
 141        -  ``rangehigh``
 142
 143        -  If non-zero, the highest tunable frequency of the band to search
 144           in units of 62.5 kHz, or if the struct
 145           :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
 146           ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
 147           struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has
 148           the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
 149           ``rangehigh`` is zero a reasonable default value is used.
 150
 151     -  .. row 8
 152
 153        -  __u32
 154
 155        -  ``reserved``\ [5]
 156
 157        -  Reserved for future extensions. Applications must set the array to
 158           zero.
 159
 160
 161 Return Value
 162 ============
 163
 164 On success 0 is returned, on error -1 and the ``errno`` variable is set
 165 appropriately. The generic error codes are described at the
 166 :ref:`Generic Error Codes <gen-errors>` chapter.
 167
 168 EINVAL
 169     The ``tuner`` index is out of bounds, the ``wrap_around`` value is
 170     not supported or one of the values in the ``type``, ``rangelow`` or
 171     ``rangehigh`` fields is wrong.
 172
 173 EAGAIN
 174     Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
 175     non-blocking mode.
 176
 177 ENODATA
 178     The hardware seek found no channels.
 179
 180 EBUSY
 181     Another hardware seek is already in progress.