Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 3 | .. _VIDIOC_G_TUNER: |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 4 | |
| 5 | ************************************ |
| 6 | ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER |
| 7 | ************************************ |
| 8 | |
| 9 | *man VIDIOC_G_TUNER(2)* |
| 10 | |
| 11 | VIDIOC_S_TUNER |
| 12 | Get or set tuner attributes |
| 13 | |
| 14 | |
| 15 | Synopsis |
| 16 | ======== |
| 17 | |
Mauro Carvalho Chehab | b7e67f6 | 2016-07-02 09:49:16 -0300 | [diff] [blame] | 18 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_tuner *argp ) |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 19 | |
Mauro Carvalho Chehab | b7e67f6 | 2016-07-02 09:49:16 -0300 | [diff] [blame] | 20 | .. cpp:function:: int ioctl( int fd, int request, const struct v4l2_tuner *argp ) |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 21 | |
| 22 | Arguments |
| 23 | ========= |
| 24 | |
| 25 | ``fd`` |
| 26 | File descriptor returned by :ref:`open() <func-open>`. |
| 27 | |
| 28 | ``request`` |
| 29 | VIDIOC_G_TUNER, VIDIOC_S_TUNER |
| 30 | |
| 31 | ``argp`` |
| 32 | |
| 33 | |
| 34 | Description |
| 35 | =========== |
| 36 | |
| 37 | To query the attributes of a tuner applications initialize the ``index`` |
| 38 | field and zero out the ``reserved`` array of a struct |
| 39 | :ref:`v4l2_tuner <v4l2-tuner>` and call the ``VIDIOC_G_TUNER`` ioctl |
| 40 | with a pointer to this structure. Drivers fill the rest of the structure |
Mauro Carvalho Chehab | cdb4af0 | 2016-07-03 11:53:09 -0300 | [diff] [blame] | 41 | or return an ``EINVAL`` error code when the index is out of bounds. To |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 42 | enumerate all tuners applications shall begin at index zero, |
Mauro Carvalho Chehab | cdb4af0 | 2016-07-03 11:53:09 -0300 | [diff] [blame] | 43 | incrementing by one until the driver returns ``EINVAL``. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 44 | |
| 45 | Tuners have two writable properties, the audio mode and the radio |
| 46 | frequency. To change the audio mode, applications initialize the |
| 47 | ``index``, ``audmode`` and ``reserved`` fields and call the |
| 48 | ``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner, |
| 49 | which is determined by the current video input. Drivers may choose a |
| 50 | different audio mode if the requested mode is invalid or unsupported. |
| 51 | Since this is a write-only ioctl, it does not return the actually |
| 52 | selected audio mode. |
| 53 | |
| 54 | :ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and |
| 55 | ``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized |
| 56 | to zero. The term 'tuner' means SDR receiver in this context. |
| 57 | |
| 58 | To change the radio frequency the |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 59 | :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 60 | |
| 61 | |
| 62 | .. _v4l2-tuner: |
| 63 | |
| 64 | .. flat-table:: struct v4l2_tuner |
| 65 | :header-rows: 0 |
| 66 | :stub-columns: 0 |
| 67 | |
| 68 | |
| 69 | - .. row 1 |
| 70 | |
| 71 | - __u32 |
| 72 | |
| 73 | - ``index`` |
| 74 | |
| 75 | - :cspan:`1` Identifies the tuner, set by the application. |
| 76 | |
| 77 | - .. row 2 |
| 78 | |
| 79 | - __u8 |
| 80 | |
| 81 | - ``name``\ [32] |
| 82 | |
| 83 | - :cspan:`1` |
| 84 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 85 | Name of the tuner, a NUL-terminated ASCII string. This information |
| 86 | is intended for the user. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 87 | |
| 88 | - .. row 3 |
| 89 | |
| 90 | - __u32 |
| 91 | |
| 92 | - ``type`` |
| 93 | |
| 94 | - :cspan:`1` Type of the tuner, see :ref:`v4l2-tuner-type`. |
| 95 | |
| 96 | - .. row 4 |
| 97 | |
| 98 | - __u32 |
| 99 | |
| 100 | - ``capability`` |
| 101 | |
| 102 | - :cspan:`1` |
| 103 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 104 | Tuner capability flags, see :ref:`tuner-capability`. Audio flags |
| 105 | indicate the ability to decode audio subprograms. They will *not* |
| 106 | change, for example with the current video standard. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 107 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 108 | When the structure refers to a radio tuner the |
| 109 | ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and |
| 110 | ``V4L2_TUNER_CAP_NORM`` flags can't be used. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 111 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 112 | If multiple frequency bands are supported, then ``capability`` is |
| 113 | the union of all ``capability`` fields of each struct |
| 114 | :ref:`v4l2_frequency_band <v4l2-frequency-band>`. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 115 | |
| 116 | - .. row 5 |
| 117 | |
| 118 | - __u32 |
| 119 | |
| 120 | - ``rangelow`` |
| 121 | |
| 122 | - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 123 | if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units |
| 124 | of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` |
| 125 | is set, in units of 1 Hz. If multiple frequency bands are |
| 126 | supported, then ``rangelow`` is the lowest frequency of all the |
| 127 | frequency bands. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 128 | |
| 129 | - .. row 6 |
| 130 | |
| 131 | - __u32 |
| 132 | |
| 133 | - ``rangehigh`` |
| 134 | |
| 135 | - :cspan:`1` The highest tunable frequency in units of 62.5 kHz, |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 136 | or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in |
| 137 | units of 62.5 Hz, or if the ``capability`` flag |
| 138 | ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple |
| 139 | frequency bands are supported, then ``rangehigh`` is the highest |
| 140 | frequency of all the frequency bands. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 141 | |
| 142 | - .. row 7 |
| 143 | |
| 144 | - __u32 |
| 145 | |
| 146 | - ``rxsubchans`` |
| 147 | |
| 148 | - :cspan:`1` |
| 149 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 150 | Some tuners or audio decoders can determine the received audio |
| 151 | subprograms by analyzing audio carriers, pilot tones or other |
| 152 | indicators. To pass this information drivers set flags defined in |
| 153 | :ref:`tuner-rxsubchans` in this field. For example: |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 154 | |
| 155 | - .. row 8 |
| 156 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 157 | - |
| 158 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 159 | - ``V4L2_TUNER_SUB_MONO`` |
| 160 | |
| 161 | - receiving mono audio |
| 162 | |
| 163 | - .. row 9 |
| 164 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 165 | - |
| 166 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 167 | - ``STEREO | SAP`` |
| 168 | |
| 169 | - receiving stereo audio and a secondary audio program |
| 170 | |
| 171 | - .. row 10 |
| 172 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 173 | - |
| 174 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 175 | - ``MONO | STEREO`` |
| 176 | |
| 177 | - receiving mono or stereo audio, the hardware cannot distinguish |
| 178 | |
| 179 | - .. row 11 |
| 180 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 181 | - |
| 182 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 183 | - ``LANG1 | LANG2`` |
| 184 | |
| 185 | - receiving bilingual audio |
| 186 | |
| 187 | - .. row 12 |
| 188 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 189 | - |
| 190 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 191 | - ``MONO | STEREO | LANG1 | LANG2`` |
| 192 | |
| 193 | - receiving mono, stereo or bilingual audio |
| 194 | |
| 195 | - .. row 13 |
| 196 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 197 | - |
| 198 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 199 | - :cspan:`1` |
| 200 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 201 | When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or |
| 202 | ``_SAP`` flag is cleared in the ``capability`` field, the |
| 203 | corresponding ``V4L2_TUNER_SUB_`` flag must not be set here. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 204 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 205 | This field is valid only if this is the tuner of the current video |
| 206 | input, or when the structure refers to a radio tuner. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 207 | |
| 208 | - .. row 14 |
| 209 | |
| 210 | - __u32 |
| 211 | |
| 212 | - ``audmode`` |
| 213 | |
| 214 | - :cspan:`1` |
| 215 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 216 | The selected audio mode, see :ref:`tuner-audmode` for valid |
| 217 | values. The audio mode does not affect audio subprogram detection, |
| 218 | and like a :ref:`control` it does not automatically |
| 219 | change unless the requested mode is invalid or unsupported. See |
| 220 | :ref:`tuner-matrix` for possible results when the selected and |
| 221 | received audio programs do not match. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 222 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 223 | Currently this is the only field of struct |
| 224 | :ref:`struct v4l2_tuner <v4l2-tuner>` applications can change. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 225 | |
| 226 | - .. row 15 |
| 227 | |
| 228 | - __u32 |
| 229 | |
| 230 | - ``signal`` |
| 231 | |
| 232 | - :cspan:`1` The signal strength if known, ranging from 0 to |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 233 | 65535. Higher values indicate a better signal. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 234 | |
| 235 | - .. row 16 |
| 236 | |
| 237 | - __s32 |
| 238 | |
| 239 | - ``afc`` |
| 240 | |
| 241 | - :cspan:`1` Automatic frequency control: When the ``afc`` value |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 242 | is negative, the frequency is too low, when positive too high. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 243 | |
| 244 | - .. row 17 |
| 245 | |
| 246 | - __u32 |
| 247 | |
| 248 | - ``reserved``\ [4] |
| 249 | |
| 250 | - :cspan:`1` Reserved for future extensions. Drivers and |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 251 | applications must set the array to zero. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 252 | |
| 253 | |
| 254 | |
| 255 | .. _v4l2-tuner-type: |
| 256 | |
| 257 | .. flat-table:: enum v4l2_tuner_type |
| 258 | :header-rows: 0 |
| 259 | :stub-columns: 0 |
| 260 | :widths: 3 1 4 |
| 261 | |
| 262 | |
| 263 | - .. row 1 |
| 264 | |
| 265 | - ``V4L2_TUNER_RADIO`` |
| 266 | |
| 267 | - 1 |
| 268 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 269 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 270 | |
| 271 | - .. row 2 |
| 272 | |
| 273 | - ``V4L2_TUNER_ANALOG_TV`` |
| 274 | |
| 275 | - 2 |
| 276 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 277 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 278 | |
| 279 | - .. row 3 |
| 280 | |
| 281 | - ``V4L2_TUNER_SDR`` |
| 282 | |
| 283 | - 4 |
| 284 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 285 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 286 | |
| 287 | - .. row 4 |
| 288 | |
| 289 | - ``V4L2_TUNER_RF`` |
| 290 | |
| 291 | - 5 |
| 292 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 293 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 294 | |
| 295 | |
| 296 | |
| 297 | .. _tuner-capability: |
| 298 | |
| 299 | .. flat-table:: Tuner and Modulator Capability Flags |
| 300 | :header-rows: 0 |
| 301 | :stub-columns: 0 |
| 302 | :widths: 3 1 4 |
| 303 | |
| 304 | |
| 305 | - .. row 1 |
| 306 | |
| 307 | - ``V4L2_TUNER_CAP_LOW`` |
| 308 | |
| 309 | - 0x0001 |
| 310 | |
| 311 | - When set, tuning frequencies are expressed in units of 62.5 Hz |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 312 | instead of 62.5 kHz. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 313 | |
| 314 | - .. row 2 |
| 315 | |
| 316 | - ``V4L2_TUNER_CAP_NORM`` |
| 317 | |
| 318 | - 0x0002 |
| 319 | |
| 320 | - This is a multi-standard tuner; the video standard can or must be |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 321 | switched. (B/G PAL tuners for example are typically not considered |
| 322 | multi-standard because the video standard is automatically |
| 323 | determined from the frequency band.) The set of supported video |
| 324 | standards is available from the struct |
| 325 | :ref:`v4l2_input <v4l2-input>` pointing to this tuner, see the |
| 326 | description of ioctl :ref:`VIDIOC_ENUMINPUT` |
| 327 | for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this |
| 328 | capability. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 329 | |
| 330 | - .. row 3 |
| 331 | |
| 332 | - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED`` |
| 333 | |
| 334 | - 0x0004 |
| 335 | |
| 336 | - If set, then this tuner supports the hardware seek functionality |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 337 | where the seek stops when it reaches the end of the frequency |
| 338 | range. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 339 | |
| 340 | - .. row 4 |
| 341 | |
| 342 | - ``V4L2_TUNER_CAP_HWSEEK_WRAP`` |
| 343 | |
| 344 | - 0x0008 |
| 345 | |
| 346 | - If set, then this tuner supports the hardware seek functionality |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 347 | where the seek wraps around when it reaches the end of the |
| 348 | frequency range. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 349 | |
| 350 | - .. row 5 |
| 351 | |
| 352 | - ``V4L2_TUNER_CAP_STEREO`` |
| 353 | |
| 354 | - 0x0010 |
| 355 | |
| 356 | - Stereo audio reception is supported. |
| 357 | |
| 358 | - .. row 6 |
| 359 | |
| 360 | - ``V4L2_TUNER_CAP_LANG1`` |
| 361 | |
| 362 | - 0x0040 |
| 363 | |
| 364 | - Reception of the primary language of a bilingual audio program is |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 365 | supported. Bilingual audio is a feature of two-channel systems, |
| 366 | transmitting the primary language monaural on the main audio |
| 367 | carrier and a secondary language monaural on a second carrier. |
| 368 | Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 369 | |
| 370 | - .. row 7 |
| 371 | |
| 372 | - ``V4L2_TUNER_CAP_LANG2`` |
| 373 | |
| 374 | - 0x0020 |
| 375 | |
| 376 | - Reception of the secondary language of a bilingual audio program |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 377 | is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this |
| 378 | capability. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 379 | |
| 380 | - .. row 8 |
| 381 | |
| 382 | - ``V4L2_TUNER_CAP_SAP`` |
| 383 | |
| 384 | - 0x0020 |
| 385 | |
| 386 | - Reception of a secondary audio program is supported. This is a |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 387 | feature of the BTSC system which accompanies the NTSC video |
| 388 | standard. Two audio carriers are available for mono or stereo |
| 389 | transmissions of a primary language, and an independent third |
| 390 | carrier for a monaural secondary language. Only |
| 391 | ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 392 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 393 | Note the ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` flags |
| 394 | are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner |
| 395 | supports the ``V4L2_STD_NTSC_M`` video standard. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 396 | |
| 397 | - .. row 9 |
| 398 | |
| 399 | - ``V4L2_TUNER_CAP_RDS`` |
| 400 | |
| 401 | - 0x0080 |
| 402 | |
| 403 | - RDS capture is supported. This capability is only valid for radio |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 404 | tuners. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 405 | |
| 406 | - .. row 10 |
| 407 | |
| 408 | - ``V4L2_TUNER_CAP_RDS_BLOCK_IO`` |
| 409 | |
| 410 | - 0x0100 |
| 411 | |
| 412 | - The RDS data is passed as unparsed RDS blocks. |
| 413 | |
| 414 | - .. row 11 |
| 415 | |
| 416 | - ``V4L2_TUNER_CAP_RDS_CONTROLS`` |
| 417 | |
| 418 | - 0x0200 |
| 419 | |
| 420 | - The RDS data is parsed by the hardware and set via controls. |
| 421 | |
| 422 | - .. row 12 |
| 423 | |
| 424 | - ``V4L2_TUNER_CAP_FREQ_BANDS`` |
| 425 | |
| 426 | - 0x0400 |
| 427 | |
Mauro Carvalho Chehab | 7347081 | 2016-07-01 13:58:44 -0300 | [diff] [blame] | 428 | - The :ref:`VIDIOC_ENUM_FREQ_BANDS` |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 429 | ioctl can be used to enumerate the available frequency bands. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 430 | |
| 431 | - .. row 13 |
| 432 | |
| 433 | - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` |
| 434 | |
| 435 | - 0x0800 |
| 436 | |
| 437 | - The range to search when using the hardware seek functionality is |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 438 | programmable, see |
| 439 | :ref:`VIDIOC_S_HW_FREQ_SEEK` for |
| 440 | details. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 441 | |
| 442 | - .. row 14 |
| 443 | |
| 444 | - ``V4L2_TUNER_CAP_1HZ`` |
| 445 | |
| 446 | - 0x1000 |
| 447 | |
| 448 | - When set, tuning frequencies are expressed in units of 1 Hz |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 449 | instead of 62.5 kHz. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 450 | |
| 451 | |
| 452 | |
| 453 | .. _tuner-rxsubchans: |
| 454 | |
| 455 | .. flat-table:: Tuner Audio Reception Flags |
| 456 | :header-rows: 0 |
| 457 | :stub-columns: 0 |
| 458 | :widths: 3 1 4 |
| 459 | |
| 460 | |
| 461 | - .. row 1 |
| 462 | |
| 463 | - ``V4L2_TUNER_SUB_MONO`` |
| 464 | |
| 465 | - 0x0001 |
| 466 | |
| 467 | - The tuner receives a mono audio signal. |
| 468 | |
| 469 | - .. row 2 |
| 470 | |
| 471 | - ``V4L2_TUNER_SUB_STEREO`` |
| 472 | |
| 473 | - 0x0002 |
| 474 | |
| 475 | - The tuner receives a stereo audio signal. |
| 476 | |
| 477 | - .. row 3 |
| 478 | |
| 479 | - ``V4L2_TUNER_SUB_LANG1`` |
| 480 | |
| 481 | - 0x0008 |
| 482 | |
| 483 | - The tuner receives the primary language of a bilingual audio |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 484 | signal. Drivers must clear this flag when the current video |
| 485 | standard is ``V4L2_STD_NTSC_M``. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 486 | |
| 487 | - .. row 4 |
| 488 | |
| 489 | - ``V4L2_TUNER_SUB_LANG2`` |
| 490 | |
| 491 | - 0x0004 |
| 492 | |
| 493 | - The tuner receives the secondary language of a bilingual audio |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 494 | signal (or a second audio program). |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 495 | |
| 496 | - .. row 5 |
| 497 | |
| 498 | - ``V4L2_TUNER_SUB_SAP`` |
| 499 | |
| 500 | - 0x0004 |
| 501 | |
| 502 | - The tuner receives a Second Audio Program. Note the |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 503 | ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` flags are |
| 504 | synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies when the current |
| 505 | video standard is ``V4L2_STD_NTSC_M``. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 506 | |
| 507 | - .. row 6 |
| 508 | |
| 509 | - ``V4L2_TUNER_SUB_RDS`` |
| 510 | |
| 511 | - 0x0010 |
| 512 | |
| 513 | - The tuner receives an RDS channel. |
| 514 | |
| 515 | |
| 516 | |
| 517 | .. _tuner-audmode: |
| 518 | |
| 519 | .. flat-table:: Tuner Audio Modes |
| 520 | :header-rows: 0 |
| 521 | :stub-columns: 0 |
| 522 | :widths: 3 1 4 |
| 523 | |
| 524 | |
| 525 | - .. row 1 |
| 526 | |
| 527 | - ``V4L2_TUNER_MODE_MONO`` |
| 528 | |
| 529 | - 0 |
| 530 | |
| 531 | - Play mono audio. When the tuner receives a stereo signal this a |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 532 | down-mix of the left and right channel. When the tuner receives a |
| 533 | bilingual or SAP signal this mode selects the primary language. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 534 | |
| 535 | - .. row 2 |
| 536 | |
| 537 | - ``V4L2_TUNER_MODE_STEREO`` |
| 538 | |
| 539 | - 1 |
| 540 | |
| 541 | - Play stereo audio. When the tuner receives bilingual audio it may |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 542 | play different languages on the left and right channel or the |
| 543 | primary language is played on both channels. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 544 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 545 | Playing different languages in this mode is deprecated. New |
| 546 | drivers should do this only in ``MODE_LANG1_LANG2``. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 547 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 548 | When the tuner receives no stereo signal or does not support |
| 549 | stereo reception the driver shall fall back to ``MODE_MONO``. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 550 | |
| 551 | - .. row 3 |
| 552 | |
| 553 | - ``V4L2_TUNER_MODE_LANG1`` |
| 554 | |
| 555 | - 3 |
| 556 | |
| 557 | - Play the primary language, mono or stereo. Only |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 558 | ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 559 | |
| 560 | - .. row 4 |
| 561 | |
| 562 | - ``V4L2_TUNER_MODE_LANG2`` |
| 563 | |
| 564 | - 2 |
| 565 | |
| 566 | - Play the secondary language, mono. When the tuner receives no |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 567 | bilingual audio or SAP, or their reception is not supported the |
| 568 | driver shall fall back to mono or stereo mode. Only |
| 569 | ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 570 | |
| 571 | - .. row 5 |
| 572 | |
| 573 | - ``V4L2_TUNER_MODE_SAP`` |
| 574 | |
| 575 | - 2 |
| 576 | |
| 577 | - Play the Second Audio Program. When the tuner receives no |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 578 | bilingual audio or SAP, or their reception is not supported the |
| 579 | driver shall fall back to mono or stereo mode. Only |
| 580 | ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. Note the |
| 581 | ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` are |
| 582 | synonyms. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 583 | |
| 584 | - .. row 6 |
| 585 | |
| 586 | - ``V4L2_TUNER_MODE_LANG1_LANG2`` |
| 587 | |
| 588 | - 4 |
| 589 | |
| 590 | - Play the primary language on the left channel, the secondary |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 591 | language on the right channel. When the tuner receives no |
| 592 | bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or |
| 593 | ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this |
| 594 | mode. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 595 | |
| 596 | |
| 597 | |
| 598 | .. _tuner-matrix: |
| 599 | |
| 600 | .. flat-table:: Tuner Audio Matrix |
| 601 | :header-rows: 2 |
| 602 | :stub-columns: 0 |
| 603 | |
| 604 | |
| 605 | - .. row 1 |
| 606 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame^] | 607 | - |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 608 | - :cspan:`5` Selected ``V4L2_TUNER_MODE_`` |
| 609 | |
| 610 | - .. row 2 |
| 611 | |
| 612 | - Received ``V4L2_TUNER_SUB_`` |
| 613 | |
| 614 | - ``MONO`` |
| 615 | |
| 616 | - ``STEREO`` |
| 617 | |
| 618 | - ``LANG1`` |
| 619 | |
| 620 | - ``LANG2 = SAP`` |
| 621 | |
| 622 | - ``LANG1_LANG2``\ [1]_ |
| 623 | |
| 624 | - .. row 3 |
| 625 | |
| 626 | - ``MONO`` |
| 627 | |
| 628 | - Mono |
| 629 | |
| 630 | - Mono/Mono |
| 631 | |
| 632 | - Mono |
| 633 | |
| 634 | - Mono |
| 635 | |
| 636 | - Mono/Mono |
| 637 | |
| 638 | - .. row 4 |
| 639 | |
| 640 | - ``MONO | SAP`` |
| 641 | |
| 642 | - Mono |
| 643 | |
| 644 | - Mono/Mono |
| 645 | |
| 646 | - Mono |
| 647 | |
| 648 | - SAP |
| 649 | |
| 650 | - Mono/SAP (preferred) or Mono/Mono |
| 651 | |
| 652 | - .. row 5 |
| 653 | |
| 654 | - ``STEREO`` |
| 655 | |
| 656 | - L+R |
| 657 | |
| 658 | - L/R |
| 659 | |
| 660 | - Stereo L/R (preferred) or Mono L+R |
| 661 | |
| 662 | - Stereo L/R (preferred) or Mono L+R |
| 663 | |
| 664 | - L/R (preferred) or L+R/L+R |
| 665 | |
| 666 | - .. row 6 |
| 667 | |
| 668 | - ``STEREO | SAP`` |
| 669 | |
| 670 | - L+R |
| 671 | |
| 672 | - L/R |
| 673 | |
| 674 | - Stereo L/R (preferred) or Mono L+R |
| 675 | |
| 676 | - SAP |
| 677 | |
| 678 | - L+R/SAP (preferred) or L/R or L+R/L+R |
| 679 | |
| 680 | - .. row 7 |
| 681 | |
| 682 | - ``LANG1 | LANG2`` |
| 683 | |
| 684 | - Language 1 |
| 685 | |
| 686 | - Lang1/Lang2 (deprecated [2]_) or Lang1/Lang1 |
| 687 | |
| 688 | - Language 1 |
| 689 | |
| 690 | - Language 2 |
| 691 | |
| 692 | - Lang1/Lang2 (preferred) or Lang1/Lang1 |
| 693 | |
| 694 | |
| 695 | |
| 696 | Return Value |
| 697 | ============ |
| 698 | |
| 699 | On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 700 | appropriately. The generic error codes are described at the |
| 701 | :ref:`Generic Error Codes <gen-errors>` chapter. |
| 702 | |
| 703 | EINVAL |
| 704 | The struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` is out of |
| 705 | bounds. |
| 706 | |
| 707 | .. [1] |
| 708 | This mode has been added in Linux 2.6.17 and may not be supported by |
| 709 | older drivers. |
| 710 | |
| 711 | .. [2] |
| 712 | Playback of both languages in ``MODE_STEREO`` is deprecated. In the |
| 713 | future drivers should produce only the primary language in this mode. |
| 714 | Applications should request ``MODE_LANG1_LANG2`` to record both |
| 715 | languages or a stereo signal. |