1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _VIDIOC_ENUM_DV_TIMINGS:
11
12***********************************************************
13ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
14***********************************************************
15
16Name
17====
18
19VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp )
26    :name: VIDIOC_ENUM_DV_TIMINGS
27
28.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp )
29    :name: VIDIOC_SUBDEV_ENUM_DV_TIMINGS
30
31
32Arguments
33=========
34
35``fd``
36    File descriptor returned by :ref:`open() <func-open>`.
37
38``argp``
39    Pointer to struct :c:type:`v4l2_enum_dv_timings`.
40
41
42Description
43===========
44
45While some DV receivers or transmitters support a wide range of timings,
46others support only a limited number of timings. With this ioctl
47applications can enumerate a list of known supported timings. Call
48:ref:`VIDIOC_DV_TIMINGS_CAP` to check if it
49also supports other standards or even custom timings that are not in
50this list.
51
52To query the available timings, applications initialize the ``index``
53field, set the ``pad`` field to 0, zero the reserved array of struct
54:c:type:`v4l2_enum_dv_timings` and call the
55``VIDIOC_ENUM_DV_TIMINGS`` ioctl on a video node with a pointer to this
56structure. Drivers fill the rest of the structure or return an ``EINVAL``
57error code when the index is out of bounds. To enumerate all supported
58DV timings, applications shall begin at index zero, incrementing by one
59until the driver returns ``EINVAL``.
60
61.. note::
62
63   Drivers may enumerate a different set of DV timings after
64   switching the video input or output.
65
66When implemented by the driver DV timings of subdevices can be queried
67by calling the ``VIDIOC_SUBDEV_ENUM_DV_TIMINGS`` ioctl directly on a
68subdevice node. The DV timings are specific to inputs (for DV receivers)
69or outputs (for DV transmitters), applications must specify the desired
70pad number in the struct
71:c:type:`v4l2_enum_dv_timings` ``pad`` field.
72Attempts to enumerate timings on a pad that doesn't support them will
73return an ``EINVAL`` error code.
74
75
76.. c:type:: v4l2_enum_dv_timings
77
78.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
79
80.. flat-table:: struct v4l2_enum_dv_timings
81    :header-rows:  0
82    :stub-columns: 0
83    :widths:       1 1 2
84
85    * - __u32
86      - ``index``
87      - Number of the DV timings, set by the application.
88    * - __u32
89      - ``pad``
90      - Pad number as reported by the media controller API. This field is
91	only used when operating on a subdevice node. When operating on a
92	video node applications must set this field to zero.
93    * - __u32
94      - ``reserved``\ [2]
95      - Reserved for future extensions. Drivers and applications must set
96	the array to zero.
97    * - struct :c:type:`v4l2_dv_timings`
98      - ``timings``
99      - The timings.
100
101
102Return Value
103============
104
105On success 0 is returned, on error -1 and the ``errno`` variable is set
106appropriately. The generic error codes are described at the
107:ref:`Generic Error Codes <gen-errors>` chapter.
108
109EINVAL
110    The struct :c:type:`v4l2_enum_dv_timings`
111    ``index`` is out of bounds or the ``pad`` number is invalid.
112
113ENODATA
114    Digital video presets are not supported for this input or output.
115