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