From 7dcc606b2a980222d9816d092a5c20b7c98cbd1a Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Tue, 15 May 2012 08:04:28 -0300 Subject: [PATCH] [media] V4L2 spec: document the new V4L2 DV timings ioctls Signed-off-by: Hans Verkuil Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/biblio.xml | 18 ++ Documentation/DocBook/media/v4l/common.xml | 32 +-- Documentation/DocBook/media/v4l/compat.xml | 13 ++ Documentation/DocBook/media/v4l/v4l2.xml | 15 +- .../DocBook/media/v4l/vidioc-create-bufs.xml | 6 + .../media/v4l/vidioc-dv-timings-cap.xml | 211 ++++++++++++++++++ .../media/v4l/vidioc-enum-dv-presets.xml | 4 + .../media/v4l/vidioc-enum-dv-timings.xml | 119 ++++++++++ .../DocBook/media/v4l/vidioc-enuminput.xml | 2 +- .../DocBook/media/v4l/vidioc-enumoutput.xml | 2 +- .../DocBook/media/v4l/vidioc-g-dv-timings.xml | 130 ++++++++++- .../DocBook/media/v4l/vidioc-prepare-buf.xml | 6 + .../media/v4l/vidioc-query-dv-timings.xml | 104 +++++++++ 13 files changed, 633 insertions(+), 29 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml create mode 100644 Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml create mode 100644 Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index 66a0ef251c79..7c49facecd25 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -208,4 +208,22 @@ in the frequency range from 87,5 to 108,0 MHz recommended exposure index + + CEA-861-E + + Consumer Electronics Association +(http://www.ce.org) + + A DTV Profile for Uncompressed High Speed Digital Interfaces + + + + VESA DMT + + Video Electronics Standards Association +(http://www.vesa.org) + + VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT) + + diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index c79278acfb0e..81b7cf384a39 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -724,41 +724,47 @@ if (-1 == ioctl (fd, &VIDIOC-S-STD;, &std_id)) { } +
Digital Video (DV) Timings - The video standards discussed so far has been dealing with Analog TV and the + The video standards discussed so far have been dealing with Analog TV and the corresponding video timings. Today there are many more different hardware interfaces such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry video signals and there is a need to extend the API to select the video timings for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to -the limited bits available, a new set of IOCTLs is added to set/get video timings at +the limited bits available, a new set of IOCTLs was added to set/get video timings at the input and output: + + DV Timings: This will allow applications to define detailed +video timings for the interface. This includes parameters such as width, height, +polarities, frontporch, backporch etc. The linux/v4l2-dv-timings.h +header can be used to get the timings of the formats in the and + standards. + + DV Presets: Digital Video (DV) presets. These are IDs representing a video timing at the input/output. Presets are pre-defined timings implemented by the hardware according to video standards. A __u32 data type is used to represent a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions to support as many different presets as needed. - - - Custom DV Timings: This will allow applications to define more detailed -custom video timings for the interface. This includes parameters such as width, height, -polarities, frontporch, backporch etc. - + To enumerate and query the attributes of the DV timings supported by a device, + applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls. + To set DV timings for the device, applications use the +&VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the +&VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications +use the &VIDIOC-QUERY-DV-TIMINGS; ioctl. To enumerate and query the attributes of DV presets supported by a device, applications use the &VIDIOC-ENUM-DV-PRESETS; ioctl. To get the current DV preset, applications use the &VIDIOC-G-DV-PRESET; ioctl and to set a preset they use the -&VIDIOC-S-DV-PRESET; ioctl. - To set custom DV timings for the device, applications use the -&VIDIOC-S-DV-TIMINGS; ioctl and to get current custom DV timings they use the -&VIDIOC-G-DV-TIMINGS; ioctl. +&VIDIOC-S-DV-PRESET; ioctl. To detect the preset as seen by the video receiver applications +use the &VIDIOC-QUERY-DV-PRESET; ioctl. Applications can make use of the and flags to decide what ioctls are available to set the video timings for the device. -
&sub-controls; diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index dc61b013b8a8..cd19d21085db 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2407,6 +2407,11 @@ details. Added JPEG compression control class. + + Extended the DV Timings API: + &VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and + &VIDIOC-DV-TIMINGS-CAP;. + @@ -2548,6 +2553,10 @@ and may change in the future. &VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; +ioctls. + + + &VIDIOC-DECODER-CMD; and &VIDIOC-TRY-DECODER-CMD; ioctls. @@ -2557,6 +2566,10 @@ ioctls. &VIDIOC-DBG-G-CHIP-IDENT; ioctl. + + &VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and + &VIDIOC-DV-TIMINGS-CAP; ioctls. + Flash API. diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index e6fbbc6c17e1..015c561754b7 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -28,8 +28,8 @@ documentation. Hans Verkuil Designed and documented the VIDIOC_LOG_STATUS ioctl, -the extended control ioctls and major parts of the sliced VBI -API. +the extended control ioctls, major parts of the sliced VBI API, the +MPEG encoder and decoder APIs and the DV Timings API.
hverkuil@xs4all.nl @@ -123,6 +123,7 @@ Remote Controller chapter. 2009 2010 2011 + 2012 Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak @@ -153,6 +154,11 @@ applications. --> V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. + 2012-05-01 + hv + Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and + VIDIOC_DV_TIMINGS_CAP. + @@ -461,7 +467,7 @@ and discussions on the V4L mailing list. Video for Linux Two API Specification - Revision 3.3 + Revision 3.5 &sub-common; @@ -519,10 +525,12 @@ and discussions on the V4L mailing list. &sub-dbg-g-register; &sub-decoder-cmd; &sub-dqevent; + &sub-dv-timings-cap; &sub-encoder-cmd; &sub-enumaudio; &sub-enumaudioout; &sub-enum-dv-presets; + &sub-enum-dv-timings; &sub-enum-fmt; &sub-enum-framesizes; &sub-enum-frameintervals; @@ -557,6 +565,7 @@ and discussions on the V4L mailing list. &sub-querycap; &sub-queryctrl; &sub-query-dv-preset; + &sub-query-dv-timings; &sub-querystd; &sub-prepare-buf; &sub-reqbufs; diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index 184cdfc13081..765549ff8a71 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -48,6 +48,12 @@ Description + + Experimental + This is an experimental + interface and may change in the future. + + This ioctl is used to create buffers for memory mapped or user pointer I/O. It can be used as an alternative or in addition to the diff --git a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml new file mode 100644 index 000000000000..6673ce582050 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml @@ -0,0 +1,211 @@ + + + ioctl VIDIOC_DV_TIMINGS_CAP + &manvol; + + + + VIDIOC_DV_TIMINGS_CAP + The capabilities of the Digital Video receiver/transmitter + + + + + + int ioctl + int fd + int request + struct v4l2_dv_timings_cap *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_DV_TIMINGS_CAP + + + + argp + + + + + + + + + Description + + + Experimental + This is an experimental + interface and may change in the future. + + + To query the available timings, applications initialize the +index field and zero the reserved array of &v4l2-dv-timings-cap; +and call the VIDIOC_DV_TIMINGS_CAP ioctl with a pointer to this +structure. Drivers fill the rest of the structure or return an +&EINVAL; when the index is out of bounds. To enumerate all supported DV timings, +applications shall begin at index zero, incrementing by one until the +driver returns EINVAL. Note that drivers may enumerate a +different set of DV timings after switching the video input or +output. + + + struct <structname>v4l2_bt_timings_cap</structname> + + &cs-str; + + + __u32 + min_width + Minimum width of the active video in pixels. + + + __u32 + max_width + Maximum width of the active video in pixels. + + + __u32 + min_height + Minimum height of the active video in lines. + + + __u32 + max_height + Maximum height of the active video in lines. + + + __u64 + min_pixelclock + Minimum pixelclock frequency in Hz. + + + __u64 + max_pixelclock + Maximum pixelclock frequency in Hz. + + + __u32 + standards + The video standard(s) supported by the hardware. + See for a list of standards. + + + __u32 + capabilities + Several flags giving more information about the capabilities. + See for a description of the flags. + + + + __u32 + reserved[16] + + + + +
+ + + struct <structname>v4l2_dv_timings_cap</structname> + + &cs-str; + + + __u32 + type + Type of DV timings as listed in . + + + __u32 + reserved[3] + Reserved for future extensions. Drivers must set the array to zero. + + + union + + + + + + &v4l2-bt-timings-cap; + bt + BT.656/1120 timings capabilities of the hardware. + + + + __u32 + raw_data[32] + + + + +
+ + + DV BT Timing capabilities + + &cs-str; + + + Flag + Description + + + + + + + V4L2_DV_BT_CAP_INTERLACED + Interlaced formats are supported. + + + + V4L2_DV_BT_CAP_PROGRESSIVE + Progressive formats are supported. + + + + V4L2_DV_BT_CAP_REDUCED_BLANKING + CVT/GTF specific: the timings can make use of reduced blanking (CVT) +or the 'Secondary GTF' curve (GTF). + + + + V4L2_DV_BT_CAP_CUSTOM + Can support non-standard timings, i.e. timings not belonging to the +standards set in the standards field. + + + + +
+ + + + &return-value; + + + + diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml index 0be17c232d3a..509f0012d2a6 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml @@ -48,6 +48,10 @@ Description + This ioctl is deprecated. + New drivers and applications should use &VIDIOC-ENUM-DV-TIMINGS; instead. + + To query the attributes of a DV preset, applications initialize the index field and zero the reserved array of &v4l2-dv-enum-preset; and call the VIDIOC_ENUM_DV_PRESETS ioctl with a pointer to this diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml new file mode 100644 index 000000000000..24c3bf4fd29a --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml @@ -0,0 +1,119 @@ + + + ioctl VIDIOC_ENUM_DV_TIMINGS + &manvol; + + + + VIDIOC_ENUM_DV_TIMINGS + Enumerate supported Digital Video timings + + + + + + int ioctl + int fd + int request + struct v4l2_enum_dv_timings *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_ENUM_DV_TIMINGS + + + + argp + + + + + + + + + Description + + + Experimental + This is an experimental + interface and may change in the future. + + + While some DV receivers or transmitters support a wide range of timings, others +support only a limited number of timings. With this ioctl applications can enumerate a list +of known supported timings. Call &VIDIOC-DV-TIMINGS-CAP; to check if it also supports other +standards or even custom timings that are not in this list. + + To query the available timings, applications initialize the +index field and zero the reserved array of &v4l2-enum-dv-timings; +and call the VIDIOC_ENUM_DV_TIMINGS ioctl with a pointer to this +structure. Drivers fill the rest of the structure or return an +&EINVAL; when the index is out of bounds. To enumerate all supported DV timings, +applications shall begin at index zero, incrementing by one until the +driver returns EINVAL. Note that drivers may enumerate a +different set of DV timings after switching the video input or +output. + + + struct <structname>v4l2_enum_dv_timings</structname> + + &cs-str; + + + __u32 + index + Number of the DV timings, set by the +application. + + + __u32 + reserved[3] + Reserved for future extensions. Drivers must set the array to zero. + + + &v4l2-dv-timings; + timings + The timings. + + + +
+ + + + &return-value; + + + + EINVAL + + The &v4l2-enum-dv-timings; index +is out of bounds. + + + + + + + diff --git a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml index 9b8efcd6e947..46d5a044a537 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml @@ -285,7 +285,7 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. V4L2_IN_CAP_CUSTOM_TIMINGS 0x00000002 - This input supports setting custom video timings by using VIDIOC_S_DV_TIMINGS. + This input supports setting video timings by using VIDIOC_S_DV_TIMINGS. V4L2_IN_CAP_STD diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml index a64d5ef103fa..428020000ef0 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml @@ -170,7 +170,7 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. V4L2_OUT_CAP_CUSTOM_TIMINGS 0x00000002 - This output supports setting custom video timings by using VIDIOC_S_DV_TIMINGS. + This output supports setting video timings by using VIDIOC_S_DV_TIMINGS. V4L2_OUT_CAP_STD diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml index 4a8648ae9a63..eda1a2991bbe 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml @@ -7,7 +7,7 @@ VIDIOC_G_DV_TIMINGS VIDIOC_S_DV_TIMINGS - Get or set custom DV timings for input or output + Get or set DV timings for input or output @@ -48,12 +48,15 @@ Description - To set custom DV timings for the input or output, applications use the -VIDIOC_S_DV_TIMINGS ioctl and to get the current custom timings, + To set DV timings for the input or output, applications use the +VIDIOC_S_DV_TIMINGS ioctl and to get the current timings, applications use the VIDIOC_G_DV_TIMINGS ioctl. The detailed timing information is filled in using the structure &v4l2-dv-timings;. These ioctls take a pointer to the &v4l2-dv-timings; structure as argument. If the ioctl is not supported or the timing values are not correct, the driver returns &EINVAL;. +The linux/v4l2-dv-timings.h header can be used to get the +timings of the formats in the and +standards. @@ -83,12 +86,13 @@ or the timing values are not correct, the driver returns &EINVAL;. __u32 width - Width of the active video in pixels + Width of the active video in pixels. __u32 height - Height of the active video in lines + Height of the active video frame in lines. So for interlaced formats the + height of the active video in each field is height/2. __u32 @@ -125,32 +129,52 @@ bit 0 (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit 1 (V4L2_DV_H __u32 vfrontporch - Vertical front porch in lines + Vertical front porch in lines. For interlaced formats this refers to the + odd field (aka field 1). __u32 vsync - Vertical sync length in lines + Vertical sync length in lines. For interlaced formats this refers to the + odd field (aka field 1). __u32 vbackporch - Vertical back porch in lines + Vertical back porch in lines. For interlaced formats this refers to the + odd field (aka field 1). __u32 il_vfrontporch - Vertical front porch in lines for bottom field of interlaced field formats + Vertical front porch in lines for the even field (aka field 2) of + interlaced field formats. __u32 il_vsync - Vertical sync length in lines for bottom field of interlaced field formats + Vertical sync length in lines for the even field (aka field 2) of + interlaced field formats. __u32 il_vbackporch - Vertical back porch in lines for bottom field of interlaced field formats + Vertical back porch in lines for the even field (aka field 2) of + interlaced field formats. + + + __u32 + standards + The video standard(s) this format belongs to. This will be filled in by + the driver. Applications must set this to 0. See + for a list of standards. + + + __u32 + flags + Several flags giving more information about the format. + See for a description of the flags. + @@ -211,6 +235,90 @@ bit 0 (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit 1 (V4L2_DV_H + + DV BT Timing standards + + &cs-str; + + + Timing standard + Description + + + + + + + V4L2_DV_BT_STD_CEA861 + The timings follow the CEA-861 Digital TV Profile standard + + + V4L2_DV_BT_STD_DMT + The timings follow the VESA Discrete Monitor Timings standard + + + V4L2_DV_BT_STD_CVT + The timings follow the VESA Coordinated Video Timings standard + + + V4L2_DV_BT_STD_GTF + The timings follow the VESA Generalized Timings Formula standard + + + +
+ + DV BT Timing flags + + &cs-str; + + + Flag + Description + + + + + + + V4L2_DV_FL_REDUCED_BLANKING + CVT/GTF specific: the timings use reduced blanking (CVT) or the 'Secondary +GTF' curve (GTF). In both cases the horizontal and/or vertical blanking +intervals are reduced, allowing a higher resolution over the same +bandwidth. This is a read-only flag, applications must not set this. + + + + V4L2_DV_FL_CAN_REDUCE_FPS + CEA-861 specific: set for CEA-861 formats with a framerate that is a multiple +of six. These formats can be optionally played at 1 / 1.001 speed to +be compatible with 60 Hz based standards such as NTSC and PAL-M that use a framerate of +29.97 frames per second. If the transmitter can't generate such frequencies, then the +flag will also be cleared. This is a read-only flag, applications must not set this. + + + + V4L2_DV_FL_REDUCED_FPS + CEA-861 specific: only valid for video transmitters, the flag is cleared +by receivers. It is also only valid for formats with the V4L2_DV_FL_CAN_REDUCE_FPS flag +set, for other formats the flag will be cleared by the driver. + +If the application sets this flag, then the pixelclock used to set up the transmitter is +divided by 1.001 to make it compatible with NTSC framerates. If the transmitter +can't generate such frequencies, then the flag will also be cleared. + + + + V4L2_DV_FL_HALF_LINE + Specific to interlaced formats: if set, then field 1 (aka the odd field) +is really one half-line longer and field 2 (aka the even field) is really one half-line +shorter, so each field has exactly the same number of half-lines. Whether half-lines can be +detected or used depends on the hardware. + + + + +
&return-value; diff --git a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml index 7bde698760e4..fa7ad7e33228 100644 --- a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml @@ -48,6 +48,12 @@ Description + + Experimental + This is an experimental + interface and may change in the future. + + Applications can optionally call the VIDIOC_PREPARE_BUF ioctl to pass ownership of the buffer to the driver before actually enqueuing it, using the diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml new file mode 100644 index 000000000000..44935a0ffcf0 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml @@ -0,0 +1,104 @@ + + + ioctl VIDIOC_QUERY_DV_TIMINGS + &manvol; + + + + VIDIOC_QUERY_DV_TIMINGS + Sense the DV preset received by the current +input + + + + + + int ioctl + int fd + int request + struct v4l2_dv_timings *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_QUERY_DV_TIMINGS + + + + argp + + + + + + + + + Description + + + Experimental + This is an experimental + interface and may change in the future. + + + The hardware may be able to detect the current DV timings +automatically, similar to sensing the video standard. To do so, applications +call VIDIOC_QUERY_DV_TIMINGS with a pointer to a +&v4l2-dv-timings;. Once the hardware detects the timings, it will fill in the +timings structure. + +If the timings could not be detected because there was no signal, then +ENOLINK is returned. If a signal was detected, but +it was unstable and the receiver could not lock to the signal, then +ENOLCK is returned. If the receiver could lock to the signal, +but the format is unsupported (e.g. because the pixelclock is out of range +of the hardware capabilities), then the driver fills in whatever timings it +could find and returns ERANGE. In that case the application +can call &VIDIOC-DV-TIMINGS-CAP; to compare the found timings with the hardware's +capabilities in order to give more precise feedback to the user. + + + + + &return-value; + + + + ENOLINK + + No timings could be detected because no signal was found. + + + + + ENOLCK + + The signal was unstable and the hardware could not lock on to it. + + + + + ERANGE + + Timings were found, but they are out of range of the hardware +capabilities. + + + + + + -- 2.30.2