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

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_S_HW_FREQ_SEEK:
  11
  12 ***************************
  13 ioctl VIDIOC_S_HW_FREQ_SEEK
  14 ***************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp )
  26     :name: VIDIOC_S_HW_FREQ_SEEK
  27
  28
  29 Arguments
  30 =========
  31
  32 ``fd``
  33     File descriptor returned by :ref:`open() <func-open>`.
  34
  35 ``argp``
  36     Pointer to struct :c:type:`v4l2_hw_freq_seek`.
  37
  38
  39 Description
  40 ===========
  41
  42 Start a hardware frequency seek from the current frequency. To do this
  43 applications initialize the ``tuner``, ``type``, ``seek_upward``,
  44 ``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
  45 zero out the ``reserved`` array of a struct
  46 :c:type:`v4l2_hw_freq_seek` and call the
  47 ``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.
  48
  49 The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
  50 to tell the driver to search a specific band. If the struct
  51 :c:type:`v4l2_tuner` ``capability`` field has the
  52 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
  53 within one of the bands returned by
  54 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
  55 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
  56 must exactly match those of one of the bands returned by
  57 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
  58 current frequency of the tuner does not fall within the selected band it
  59 will be clamped to fit in the band before the seek is started.
  60
  61 If an error is returned, then the original frequency will be restored.
  62
  63 This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
  64 set.
  65
  66 If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
  67 error code is returned and no seek takes place.
  68
  69
  70 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  71
  72 .. c:type:: v4l2_hw_freq_seek
  73
  74 .. flat-table:: struct v4l2_hw_freq_seek
  75     :header-rows:  0
  76     :stub-columns: 0
  77     :widths:       1 1 2
  78
  79     * - __u32
  80       - ``tuner``
  81       - The tuner index number. This is the same value as in the struct
  82         :c:type:`v4l2_input` ``tuner`` field and the struct
  83         :c:type:`v4l2_tuner` ``index`` field.
  84     * - __u32
  85       - ``type``
  86       - The tuner type. This is the same value as in the struct
  87         :c:type:`v4l2_tuner` ``type`` field. See
  88         :c:type:`v4l2_tuner_type`
  89     * - __u32
  90       - ``seek_upward``
  91       - If non-zero, seek upward from the current frequency, else seek
  92         downward.
  93     * - __u32
  94       - ``wrap_around``
  95       - If non-zero, wrap around when at the end of the frequency range,
  96         else stop seeking. The struct :c:type:`v4l2_tuner`
  97         ``capability`` field will tell you what the hardware supports.
  98     * - __u32
  99       - ``spacing``
 100       - If non-zero, defines the hardware seek resolution in Hz. The
 101         driver selects the nearest value that is supported by the device.
 102         If spacing is zero a reasonable default value is used.
 103     * - __u32
 104       - ``rangelow``
 105       - If non-zero, the lowest tunable frequency of the band to search in
 106         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         ``rangelow`` is zero a reasonable default value is used.
 112     * - __u32
 113       - ``rangehigh``
 114       - If non-zero, the highest tunable frequency of the band to search
 115         in units of 62.5 kHz, or if the struct
 116         :c:type:`v4l2_tuner` ``capability`` field has the
 117         ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
 118         struct :c:type:`v4l2_tuner` ``capability`` field has
 119         the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
 120         ``rangehigh`` is zero a reasonable default value is used.
 121     * - __u32
 122       - ``reserved``\ [5]
 123       - Reserved for future extensions. Applications must set the array to
 124         zero.
 125
 126
 127 Return Value
 128 ============
 129
 130 On success 0 is returned, on error -1 and the ``errno`` variable is set
 131 appropriately. The generic error codes are described at the
 132 :ref:`Generic Error Codes <gen-errors>` chapter.
 133
 134 EINVAL
 135     The ``tuner`` index is out of bounds, the ``wrap_around`` value is
 136     not supported or one of the values in the ``type``, ``rangelow`` or
 137     ``rangehigh`` fields is wrong.
 138
 139 EAGAIN
 140     Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
 141     non-blocking mode.
 142
 143 ENODATA
 144     The hardware seek found no channels.
 145
 146 EBUSY
 147     Another hardware seek is already in progress.