Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 7dcc606b authored by Hans Verkuil's avatar Hans Verkuil Committed by Mauro Carvalho Chehab
Browse files

[media] V4L2 spec: document the new V4L2 DV timings ioctls 



Signed-off-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
Reviewed-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 06bba75d

Documentation/DocBook/media/v4l/biblio.xml

+18 −0
Original line number Diff line number Diff line
@@ -208,4 +208,22 @@ in the frequency range from 87,5 to 108,0 MHz</title> 
      recommended exposure index</title>

    </biblioentry>



    <biblioentry id="cea861">

      <abbrev>CEA-861-E</abbrev>

      <authorgroup>

	<corpauthor>Consumer Electronics Association

(<ulink url="http://www.ce.org">http://www.ce.org</ulink>)</corpauthor>

      </authorgroup>

      <title>A DTV Profile for Uncompressed High Speed Digital Interfaces</title>

    </biblioentry>



    <biblioentry id="vesadmt">

      <abbrev>VESA&nbsp;DMT</abbrev>

      <authorgroup>

	<corpauthor>Video Electronics Standards Association

(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor>

      </authorgroup>

      <title>VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT)</title>

    </biblioentry>



  </bibliography>

Documentation/DocBook/media/v4l/common.xml

+19 −13
Original line number Diff line number Diff line
@@ -724,42 +724,48 @@ if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) { 
}

      </programlisting>

    </example>

  </section>

  <section id="dv-timings">

	<title>Digital Video (DV) Timings</title>

	<para>

	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: </para><itemizedlist>

	<listitem>

	<para>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 <filename>linux/v4l2-dv-timings.h</filename>

header can be used to get the timings of the formats in the <xref linkend="cea861" /> and

<xref linkend="vesadmt" /> standards.

	</para>

	</listitem>

	<listitem>

	<para>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.</para>

	</listitem>

	<listitem>

	<para>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.

	</para>

	</listitem>

	</itemizedlist>

	<para>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.</para>

	<para>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.</para>

	<para>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.</para>

&VIDIOC-S-DV-PRESET; ioctl. To detect the preset as seen by the video receiver applications

use the &VIDIOC-QUERY-DV-PRESET; ioctl.</para>

	<para>Applications can make use of the <xref linkend="input-capabilities" /> and

<xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the

video timings for the device.</para>

  </section>

  </section>



  &sub-controls;

Documentation/DocBook/media/v4l/compat.xml

+13 −0
Original line number Diff line number Diff line
@@ -2407,6 +2407,11 @@ details.</para> 
	  <para>Added <link linkend="jpeg-controls">JPEG compression control

	  class</link>.</para>

        </listitem>

        <listitem>

	  <para>Extended the DV Timings API:

	  &VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and

	  &VIDIOC-DV-TIMINGS-CAP;.</para>

        </listitem>

      </orderedlist>

    </section>
@@ -2548,6 +2553,10 @@ and may change in the future.</para> 
        </listitem>

        <listitem>

	  <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD;

ioctls.</para>

        </listitem>

        <listitem>

	  <para>&VIDIOC-DECODER-CMD; and &VIDIOC-TRY-DECODER-CMD;

ioctls.</para>

        </listitem>

        <listitem>
@@ -2557,6 +2566,10 @@ ioctls.</para> 
        <listitem>

	  <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>

        </listitem>

        <listitem>

	  <para>&VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and

	  &VIDIOC-DV-TIMINGS-CAP; ioctls.</para>

        </listitem>

        <listitem>

	  <para>Flash API. <xref linkend="flash-controls" /></para>

        </listitem>

Documentation/DocBook/media/v4l/v4l2.xml

+12 −3
Original line number Diff line number Diff line
@@ -28,8 +28,8 @@ documentation.</contrib> 
	<firstname>Hans</firstname>

	<surname>Verkuil</surname>

	<contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl,

the extended control ioctls and major parts of the sliced VBI

API.</contrib>

the extended control ioctls, major parts of the sliced VBI API, the

MPEG encoder and decoder APIs and the DV Timings API.</contrib>

	<affiliation>

	  <address>

	    <email>hverkuil@xs4all.nl</email>
@@ -123,6 +123,7 @@ Remote Controller chapter.</contrib> 
      <year>2009</year>

      <year>2010</year>

      <year>2011</year>

      <year>2012</year>

      <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin

Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,

	Pawel Osciak</holder>
@@ -153,6 +154,11 @@ applications. --> 
	    V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS

	    and V4L2_CID_AUTO_FOCUS_RANGE.

	</revremark>

	<date>2012-05-01</date>

	<authorinitials>hv</authorinitials>

	<revremark>Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and

	VIDIOC_DV_TIMINGS_CAP.

	</revremark>

      </revision>



      <revision>
@@ -461,7 +467,7 @@ and discussions on the V4L mailing list.</revremark> 
</partinfo>



<title>Video for Linux Two API Specification</title>

 <subtitle>Revision 3.3</subtitle>

 <subtitle>Revision 3.5</subtitle>



  <chapter id="common">

    &sub-common;
@@ -519,10 +525,12 @@ and discussions on the V4L mailing list.</revremark> 
    &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.</revremark> 
    &sub-querycap;

    &sub-queryctrl;

    &sub-query-dv-preset;

    &sub-query-dv-timings;

    &sub-querystd;

    &sub-prepare-buf;

    &sub-reqbufs;

Documentation/DocBook/media/v4l/vidioc-create-bufs.xml

+6 −0
Original line number Diff line number Diff line
@@ -48,6 +48,12 @@ 
  <refsect1>

    <title>Description</title>



    <note>

      <title>Experimental</title>

      <para>This is an <link linkend="experimental"> experimental </link>

      interface and may change in the future.</para>

    </note>



    <para>This ioctl is used to create buffers for <link linkend="mmap">memory

mapped</link> or <link linkend="userp">user pointer</link>

I/O. It can be used as an alternative or in addition to the