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