1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _VIDIOC_QUERY_DV_TIMINGS:
4
5*****************************
6ioctl VIDIOC_QUERY_DV_TIMINGS
7*****************************
8
9Name
10====
11
12VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input
13
14
15Synopsis
16========
17
18.. c:function:: int ioctl( int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp )
19    :name: VIDIOC_QUERY_DV_TIMINGS
20
21.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp )
22    :name: VIDIOC_SUBDEV_QUERY_DV_TIMINGS
23
24
25Arguments
26=========
27
28``fd``
29    File descriptor returned by :ref:`open() <func-open>`.
30
31``argp``
32    Pointer to struct :c:type:`v4l2_dv_timings`.
33
34
35Description
36===========
37
38The hardware may be able to detect the current DV timings automatically,
39similar to sensing the video standard. To do so, applications call
40:ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct
41:c:type:`v4l2_dv_timings`. Once the hardware detects
42the timings, it will fill in the timings structure.
43
44.. note::
45
46   Drivers shall *not* switch timings automatically if new
47   timings are detected. Instead, drivers should send the
48   ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
49   that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
50   The reason is that new timings usually mean different buffer sizes as
51   well, and you cannot change buffer sizes on the fly. In general,
52   applications that receive the Source Change event will have to call
53   :ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
54   will have to stop streaming, set the new timings, allocate new buffers
55   and start streaming again.
56
57If the timings could not be detected because there was no signal, then
58ENOLINK is returned. If a signal was detected, but it was unstable and
59the receiver could not lock to the signal, then ``ENOLCK`` is returned. If
60the receiver could lock to the signal, but the format is unsupported
61(e.g. because the pixelclock is out of range of the hardware
62capabilities), then the driver fills in whatever timings it could find
63and returns ``ERANGE``. In that case the application can call
64:ref:`VIDIOC_DV_TIMINGS_CAP` to compare the
65found timings with the hardware's capabilities in order to give more
66precise feedback to the user.
67
68
69Return Value
70============
71
72On success 0 is returned, on error -1 and the ``errno`` variable is set
73appropriately. The generic error codes are described at the
74:ref:`Generic Error Codes <gen-errors>` chapter.
75
76ENODATA
77    Digital video timings are not supported for this input or output.
78
79ENOLINK
80    No timings could be detected because no signal was found.
81
82ENOLCK
83    The signal was unstable and the hardware could not lock on to it.
84
85ERANGE
86    Timings were found, but they are out of range of the hardware
87    capabilities.
88