1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L 2 .. c:namespace:: V4L
3 3
4 .. _VIDIOC_S_HW_FREQ_SEEK: 4 .. _VIDIOC_S_HW_FREQ_SEEK:
5 5
6 *************************** 6 ***************************
7 ioctl VIDIOC_S_HW_FREQ_SEEK 7 ioctl VIDIOC_S_HW_FREQ_SEEK
8 *************************** 8 ***************************
9 9
10 Name 10 Name
11 ==== 11 ====
12 12
13 VIDIOC_S_HW_FREQ_SEEK - Perform a hardware fre 13 VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek
14 14
15 Synopsis 15 Synopsis
16 ======== 16 ========
17 17
18 .. c:macro:: VIDIOC_S_HW_FREQ_SEEK 18 .. c:macro:: VIDIOC_S_HW_FREQ_SEEK
19 19
20 ``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, str 20 ``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)``
21 21
22 Arguments 22 Arguments
23 ========= 23 =========
24 24
25 ``fd`` 25 ``fd``
26 File descriptor returned by :c:func:`open( 26 File descriptor returned by :c:func:`open()`.
27 27
28 ``argp`` 28 ``argp``
29 Pointer to struct :c:type:`v4l2_hw_freq_se 29 Pointer to struct :c:type:`v4l2_hw_freq_seek`.
30 30
31 Description 31 Description
32 =========== 32 ===========
33 33
34 Start a hardware frequency seek from the curre 34 Start a hardware frequency seek from the current frequency. To do this
35 applications initialize the ``tuner``, ``type` 35 applications initialize the ``tuner``, ``type``, ``seek_upward``,
36 ``wrap_around``, ``spacing``, ``rangelow`` and 36 ``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
37 zero out the ``reserved`` array of a struct 37 zero out the ``reserved`` array of a struct
38 :c:type:`v4l2_hw_freq_seek` and call the 38 :c:type:`v4l2_hw_freq_seek` and call the
39 ``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer 39 ``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.
40 40
41 The ``rangelow`` and ``rangehigh`` fields can 41 The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
42 to tell the driver to search a specific band. 42 to tell the driver to search a specific band. If the struct
43 :c:type:`v4l2_tuner` ``capability`` field has 43 :c:type:`v4l2_tuner` ``capability`` field has the
44 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, t 44 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
45 within one of the bands returned by 45 within one of the bands returned by
46 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the 46 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
47 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not 47 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
48 must exactly match those of one of the bands r 48 must exactly match those of one of the bands returned by
49 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the 49 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
50 current frequency of the tuner does not fall w 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 51 will be clamped to fit in the band before the seek is started.
52 52
53 If an error is returned, then the original fre 53 If an error is returned, then the original frequency will be restored.
54 54
55 This ioctl is supported if the ``V4L2_CAP_HW_F 55 This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
56 set. 56 set.
57 57
58 If this ioctl is called from a non-blocking fi 58 If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
59 error code is returned and no seek takes place 59 error code is returned and no seek takes place.
60 60
61 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm 61 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
62 62
63 .. c:type:: v4l2_hw_freq_seek 63 .. c:type:: v4l2_hw_freq_seek
64 64
65 .. flat-table:: struct v4l2_hw_freq_seek 65 .. flat-table:: struct v4l2_hw_freq_seek
66 :header-rows: 0 66 :header-rows: 0
67 :stub-columns: 0 67 :stub-columns: 0
68 :widths: 1 1 2 68 :widths: 1 1 2
69 69
70 * - __u32 70 * - __u32
71 - ``tuner`` 71 - ``tuner``
72 - The tuner index number. This is the sa 72 - The tuner index number. This is the same value as in the struct
73 :c:type:`v4l2_input` ``tuner`` field a 73 :c:type:`v4l2_input` ``tuner`` field and the struct
74 :c:type:`v4l2_tuner` ``index`` field. 74 :c:type:`v4l2_tuner` ``index`` field.
75 * - __u32 75 * - __u32
76 - ``type`` 76 - ``type``
77 - The tuner type. This is the same value 77 - The tuner type. This is the same value as in the struct
78 :c:type:`v4l2_tuner` ``type`` field. S 78 :c:type:`v4l2_tuner` ``type`` field. See
79 :c:type:`v4l2_tuner_type` 79 :c:type:`v4l2_tuner_type`
80 * - __u32 80 * - __u32
81 - ``seek_upward`` 81 - ``seek_upward``
82 - If non-zero, seek upward from the curr 82 - If non-zero, seek upward from the current frequency, else seek
83 downward. 83 downward.
84 * - __u32 84 * - __u32
85 - ``wrap_around`` 85 - ``wrap_around``
86 - If non-zero, wrap around when at the e 86 - If non-zero, wrap around when at the end of the frequency range,
87 else stop seeking. The struct :c:type: 87 else stop seeking. The struct :c:type:`v4l2_tuner`
88 ``capability`` field will tell you wha 88 ``capability`` field will tell you what the hardware supports.
89 * - __u32 89 * - __u32
90 - ``spacing`` 90 - ``spacing``
91 - If non-zero, defines the hardware seek 91 - If non-zero, defines the hardware seek resolution in Hz. The
92 driver selects the nearest value that 92 driver selects the nearest value that is supported by the device.
93 If spacing is zero a reasonable defaul 93 If spacing is zero a reasonable default value is used.
94 * - __u32 94 * - __u32
95 - ``rangelow`` 95 - ``rangelow``
96 - If non-zero, the lowest tunable freque 96 - If non-zero, the lowest tunable frequency of the band to search in
97 units of 62.5 kHz, or if the struct 97 units of 62.5 kHz, or if the struct
98 :c:type:`v4l2_tuner` ``capability`` fi 98 :c:type:`v4l2_tuner` ``capability`` field has the
99 ``V4L2_TUNER_CAP_LOW`` flag set, in un 99 ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
100 struct :c:type:`v4l2_tuner` ``capabili 100 struct :c:type:`v4l2_tuner` ``capability`` field has
101 the ``V4L2_TUNER_CAP_1HZ`` flag set, i 101 the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
102 ``rangelow`` is zero a reasonable defa 102 ``rangelow`` is zero a reasonable default value is used.
103 * - __u32 103 * - __u32
104 - ``rangehigh`` 104 - ``rangehigh``
105 - If non-zero, the highest tunable frequ 105 - If non-zero, the highest tunable frequency of the band to search
106 in units of 62.5 kHz, or if the struct 106 in units of 62.5 kHz, or if the struct
107 :c:type:`v4l2_tuner` ``capability`` fi 107 :c:type:`v4l2_tuner` ``capability`` field has the
108 ``V4L2_TUNER_CAP_LOW`` flag set, in un 108 ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
109 struct :c:type:`v4l2_tuner` ``capabili 109 struct :c:type:`v4l2_tuner` ``capability`` field has
110 the ``V4L2_TUNER_CAP_1HZ`` flag set, i 110 the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
111 ``rangehigh`` is zero a reasonable def 111 ``rangehigh`` is zero a reasonable default value is used.
112 * - __u32 112 * - __u32
113 - ``reserved``\ [5] 113 - ``reserved``\ [5]
114 - Reserved for future extensions. Applic 114 - Reserved for future extensions. Applications must set the array to
115 zero. 115 zero.
116 116
117 Return Value 117 Return Value
118 ============ 118 ============
119 119
120 On success 0 is returned, on error -1 and the 120 On success 0 is returned, on error -1 and the ``errno`` variable is set
121 appropriately. The generic error codes are des 121 appropriately. The generic error codes are described at the
122 :ref:`Generic Error Codes <gen-errors>` chapte 122 :ref:`Generic Error Codes <gen-errors>` chapter.
123 123
124 EINVAL 124 EINVAL
125 The ``tuner`` index is out of bounds, the 125 The ``tuner`` index is out of bounds, the ``wrap_around`` value is
126 not supported or one of the values in the 126 not supported or one of the values in the ``type``, ``rangelow`` or
127 ``rangehigh`` fields is wrong. 127 ``rangehigh`` fields is wrong.
128 128
129 EAGAIN 129 EAGAIN
130 Attempted to call ``VIDIOC_S_HW_FREQ_SEEK` 130 Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
131 non-blocking mode. 131 non-blocking mode.
132 132
133 ENODATA 133 ENODATA
134 The hardware seek found no channels. 134 The hardware seek found no channels.
135 135
136 EBUSY 136 EBUSY
137 Another hardware seek is already in progre 137 Another hardware seek is already in progress.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.