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