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

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_S_HW_FREQ_SEEK:
   5
   6 ***************************
   7 ioctl VIDIOC_S_HW_FREQ_SEEK
   8 ***************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_S_HW_FREQ_SEEK
  19
  20 ``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)``
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :c:func:`open()`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`v4l2_hw_freq_seek`.
  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 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
  62
  63 .. c:type:: v4l2_hw_freq_seek
  64
  65 .. flat-table:: struct v4l2_hw_freq_seek
  66     :header-rows:  0
  67     :stub-columns: 0
  68     :widths:       1 1 2
  69
  70     * - __u32
  71       - ``tuner``
  72       - The tuner index number. This is the same value as in the struct
  73         :c:type:`v4l2_input` ``tuner`` field and the struct
  74         :c:type:`v4l2_tuner` ``index`` field.
  75     * - __u32
  76       - ``type``
  77       - The tuner type. This is the same value as in the struct
  78         :c:type:`v4l2_tuner` ``type`` field. See
  79         :c:type:`v4l2_tuner_type`
  80     * - __u32
  81       - ``seek_upward``
  82       - If non-zero, seek upward from the current frequency, else seek
  83         downward.
  84     * - __u32
  85       - ``wrap_around``
  86       - If non-zero, wrap around when at the end of the frequency range,
  87         else stop seeking. The struct :c:type:`v4l2_tuner`
  88         ``capability`` field will tell you what the hardware supports.
  89     * - __u32
  90       - ``spacing``
  91       - If non-zero, defines the hardware seek resolution in Hz. The
  92         driver selects the nearest value that is supported by the device.
  93         If spacing is zero a reasonable default value is used.
  94     * - __u32
  95       - ``rangelow``
  96       - If non-zero, the lowest tunable frequency of the band to search in
  97         units of 62.5 kHz, or if the struct
  98         :c:type:`v4l2_tuner` ``capability`` field has the
  99         ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
 100         struct :c:type:`v4l2_tuner` ``capability`` field has
 101         the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
 102         ``rangelow`` is zero a reasonable default value is used.
 103     * - __u32
 104       - ``rangehigh``
 105       - If non-zero, the highest tunable frequency of the band to search
 106         in units of 62.5 kHz, or if the struct
 107         :c:type:`v4l2_tuner` ``capability`` field has the
 108         ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
 109         struct :c:type:`v4l2_tuner` ``capability`` field has
 110         the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
 111         ``rangehigh`` is zero a reasonable default value is used.
 112     * - __u32
 113       - ``reserved``\ [5]
 114       - Reserved for future extensions. Applications must set the array to
 115         zero.
 116
 117 Return Value
 118 ============
 119
 120 On success 0 is returned, on error -1 and the ``errno`` variable is set
 121 appropriately. The generic error codes are described at the
 122 :ref:`Generic Error Codes <gen-errors>` chapter.
 123
 124 EINVAL
 125     The ``tuner`` index is out of bounds, the ``wrap_around`` value is
 126     not supported or one of the values in the ``type``, ``rangelow`` or
 127     ``rangehigh`` fields is wrong.
 128
 129 EAGAIN
 130     Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
 131     non-blocking mode.
 132
 133 ENODATA
 134     The hardware seek found no channels.
 135
 136 EBUSY
 137     Another hardware seek is already in progress.