1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 254f38fcaSMauro Carvalho Chehab 354f38fcaSMauro Carvalho Chehab.. _dv-timings: 454f38fcaSMauro Carvalho Chehab 554f38fcaSMauro Carvalho Chehab************************** 654f38fcaSMauro Carvalho ChehabDigital Video (DV) Timings 754f38fcaSMauro Carvalho Chehab************************** 854f38fcaSMauro Carvalho Chehab 954f38fcaSMauro Carvalho ChehabThe video standards discussed so far have been dealing with Analog TV 1054f38fcaSMauro Carvalho Chehaband the corresponding video timings. Today there are many more different 1154f38fcaSMauro Carvalho Chehabhardware interfaces such as High Definition TV interfaces (HDMI), VGA, 1254f38fcaSMauro Carvalho ChehabDVI connectors etc., that carry video signals and there is a need to 1354f38fcaSMauro Carvalho Chehabextend the API to select the video timings for these interfaces. Since 1454f38fcaSMauro Carvalho Chehabit is not possible to extend the :ref:`v4l2_std_id <v4l2-std-id>` 1554f38fcaSMauro Carvalho Chehabdue to the limited bits available, a new set of ioctls was added to 1654f38fcaSMauro Carvalho Chehabset/get video timings at the input and output. 1754f38fcaSMauro Carvalho Chehab 1854f38fcaSMauro Carvalho ChehabThese ioctls deal with the detailed digital video timings that define 1954f38fcaSMauro Carvalho Chehabeach video format. This includes parameters such as the active video 2054f38fcaSMauro Carvalho Chehabwidth and height, signal polarities, frontporches, backporches, sync 2154f38fcaSMauro Carvalho Chehabwidths etc. The ``linux/v4l2-dv-timings.h`` header can be used to get 2254f38fcaSMauro Carvalho Chehabthe timings of the formats in the :ref:`cea861` and :ref:`vesadmt` 2354f38fcaSMauro Carvalho Chehabstandards. 2454f38fcaSMauro Carvalho Chehab 2554f38fcaSMauro Carvalho ChehabTo enumerate and query the attributes of the DV timings supported by a 2654f38fcaSMauro Carvalho Chehabdevice applications use the 2754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_ENUM_DV_TIMINGS` and 2854f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_DV_TIMINGS_CAP` ioctls. To set 2954f38fcaSMauro Carvalho ChehabDV timings for the device applications use the 3054f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get 3154f38fcaSMauro Carvalho Chehabcurrent DV timings they use the 3254f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. To detect 3354f38fcaSMauro Carvalho Chehabthe DV timings as seen by the video receiver applications use the 3454f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl. 3554f38fcaSMauro Carvalho Chehab 36*cab0c4e9SHans VerkuilWhen the hardware detects a video source change (e.g. the video 37*cab0c4e9SHans Verkuilsignal appears or disappears, or the video resolution changes), then 38*cab0c4e9SHans Verkuilit will issue a `V4L2_EVENT_SOURCE_CHANGE` event. Use the 39*cab0c4e9SHans Verkuil:ref:`ioctl VIDIOC_SUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` and the 40*cab0c4e9SHans Verkuil:ref:`VIDIOC_DQEVENT` to check if this event was reported. 41*cab0c4e9SHans Verkuil 42*cab0c4e9SHans VerkuilIf the video signal changed, then the application has to stop 43*cab0c4e9SHans Verkuilstreaming, free all buffers, and call the :ref:`VIDIOC_QUERY_DV_TIMINGS` 44*cab0c4e9SHans Verkuilto obtain the new video timings, and if they are valid, it can set 45*cab0c4e9SHans Verkuilthose by calling the :ref:`ioctl VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`. 46*cab0c4e9SHans VerkuilThis will also update the format, so use the :ref:`ioctl VIDIOC_G_FMT <VIDIOC_G_FMT>` 47*cab0c4e9SHans Verkuilto obtain the new format. Now the application can allocate new buffers 48*cab0c4e9SHans Verkuiland start streaming again. 49*cab0c4e9SHans Verkuil 50*cab0c4e9SHans VerkuilThe :ref:`VIDIOC_QUERY_DV_TIMINGS` will just report what the 51*cab0c4e9SHans Verkuilhardware detects, it will never change the configuration. If the 52*cab0c4e9SHans Verkuilcurrently set timings and the actually detected timings differ, then 53*cab0c4e9SHans Verkuiltypically this will mean that you will not be able to capture any 54*cab0c4e9SHans Verkuilvideo. The correct approach is to rely on the `V4L2_EVENT_SOURCE_CHANGE` 55*cab0c4e9SHans Verkuilevent so you know when something changed. 56*cab0c4e9SHans Verkuil 5754f38fcaSMauro Carvalho ChehabApplications can make use of the :ref:`input-capabilities` and 5854f38fcaSMauro Carvalho Chehab:ref:`output-capabilities` flags to determine whether the digital 5954f38fcaSMauro Carvalho Chehabvideo ioctls can be used with the given input or output. 60