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_G_TUNER: 4 .. _VIDIOC_G_TUNER:
5 5
6 ************************************ 6 ************************************
7 ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER 7 ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
8 ************************************ 8 ************************************
9 9
10 Name 10 Name
11 ==== 11 ====
12 12
13 VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set t 13 VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
14 14
15 Synopsis 15 Synopsis
16 ======== 16 ========
17 17
18 .. c:macro:: VIDIOC_G_TUNER 18 .. c:macro:: VIDIOC_G_TUNER
19 19
20 ``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l 20 ``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)``
21 21
22 .. c:macro:: VIDIOC_S_TUNER 22 .. c:macro:: VIDIOC_S_TUNER
23 23
24 ``int ioctl(int fd, VIDIOC_S_TUNER, const stru 24 ``int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)``
25 25
26 Arguments 26 Arguments
27 ========= 27 =========
28 28
29 ``fd`` 29 ``fd``
30 File descriptor returned by :c:func:`open( 30 File descriptor returned by :c:func:`open()`.
31 31
32 ``argp`` 32 ``argp``
33 Pointer to struct :c:type:`v4l2_tuner`. 33 Pointer to struct :c:type:`v4l2_tuner`.
34 34
35 Description 35 Description
36 =========== 36 ===========
37 37
38 To query the attributes of a tuner application 38 To query the attributes of a tuner applications initialize the ``index``
39 field and zero out the ``reserved`` array of a 39 field and zero out the ``reserved`` array of a struct
40 :c:type:`v4l2_tuner` and call the ``VIDIOC_G_T 40 :c:type:`v4l2_tuner` and call the ``VIDIOC_G_TUNER`` ioctl
41 with a pointer to this structure. Drivers fill 41 with a pointer to this structure. Drivers fill the rest of the structure
42 or return an ``EINVAL`` error code when the in 42 or return an ``EINVAL`` error code when the index is out of bounds. To
43 enumerate all tuners applications shall begin 43 enumerate all tuners applications shall begin at index zero,
44 incrementing by one until the driver returns ` 44 incrementing by one until the driver returns ``EINVAL``.
45 45
46 Tuners have two writable properties, the audio 46 Tuners have two writable properties, the audio mode and the radio
47 frequency. To change the audio mode, applicati 47 frequency. To change the audio mode, applications initialize the
48 ``index``, ``audmode`` and ``reserved`` fields 48 ``index``, ``audmode`` and ``reserved`` fields and call the
49 ``VIDIOC_S_TUNER`` ioctl. This will *not* chan 49 ``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,
50 which is determined by the current video input 50 which is determined by the current video input. Drivers may choose a
51 different audio mode if the requested mode is 51 different audio mode if the requested mode is invalid or unsupported.
52 Since this is a write-only ioctl, it does not 52 Since this is a write-only ioctl, it does not return the actually
53 selected audio mode. 53 selected audio mode.
54 54
55 :ref:`SDR <sdr>` specific tuner types are ``V4 55 :ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and
56 ``V4L2_TUNER_RF``. For SDR devices ``audmode`` 56 ``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized
57 to zero. The term 'tuner' means SDR receiver i 57 to zero. The term 'tuner' means SDR receiver in this context.
58 58
59 To change the radio frequency the 59 To change the radio frequency the
60 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` 60 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
61 61
62 .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{7.0c 62 .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{7.0cm}|p{5.8cm}|
63 63
64 .. c:type:: v4l2_tuner 64 .. c:type:: v4l2_tuner
65 65
66 .. cssclass:: longtable 66 .. cssclass:: longtable
67 67
68 .. flat-table:: struct v4l2_tuner 68 .. flat-table:: struct v4l2_tuner
69 :header-rows: 0 69 :header-rows: 0
70 :stub-columns: 0 70 :stub-columns: 0
71 71
72 * - __u32 72 * - __u32
73 - ``index`` 73 - ``index``
74 - :cspan:`1` Identifies the tuner, set b 74 - :cspan:`1` Identifies the tuner, set by the application.
75 * - __u8 75 * - __u8
76 - ``name``\ [32] 76 - ``name``\ [32]
77 - :cspan:`1` 77 - :cspan:`1`
78 78
79 Name of the tuner, a NUL-terminated AS 79 Name of the tuner, a NUL-terminated ASCII string.
80 80
81 This information is intended for the u 81 This information is intended for the user.
82 * - __u32 82 * - __u32
83 - ``type`` 83 - ``type``
84 - :cspan:`1` Type of the tuner, see :c:t 84 - :cspan:`1` Type of the tuner, see :c:type:`v4l2_tuner_type`.
85 * - __u32 85 * - __u32
86 - ``capability`` 86 - ``capability``
87 - :cspan:`1` 87 - :cspan:`1`
88 88
89 Tuner capability flags, see :ref:`tune 89 Tuner capability flags, see :ref:`tuner-capability`. Audio flags
90 indicate the ability to decode audio s 90 indicate the ability to decode audio subprograms. They will *not*
91 change, for example with the current v 91 change, for example with the current video standard.
92 92
93 When the structure refers to a radio t 93 When the structure refers to a radio tuner the
94 ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER 94 ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and
95 ``V4L2_TUNER_CAP_NORM`` flags can't be 95 ``V4L2_TUNER_CAP_NORM`` flags can't be used.
96 96
97 If multiple frequency bands are suppor 97 If multiple frequency bands are supported, then ``capability`` is
98 the union of all ``capability`` fields 98 the union of all ``capability`` fields of each struct
99 :c:type:`v4l2_frequency_band`. 99 :c:type:`v4l2_frequency_band`.
100 * - __u32 100 * - __u32
101 - ``rangelow`` 101 - ``rangelow``
102 - :cspan:`1` The lowest tunable frequenc 102 - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or
103 if the ``capability`` flag ``V4L2_TUNE 103 if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
104 of 62.5 Hz, or if the ``capability`` f 104 of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ``
105 is set, in units of 1 Hz. If multiple 105 is set, in units of 1 Hz. If multiple frequency bands are
106 supported, then ``rangelow`` is the lo 106 supported, then ``rangelow`` is the lowest frequency of all the
107 frequency bands. 107 frequency bands.
108 * - __u32 108 * - __u32
109 - ``rangehigh`` 109 - ``rangehigh``
110 - :cspan:`1` The highest tunable frequen 110 - :cspan:`1` The highest tunable frequency in units of 62.5 kHz,
111 or if the ``capability`` flag ``V4L2_T 111 or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
112 units of 62.5 Hz, or if the ``capabili 112 units of 62.5 Hz, or if the ``capability`` flag
113 ``V4L2_TUNER_CAP_1HZ`` is set, in unit 113 ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple
114 frequency bands are supported, then `` 114 frequency bands are supported, then ``rangehigh`` is the highest
115 frequency of all the frequency bands. 115 frequency of all the frequency bands.
116 * - __u32 116 * - __u32
117 - ``rxsubchans`` 117 - ``rxsubchans``
118 - :cspan:`1` 118 - :cspan:`1`
119 119
120 Some tuners or audio decoders can dete 120 Some tuners or audio decoders can determine the received audio
121 subprograms by analyzing audio carrier 121 subprograms by analyzing audio carriers, pilot tones or other
122 indicators. To pass this information d 122 indicators. To pass this information drivers set flags defined in
123 :ref:`tuner-rxsubchans` in this field. 123 :ref:`tuner-rxsubchans` in this field. For example:
124 * - 124 * -
125 - 125 -
126 - ``V4L2_TUNER_SUB_MONO`` 126 - ``V4L2_TUNER_SUB_MONO``
127 - receiving mono audio 127 - receiving mono audio
128 * - 128 * -
129 - 129 -
130 - ``STEREO | SAP`` 130 - ``STEREO | SAP``
131 - receiving stereo audio and a secondary 131 - receiving stereo audio and a secondary audio program
132 * - 132 * -
133 - 133 -
134 - ``MONO | STEREO`` 134 - ``MONO | STEREO``
135 - receiving mono or stereo audio, the ha 135 - receiving mono or stereo audio, the hardware cannot distinguish
136 * - 136 * -
137 - 137 -
138 - ``LANG1 | LANG2`` 138 - ``LANG1 | LANG2``
139 - receiving bilingual audio 139 - receiving bilingual audio
140 * - 140 * -
141 - 141 -
142 - ``MONO | STEREO | LANG1 | LANG2`` 142 - ``MONO | STEREO | LANG1 | LANG2``
143 - receiving mono, stereo or bilingual au 143 - receiving mono, stereo or bilingual audio
144 * - 144 * -
145 - 145 -
146 - :cspan:`1` 146 - :cspan:`1`
147 147
148 When the ``V4L2_TUNER_CAP_STEREO``, `` 148 When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or
149 ``_SAP`` flag is cleared in the ``capa 149 ``_SAP`` flag is cleared in the ``capability`` field, the
150 corresponding ``V4L2_TUNER_SUB_`` flag 150 corresponding ``V4L2_TUNER_SUB_`` flag must not be set here.
151 151
152 This field is valid only if this is th 152 This field is valid only if this is the tuner of the current video
153 input, or when the structure refers to 153 input, or when the structure refers to a radio tuner.
154 * - __u32 154 * - __u32
155 - ``audmode`` 155 - ``audmode``
156 - :cspan:`1` 156 - :cspan:`1`
157 157
158 The selected audio mode, see :ref:`tun 158 The selected audio mode, see :ref:`tuner-audmode` for valid
159 values. The audio mode does not affect 159 values. The audio mode does not affect audio subprogram detection,
160 and like a :ref:`control` it does not 160 and like a :ref:`control` it does not automatically
161 change unless the requested mode is in 161 change unless the requested mode is invalid or unsupported. See
162 :ref:`tuner-matrix` for possible resul 162 :ref:`tuner-matrix` for possible results when the selected and
163 received audio programs do not match. 163 received audio programs do not match.
164 164
165 Currently this is the only field of st 165 Currently this is the only field of struct
166 struct :c:type:`v4l2_tuner` applicatio 166 struct :c:type:`v4l2_tuner` applications can change.
167 * - __u32 167 * - __u32
168 - ``signal`` 168 - ``signal``
169 - :cspan:`1` The signal strength if know 169 - :cspan:`1` The signal strength if known.
170 170
171 Ranging from 0 to 65535. Higher values 171 Ranging from 0 to 65535. Higher values indicate a better signal.
172 * - __s32 172 * - __s32
173 - ``afc`` 173 - ``afc``
174 - :cspan:`1` Automatic frequency control 174 - :cspan:`1` Automatic frequency control.
175 175
176 When the ``afc`` value is negative, th 176 When the ``afc`` value is negative, the frequency is too
177 low, when positive too high. 177 low, when positive too high.
178 * - __u32 178 * - __u32
179 - ``reserved``\ [4] 179 - ``reserved``\ [4]
180 - :cspan:`1` Reserved for future extensi 180 - :cspan:`1` Reserved for future extensions.
181 181
182 Drivers and applications must set the 182 Drivers and applications must set the array to zero.
183 183
184 184
185 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm 185 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
186 186
187 .. c:type:: v4l2_tuner_type 187 .. c:type:: v4l2_tuner_type
188 188
189 .. flat-table:: enum v4l2_tuner_type 189 .. flat-table:: enum v4l2_tuner_type
190 :header-rows: 0 190 :header-rows: 0
191 :stub-columns: 0 191 :stub-columns: 0
192 :widths: 3 1 6 192 :widths: 3 1 6
193 193
194 * - ``V4L2_TUNER_RADIO`` 194 * - ``V4L2_TUNER_RADIO``
195 - 1 195 - 1
196 - Tuner supports radio 196 - Tuner supports radio
197 * - ``V4L2_TUNER_ANALOG_TV`` 197 * - ``V4L2_TUNER_ANALOG_TV``
198 - 2 198 - 2
199 - Tuner supports analog TV 199 - Tuner supports analog TV
200 * - ``V4L2_TUNER_SDR`` 200 * - ``V4L2_TUNER_SDR``
201 - 4 201 - 4
202 - Tuner controls the A/D and/or D/A bloc 202 - Tuner controls the A/D and/or D/A block of a
203 Software Digital Radio (SDR) 203 Software Digital Radio (SDR)
204 * - ``V4L2_TUNER_RF`` 204 * - ``V4L2_TUNER_RF``
205 - 5 205 - 5
206 - Tuner controls the RF part of a Softwa 206 - Tuner controls the RF part of a Software Digital Radio (SDR)
207 207
208 .. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.1cm 208 .. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.1cm}|
209 209
210 .. _tuner-capability: 210 .. _tuner-capability:
211 211
212 .. cssclass:: longtable 212 .. cssclass:: longtable
213 213
214 .. flat-table:: Tuner and Modulator Capability 214 .. flat-table:: Tuner and Modulator Capability Flags
215 :header-rows: 0 215 :header-rows: 0
216 :stub-columns: 0 216 :stub-columns: 0
217 :widths: 3 1 4 217 :widths: 3 1 4
218 218
219 * - ``V4L2_TUNER_CAP_LOW`` 219 * - ``V4L2_TUNER_CAP_LOW``
220 - 0x0001 220 - 0x0001
221 - When set, tuning frequencies are expre 221 - When set, tuning frequencies are expressed in units of 62.5 Hz
222 instead of 62.5 kHz. 222 instead of 62.5 kHz.
223 * - ``V4L2_TUNER_CAP_NORM`` 223 * - ``V4L2_TUNER_CAP_NORM``
224 - 0x0002 224 - 0x0002
225 - This is a multi-standard tuner; the vi 225 - This is a multi-standard tuner; the video standard can or must be
226 switched. (B/G PAL tuners for example 226 switched. (B/G PAL tuners for example are typically not considered
227 multi-standard because the video stand 227 multi-standard because the video standard is automatically
228 determined from the frequency band.) T 228 determined from the frequency band.) The set of supported video
229 standards is available from the struct 229 standards is available from the struct
230 :c:type:`v4l2_input` pointing to this 230 :c:type:`v4l2_input` pointing to this tuner, see the
231 description of ioctl :ref:`VIDIOC_ENUM 231 description of ioctl :ref:`VIDIOC_ENUMINPUT`
232 for details. Only ``V4L2_TUNER_ANALOG_ 232 for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
233 capability. 233 capability.
234 * - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED`` 234 * - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
235 - 0x0004 235 - 0x0004
236 - If set, then this tuner supports the h 236 - If set, then this tuner supports the hardware seek functionality
237 where the seek stops when it reaches t 237 where the seek stops when it reaches the end of the frequency
238 range. 238 range.
239 * - ``V4L2_TUNER_CAP_HWSEEK_WRAP`` 239 * - ``V4L2_TUNER_CAP_HWSEEK_WRAP``
240 - 0x0008 240 - 0x0008
241 - If set, then this tuner supports the h 241 - If set, then this tuner supports the hardware seek functionality
242 where the seek wraps around when it re 242 where the seek wraps around when it reaches the end of the
243 frequency range. 243 frequency range.
244 * - ``V4L2_TUNER_CAP_STEREO`` 244 * - ``V4L2_TUNER_CAP_STEREO``
245 - 0x0010 245 - 0x0010
246 - Stereo audio reception is supported. 246 - Stereo audio reception is supported.
247 * - ``V4L2_TUNER_CAP_LANG1`` 247 * - ``V4L2_TUNER_CAP_LANG1``
248 - 0x0040 248 - 0x0040
249 - Reception of the primary language of a 249 - Reception of the primary language of a bilingual audio program is
250 supported. Bilingual audio is a featur 250 supported. Bilingual audio is a feature of two-channel systems,
251 transmitting the primary language mona 251 transmitting the primary language monaural on the main audio
252 carrier and a secondary language monau 252 carrier and a secondary language monaural on a second carrier.
253 Only ``V4L2_TUNER_ANALOG_TV`` tuners c 253 Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
254 * - ``V4L2_TUNER_CAP_LANG2`` 254 * - ``V4L2_TUNER_CAP_LANG2``
255 - 0x0020 255 - 0x0020
256 - Reception of the secondary language of 256 - Reception of the secondary language of a bilingual audio program
257 is supported. Only ``V4L2_TUNER_ANALOG 257 is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
258 capability. 258 capability.
259 * - ``V4L2_TUNER_CAP_SAP`` 259 * - ``V4L2_TUNER_CAP_SAP``
260 - 0x0020 260 - 0x0020
261 - Reception of a secondary audio program 261 - Reception of a secondary audio program is supported. This is a
262 feature of the BTSC system which accom 262 feature of the BTSC system which accompanies the NTSC video
263 standard. Two audio carriers are avail 263 standard. Two audio carriers are available for mono or stereo
264 transmissions of a primary language, a 264 transmissions of a primary language, and an independent third
265 carrier for a monaural secondary langu 265 carrier for a monaural secondary language. Only
266 ``V4L2_TUNER_ANALOG_TV`` tuners can ha 266 ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
267 267
268 .. note:: 268 .. note::
269 269
270 The ``V4L2_TUNER_CAP_LANG2`` and `` 270 The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP``
271 flags are synonyms. ``V4L2_TUNER_CA 271 flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
272 supports the ``V4L2_STD_NTSC_M`` vi 272 supports the ``V4L2_STD_NTSC_M`` video standard.
273 * - ``V4L2_TUNER_CAP_RDS`` 273 * - ``V4L2_TUNER_CAP_RDS``
274 - 0x0080 274 - 0x0080
275 - RDS capture is supported. This capabil 275 - RDS capture is supported. This capability is only valid for radio
276 tuners. 276 tuners.
277 * - ``V4L2_TUNER_CAP_RDS_BLOCK_IO`` 277 * - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
278 - 0x0100 278 - 0x0100
279 - The RDS data is passed as unparsed RDS 279 - The RDS data is passed as unparsed RDS blocks.
280 * - ``V4L2_TUNER_CAP_RDS_CONTROLS`` 280 * - ``V4L2_TUNER_CAP_RDS_CONTROLS``
281 - 0x0200 281 - 0x0200
282 - The RDS data is parsed by the hardware 282 - The RDS data is parsed by the hardware and set via controls.
283 * - ``V4L2_TUNER_CAP_FREQ_BANDS`` 283 * - ``V4L2_TUNER_CAP_FREQ_BANDS``
284 - 0x0400 284 - 0x0400
285 - The :ref:`VIDIOC_ENUM_FREQ_BANDS` 285 - The :ref:`VIDIOC_ENUM_FREQ_BANDS`
286 ioctl can be used to enumerate the ava 286 ioctl can be used to enumerate the available frequency bands.
287 * - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` 287 * - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``
288 - 0x0800 288 - 0x0800
289 - The range to search when using the har 289 - The range to search when using the hardware seek functionality is
290 programmable, see 290 programmable, see
291 :ref:`VIDIOC_S_HW_FREQ_SEEK` for 291 :ref:`VIDIOC_S_HW_FREQ_SEEK` for
292 details. 292 details.
293 * - ``V4L2_TUNER_CAP_1HZ`` 293 * - ``V4L2_TUNER_CAP_1HZ``
294 - 0x1000 294 - 0x1000
295 - When set, tuning frequencies are expre 295 - When set, tuning frequencies are expressed in units of 1 Hz
296 instead of 62.5 kHz. 296 instead of 62.5 kHz.
297 297
298 298
299 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm 299 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
300 300
301 .. _tuner-rxsubchans: 301 .. _tuner-rxsubchans:
302 302
303 .. flat-table:: Tuner Audio Reception Flags 303 .. flat-table:: Tuner Audio Reception Flags
304 :header-rows: 0 304 :header-rows: 0
305 :stub-columns: 0 305 :stub-columns: 0
306 :widths: 3 1 4 306 :widths: 3 1 4
307 307
308 * - ``V4L2_TUNER_SUB_MONO`` 308 * - ``V4L2_TUNER_SUB_MONO``
309 - 0x0001 309 - 0x0001
310 - The tuner receives a mono audio signal 310 - The tuner receives a mono audio signal.
311 * - ``V4L2_TUNER_SUB_STEREO`` 311 * - ``V4L2_TUNER_SUB_STEREO``
312 - 0x0002 312 - 0x0002
313 - The tuner receives a stereo audio sign 313 - The tuner receives a stereo audio signal.
314 * - ``V4L2_TUNER_SUB_LANG1`` 314 * - ``V4L2_TUNER_SUB_LANG1``
315 - 0x0008 315 - 0x0008
316 - The tuner receives the primary languag 316 - The tuner receives the primary language of a bilingual audio
317 signal. Drivers must clear this flag w 317 signal. Drivers must clear this flag when the current video
318 standard is ``V4L2_STD_NTSC_M``. 318 standard is ``V4L2_STD_NTSC_M``.
319 * - ``V4L2_TUNER_SUB_LANG2`` 319 * - ``V4L2_TUNER_SUB_LANG2``
320 - 0x0004 320 - 0x0004
321 - The tuner receives the secondary langu 321 - The tuner receives the secondary language of a bilingual audio
322 signal (or a second audio program). 322 signal (or a second audio program).
323 * - ``V4L2_TUNER_SUB_SAP`` 323 * - ``V4L2_TUNER_SUB_SAP``
324 - 0x0004 324 - 0x0004
325 - The tuner receives a Second Audio Prog 325 - The tuner receives a Second Audio Program.
326 326
327 .. note:: 327 .. note::
328 328
329 The ``V4L2_TUNER_SUB_LANG2`` and `` 329 The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP``
330 flags are synonyms. The ``V4L2_TUNE 330 flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies
331 when the current video standard is 331 when the current video standard is ``V4L2_STD_NTSC_M``.
332 * - ``V4L2_TUNER_SUB_RDS`` 332 * - ``V4L2_TUNER_SUB_RDS``
333 - 0x0010 333 - 0x0010
334 - The tuner receives an RDS channel. 334 - The tuner receives an RDS channel.
335 335
336 336
337 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm 337 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
338 338
339 .. _tuner-audmode: 339 .. _tuner-audmode:
340 340
341 .. flat-table:: Tuner Audio Modes 341 .. flat-table:: Tuner Audio Modes
342 :header-rows: 0 342 :header-rows: 0
343 :stub-columns: 0 343 :stub-columns: 0
344 :widths: 3 1 4 344 :widths: 3 1 4
345 345
346 * - ``V4L2_TUNER_MODE_MONO`` 346 * - ``V4L2_TUNER_MODE_MONO``
347 - 0 347 - 0
348 - Play mono audio. When the tuner receiv 348 - Play mono audio. When the tuner receives a stereo signal this a
349 down-mix of the left and right channel 349 down-mix of the left and right channel. When the tuner receives a
350 bilingual or SAP signal this mode sele 350 bilingual or SAP signal this mode selects the primary language.
351 * - ``V4L2_TUNER_MODE_STEREO`` 351 * - ``V4L2_TUNER_MODE_STEREO``
352 - 1 352 - 1
353 - Play stereo audio. When the tuner rece 353 - Play stereo audio. When the tuner receives bilingual audio it may
354 play different languages on the left a 354 play different languages on the left and right channel or the
355 primary language is played on both cha 355 primary language is played on both channels.
356 356
357 Playing different languages in this mo 357 Playing different languages in this mode is deprecated. New
358 drivers should do this only in ``MODE_ 358 drivers should do this only in ``MODE_LANG1_LANG2``.
359 359
360 When the tuner receives no stereo sign 360 When the tuner receives no stereo signal or does not support
361 stereo reception the driver shall fall 361 stereo reception the driver shall fall back to ``MODE_MONO``.
362 * - ``V4L2_TUNER_MODE_LANG1`` 362 * - ``V4L2_TUNER_MODE_LANG1``
363 - 3 363 - 3
364 - Play the primary language, mono or ste 364 - Play the primary language, mono or stereo. Only
365 ``V4L2_TUNER_ANALOG_TV`` tuners suppor 365 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
366 * - ``V4L2_TUNER_MODE_LANG2`` 366 * - ``V4L2_TUNER_MODE_LANG2``
367 - 2 367 - 2
368 - Play the secondary language, mono. Whe 368 - Play the secondary language, mono. When the tuner receives no
369 bilingual audio or SAP, or their recep 369 bilingual audio or SAP, or their reception is not supported the
370 driver shall fall back to mono or ster 370 driver shall fall back to mono or stereo mode. Only
371 ``V4L2_TUNER_ANALOG_TV`` tuners suppor 371 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
372 * - ``V4L2_TUNER_MODE_SAP`` 372 * - ``V4L2_TUNER_MODE_SAP``
373 - 2 373 - 2
374 - Play the Second Audio Program. When th 374 - Play the Second Audio Program. When the tuner receives no
375 bilingual audio or SAP, or their recep 375 bilingual audio or SAP, or their reception is not supported the
376 driver shall fall back to mono or ster 376 driver shall fall back to mono or stereo mode. Only
377 ``V4L2_TUNER_ANALOG_TV`` tuners suppor 377 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
378 378
379 .. note:: The ``V4L2_TUNER_MODE_LANG2` 379 .. note:: The ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP``
380 are synonyms. 380 are synonyms.
381 * - ``V4L2_TUNER_MODE_LANG1_LANG2`` 381 * - ``V4L2_TUNER_MODE_LANG1_LANG2``
382 - 4 382 - 4
383 - Play the primary language on the left 383 - Play the primary language on the left channel, the secondary
384 language on the right channel. When th 384 language on the right channel. When the tuner receives no
385 bilingual audio or SAP, it shall fall 385 bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
386 ``MODE_MONO``. Only ``V4L2_TUNER_ANALO 386 ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
387 mode. 387 mode.
388 388
389 .. raw:: latex 389 .. raw:: latex
390 390
391 \scriptsize 391 \scriptsize
392 392
393 .. tabularcolumns:: |p{1.5cm}|p{1.5cm}|p{2.9cm 393 .. tabularcolumns:: |p{1.5cm}|p{1.5cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}|
394 394
395 .. _tuner-matrix: 395 .. _tuner-matrix:
396 396
397 .. flat-table:: Tuner Audio Matrix 397 .. flat-table:: Tuner Audio Matrix
398 :header-rows: 2 398 :header-rows: 2
399 :stub-columns: 0 399 :stub-columns: 0
400 :widths: 7 7 14 14 14 14 400 :widths: 7 7 14 14 14 14
401 401
402 * - 402 * -
403 - :cspan:`4` Selected ``V4L2_TUNER_MODE_ 403 - :cspan:`4` Selected ``V4L2_TUNER_MODE_``
404 * - Received ``V4L2_TUNER_SUB_`` 404 * - Received ``V4L2_TUNER_SUB_``
405 - ``MONO`` 405 - ``MONO``
406 - ``STEREO`` 406 - ``STEREO``
407 - ``LANG1`` 407 - ``LANG1``
408 - ``LANG2 = SAP`` 408 - ``LANG2 = SAP``
409 - ``LANG1_LANG2``\ [#f1]_ 409 - ``LANG1_LANG2``\ [#f1]_
410 * - ``MONO`` 410 * - ``MONO``
411 - Mono 411 - Mono
412 - Mono/Mono 412 - Mono/Mono
413 - Mono 413 - Mono
414 - Mono 414 - Mono
415 - Mono/Mono 415 - Mono/Mono
416 * - ``MONO | SAP`` 416 * - ``MONO | SAP``
417 - Mono 417 - Mono
418 - Mono/Mono 418 - Mono/Mono
419 - Mono 419 - Mono
420 - SAP 420 - SAP
421 - Mono/SAP (preferred) or Mono/Mono 421 - Mono/SAP (preferred) or Mono/Mono
422 * - ``STEREO`` 422 * - ``STEREO``
423 - L+R 423 - L+R
424 - L/R 424 - L/R
425 - Stereo L/R (preferred) or Mono L+R 425 - Stereo L/R (preferred) or Mono L+R
426 - Stereo L/R (preferred) or Mono L+R 426 - Stereo L/R (preferred) or Mono L+R
427 - L/R (preferred) or L+R/L+R 427 - L/R (preferred) or L+R/L+R
428 * - ``STEREO | SAP`` 428 * - ``STEREO | SAP``
429 - L+R 429 - L+R
430 - L/R 430 - L/R
431 - Stereo L/R (preferred) or Mono L+R 431 - Stereo L/R (preferred) or Mono L+R
432 - SAP 432 - SAP
433 - L+R/SAP (preferred) or L/R or L+R/L+R 433 - L+R/SAP (preferred) or L/R or L+R/L+R
434 * - ``LANG1 | LANG2`` 434 * - ``LANG1 | LANG2``
435 - Language 1 435 - Language 1
436 - Lang1/Lang2 (deprecated\ [#f2]_) or La 436 - Lang1/Lang2 (deprecated\ [#f2]_) or Lang1/Lang1
437 - Language 1 437 - Language 1
438 - Language 2 438 - Language 2
439 - Lang1/Lang2 (preferred) or Lang1/Lang1 439 - Lang1/Lang2 (preferred) or Lang1/Lang1
440 440
441 .. raw:: latex 441 .. raw:: latex
442 442
443 \normalsize 443 \normalsize
444 444
445 Return Value 445 Return Value
446 ============ 446 ============
447 447
448 On success 0 is returned, on error -1 and the 448 On success 0 is returned, on error -1 and the ``errno`` variable is set
449 appropriately. The generic error codes are des 449 appropriately. The generic error codes are described at the
450 :ref:`Generic Error Codes <gen-errors>` chapte 450 :ref:`Generic Error Codes <gen-errors>` chapter.
451 451
452 EINVAL 452 EINVAL
453 The struct :c:type:`v4l2_tuner` ``index`` 453 The struct :c:type:`v4l2_tuner` ``index`` is out of
454 bounds. 454 bounds.
455 455
456 .. [#f1] 456 .. [#f1]
457 This mode has been added in Linux 2.6.17 an 457 This mode has been added in Linux 2.6.17 and may not be supported by
458 older drivers. 458 older drivers.
459 459
460 .. [#f2] 460 .. [#f2]
461 Playback of both languages in ``MODE_STEREO 461 Playback of both languages in ``MODE_STEREO`` is deprecated. In the
462 future drivers should produce only the prim 462 future drivers should produce only the primary language in this mode.
463 Applications should request ``MODE_LANG1_LA 463 Applications should request ``MODE_LANG1_LANG2`` to record both
464 languages or a stereo signal. 464 languages or a stereo signal.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.