Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_G_DV_TIMINGS: |
5377d91f MH |
4 | |
5 | ********************************************** | |
6 | ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS | |
7 | ********************************************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
41d80465 MCC |
18 | .. c:function:: int ioctl( int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp ) |
19 | :name: VIDIOC_G_DV_TIMINGS | |
20 | ||
21 | .. c:function:: int ioctl( int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp ) | |
22 | :name: VIDIOC_S_DV_TIMINGS | |
23 | ||
24 | .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp ) | |
25 | :name: VIDIOC_SUBDEV_G_DV_TIMINGS | |
26 | ||
27 | .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp ) | |
28 | :name: VIDIOC_SUBDEV_S_DV_TIMINGS | |
5377d91f | 29 | |
586027ce | 30 | |
15e7d615 | 31 | Arguments |
5377d91f MH |
32 | ========= |
33 | ||
34 | ``fd`` | |
35 | File descriptor returned by :ref:`open() <func-open>`. | |
36 | ||
5377d91f MH |
37 | ``argp`` |
38 | ||
39 | ||
15e7d615 | 40 | Description |
5377d91f MH |
41 | =========== |
42 | ||
43 | To set DV timings for the input or output, applications use the | |
2212ff25 | 44 | :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get the current timings, |
4e03cb76 | 45 | applications use the :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. The detailed timing |
5377d91f | 46 | information is filled in using the structure struct |
e8be7e97 MCC |
47 | :c:type:`v4l2_dv_timings`. These ioctls take a |
48 | pointer to the struct :c:type:`v4l2_dv_timings` | |
5377d91f | 49 | structure as argument. If the ioctl is not supported or the timing |
cdb4af0f | 50 | values are not correct, the driver returns ``EINVAL`` error code. |
5377d91f MH |
51 | |
52 | The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of | |
53 | the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If | |
54 | the current input or output does not support DV timings (e.g. if | |
7347081e | 55 | :ref:`VIDIOC_ENUMINPUT` does not set the |
cdb4af0f | 56 | ``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned. |
5377d91f MH |
57 | |
58 | ||
15e7d615 | 59 | Return Value |
5377d91f MH |
60 | ============ |
61 | ||
62 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
63 | appropriately. The generic error codes are described at the | |
64 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
65 | ||
66 | EINVAL | |
2212ff25 | 67 | This ioctl is not supported, or the :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` |
5377d91f MH |
68 | parameter was unsuitable. |
69 | ||
70 | ENODATA | |
71 | Digital video timings are not supported for this input or output. | |
72 | ||
73 | EBUSY | |
74 | The device is busy and therefore can not change the timings. | |
75 | ||
76 | ||
5bd4bb78 MCC |
77 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
78 | ||
e8be7e97 | 79 | .. c:type:: v4l2_bt_timings |
fa92b04d | 80 | |
5377d91f MH |
81 | .. flat-table:: struct v4l2_bt_timings |
82 | :header-rows: 0 | |
83 | :stub-columns: 0 | |
84 | :widths: 1 1 2 | |
85 | ||
86 | ||
87 | - .. row 1 | |
88 | ||
89 | - __u32 | |
90 | ||
91 | - ``width`` | |
92 | ||
93 | - Width of the active video in pixels. | |
94 | ||
95 | - .. row 2 | |
96 | ||
97 | - __u32 | |
98 | ||
99 | - ``height`` | |
100 | ||
101 | - Height of the active video frame in lines. So for interlaced | |
0579e6e3 MCC |
102 | formats the height of the active video in each field is |
103 | ``height``/2. | |
5377d91f MH |
104 | |
105 | - .. row 3 | |
106 | ||
107 | - __u32 | |
108 | ||
109 | - ``interlaced`` | |
110 | ||
53ae9251 | 111 | - Progressive (``V4L2_DV_PROGRESSIVE``) or interlaced (``V4L2_DV_INTERLACED``). |
5377d91f MH |
112 | |
113 | - .. row 4 | |
114 | ||
115 | - __u32 | |
116 | ||
117 | - ``polarities`` | |
118 | ||
119 | - This is a bit mask that defines polarities of sync signals. bit 0 | |
249e5ba0 MCC |
120 | (``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit |
121 | 1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If | |
0579e6e3 MCC |
122 | the bit is set (1) it is positive polarity and if is cleared (0), |
123 | it is negative polarity. | |
5377d91f MH |
124 | |
125 | - .. row 5 | |
126 | ||
127 | - __u64 | |
128 | ||
129 | - ``pixelclock`` | |
130 | ||
131 | - Pixel clock in Hz. Ex. 74.25MHz->74250000 | |
132 | ||
133 | - .. row 6 | |
134 | ||
135 | - __u32 | |
136 | ||
137 | - ``hfrontporch`` | |
138 | ||
139 | - Horizontal front porch in pixels | |
140 | ||
141 | - .. row 7 | |
142 | ||
143 | - __u32 | |
144 | ||
145 | - ``hsync`` | |
146 | ||
147 | - Horizontal sync length in pixels | |
148 | ||
149 | - .. row 8 | |
150 | ||
151 | - __u32 | |
152 | ||
153 | - ``hbackporch`` | |
154 | ||
155 | - Horizontal back porch in pixels | |
156 | ||
157 | - .. row 9 | |
158 | ||
159 | - __u32 | |
160 | ||
161 | - ``vfrontporch`` | |
162 | ||
163 | - Vertical front porch in lines. For interlaced formats this refers | |
0579e6e3 | 164 | to the odd field (aka field 1). |
5377d91f MH |
165 | |
166 | - .. row 10 | |
167 | ||
168 | - __u32 | |
169 | ||
170 | - ``vsync`` | |
171 | ||
172 | - Vertical sync length in lines. For interlaced formats this refers | |
0579e6e3 | 173 | to the odd field (aka field 1). |
5377d91f MH |
174 | |
175 | - .. row 11 | |
176 | ||
177 | - __u32 | |
178 | ||
179 | - ``vbackporch`` | |
180 | ||
181 | - Vertical back porch in lines. For interlaced formats this refers | |
0579e6e3 | 182 | to the odd field (aka field 1). |
5377d91f MH |
183 | |
184 | - .. row 12 | |
185 | ||
186 | - __u32 | |
187 | ||
188 | - ``il_vfrontporch`` | |
189 | ||
190 | - Vertical front porch in lines for the even field (aka field 2) of | |
0579e6e3 | 191 | interlaced field formats. Must be 0 for progressive formats. |
5377d91f MH |
192 | |
193 | - .. row 13 | |
194 | ||
195 | - __u32 | |
196 | ||
197 | - ``il_vsync`` | |
198 | ||
199 | - Vertical sync length in lines for the even field (aka field 2) of | |
0579e6e3 | 200 | interlaced field formats. Must be 0 for progressive formats. |
5377d91f MH |
201 | |
202 | - .. row 14 | |
203 | ||
204 | - __u32 | |
205 | ||
206 | - ``il_vbackporch`` | |
207 | ||
208 | - Vertical back porch in lines for the even field (aka field 2) of | |
0579e6e3 | 209 | interlaced field formats. Must be 0 for progressive formats. |
5377d91f MH |
210 | |
211 | - .. row 15 | |
212 | ||
213 | - __u32 | |
214 | ||
215 | - ``standards`` | |
216 | ||
217 | - The video standard(s) this format belongs to. This will be filled | |
0579e6e3 MCC |
218 | in by the driver. Applications must set this to 0. See |
219 | :ref:`dv-bt-standards` for a list of standards. | |
5377d91f MH |
220 | |
221 | - .. row 16 | |
222 | ||
223 | - __u32 | |
224 | ||
225 | - ``flags`` | |
226 | ||
227 | - Several flags giving more information about the format. See | |
0579e6e3 | 228 | :ref:`dv-bt-flags` for a description of the flags. |
5377d91f | 229 | |
bb77c577 HV |
230 | - .. row 17 |
231 | ||
232 | - __u32 | |
233 | ||
234 | - ``reserved[14]`` | |
235 | ||
236 | - Reserved for future extensions. Drivers and applications must set | |
237 | the array to zero. | |
5377d91f MH |
238 | |
239 | ||
5bd4bb78 MCC |
240 | .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}| |
241 | ||
e8be7e97 | 242 | .. c:type:: v4l2_dv_timings |
fa92b04d | 243 | |
5377d91f MH |
244 | .. flat-table:: struct v4l2_dv_timings |
245 | :header-rows: 0 | |
246 | :stub-columns: 0 | |
247 | :widths: 1 1 2 1 | |
248 | ||
249 | ||
250 | - .. row 1 | |
251 | ||
252 | - __u32 | |
253 | ||
254 | - ``type`` | |
255 | ||
0579e6e3 | 256 | - |
5377d91f MH |
257 | - Type of DV timings as listed in :ref:`dv-timing-types`. |
258 | ||
259 | - .. row 2 | |
260 | ||
261 | - union | |
262 | ||
0579e6e3 MCC |
263 | - |
264 | - | |
5377d91f MH |
265 | |
266 | - .. row 3 | |
267 | ||
0579e6e3 | 268 | - |
e8be7e97 | 269 | - struct :c:type:`v4l2_bt_timings` |
5377d91f MH |
270 | |
271 | - ``bt`` | |
272 | ||
273 | - Timings defined by BT.656/1120 specifications | |
274 | ||
275 | - .. row 4 | |
276 | ||
0579e6e3 | 277 | - |
5377d91f MH |
278 | - __u32 |
279 | ||
8968da9b | 280 | - ``reserved``\ [32] |
5377d91f | 281 | |
0579e6e3 | 282 | - |
5377d91f | 283 | |
fa92b04d | 284 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
5377d91f MH |
285 | |
286 | .. _dv-timing-types: | |
287 | ||
288 | .. flat-table:: DV Timing types | |
289 | :header-rows: 0 | |
290 | :stub-columns: 0 | |
291 | :widths: 1 1 2 | |
292 | ||
293 | ||
294 | - .. row 1 | |
295 | ||
296 | - Timing type | |
297 | ||
298 | - value | |
299 | ||
300 | - Description | |
301 | ||
302 | - .. row 2 | |
303 | ||
0579e6e3 MCC |
304 | - |
305 | - | |
306 | - | |
5377d91f MH |
307 | |
308 | - .. row 3 | |
309 | ||
249e5ba0 | 310 | - ``V4L2_DV_BT_656_1120`` |
5377d91f MH |
311 | |
312 | - 0 | |
313 | ||
314 | - BT.656/1120 timings | |
315 | ||
316 | ||
317 | ||
318 | .. _dv-bt-standards: | |
319 | ||
320 | .. flat-table:: DV BT Timing standards | |
321 | :header-rows: 0 | |
322 | :stub-columns: 0 | |
323 | ||
324 | ||
325 | - .. row 1 | |
326 | ||
327 | - Timing standard | |
328 | ||
329 | - Description | |
330 | ||
5377d91f MH |
331 | - .. row 3 |
332 | ||
249e5ba0 | 333 | - ``V4L2_DV_BT_STD_CEA861`` |
5377d91f MH |
334 | |
335 | - The timings follow the CEA-861 Digital TV Profile standard | |
336 | ||
337 | - .. row 4 | |
338 | ||
249e5ba0 | 339 | - ``V4L2_DV_BT_STD_DMT`` |
5377d91f MH |
340 | |
341 | - The timings follow the VESA Discrete Monitor Timings standard | |
342 | ||
343 | - .. row 5 | |
344 | ||
249e5ba0 | 345 | - ``V4L2_DV_BT_STD_CVT`` |
5377d91f MH |
346 | |
347 | - The timings follow the VESA Coordinated Video Timings standard | |
348 | ||
349 | - .. row 6 | |
350 | ||
249e5ba0 | 351 | - ``V4L2_DV_BT_STD_GTF`` |
5377d91f MH |
352 | |
353 | - The timings follow the VESA Generalized Timings Formula standard | |
354 | ||
355 | ||
ef76c068 | 356 | .. tabularcolumns:: |p{6.0cm}|p{11.5cm}| |
5377d91f MH |
357 | |
358 | .. _dv-bt-flags: | |
359 | ||
360 | .. flat-table:: DV BT Timing flags | |
361 | :header-rows: 0 | |
362 | :stub-columns: 0 | |
363 | ||
364 | ||
365 | - .. row 1 | |
366 | ||
367 | - Flag | |
368 | ||
369 | - Description | |
370 | ||
5377d91f MH |
371 | - .. row 3 |
372 | ||
249e5ba0 | 373 | - ``V4L2_DV_FL_REDUCED_BLANKING`` |
5377d91f MH |
374 | |
375 | - CVT/GTF specific: the timings use reduced blanking (CVT) or the | |
0579e6e3 MCC |
376 | 'Secondary GTF' curve (GTF). In both cases the horizontal and/or |
377 | vertical blanking intervals are reduced, allowing a higher | |
378 | resolution over the same bandwidth. This is a read-only flag, | |
379 | applications must not set this. | |
5377d91f MH |
380 | |
381 | - .. row 4 | |
382 | ||
249e5ba0 | 383 | - ``V4L2_DV_FL_CAN_REDUCE_FPS`` |
5377d91f MH |
384 | |
385 | - CEA-861 specific: set for CEA-861 formats with a framerate that is | |
0579e6e3 MCC |
386 | a multiple of six. These formats can be optionally played at 1 / |
387 | 1.001 speed to be compatible with 60 Hz based standards such as | |
388 | NTSC and PAL-M that use a framerate of 29.97 frames per second. If | |
389 | the transmitter can't generate such frequencies, then the flag | |
390 | will also be cleared. This is a read-only flag, applications must | |
391 | not set this. | |
5377d91f MH |
392 | |
393 | - .. row 5 | |
394 | ||
249e5ba0 | 395 | - ``V4L2_DV_FL_REDUCED_FPS`` |
5377d91f MH |
396 | |
397 | - CEA-861 specific: only valid for video transmitters, the flag is | |
0579e6e3 | 398 | cleared by receivers. It is also only valid for formats with the |
249e5ba0 | 399 | ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the |
0579e6e3 MCC |
400 | flag will be cleared by the driver. If the application sets this |
401 | flag, then the pixelclock used to set up the transmitter is | |
402 | divided by 1.001 to make it compatible with NTSC framerates. If | |
403 | the transmitter can't generate such frequencies, then the flag | |
404 | will also be cleared. | |
5377d91f MH |
405 | |
406 | - .. row 6 | |
407 | ||
249e5ba0 | 408 | - ``V4L2_DV_FL_HALF_LINE`` |
5377d91f MH |
409 | |
410 | - Specific to interlaced formats: if set, then the vertical | |
0579e6e3 MCC |
411 | frontporch of field 1 (aka the odd field) is really one half-line |
412 | longer and the vertical backporch of field 2 (aka the even field) | |
413 | is really one half-line shorter, so each field has exactly the | |
414 | same number of half-lines. Whether half-lines can be detected or | |
415 | used depends on the hardware. | |
5377d91f MH |
416 | |
417 | - .. row 7 | |
418 | ||
249e5ba0 | 419 | - ``V4L2_DV_FL_IS_CE_VIDEO`` |
5377d91f MH |
420 | |
421 | - If set, then this is a Consumer Electronics (CE) video format. | |
0579e6e3 MCC |
422 | Such formats differ from other formats (commonly called IT |
423 | formats) in that if R'G'B' encoding is used then by default the | |
424 | R'G'B' values use limited range (i.e. 16-235) as opposed to full | |
425 | range (i.e. 0-255). All formats defined in CEA-861 except for the | |
426 | 640x480p59.94 format are CE formats. |