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

Commit 007701e2 authored by Muralidharan Karicheri's avatar Muralidharan Karicheri Committed by Mauro Carvalho Chehab
Browse files

V4L/DVB (13572): v4l2-spec: Digital Video Timings API documentation 



This patch updates the v4l2-dvb documentation for the new video timings API added.
Also updated the document based on comments from Hans Verkuil.

Signed-off-by: default avatarMuralidharan Karicheri <m-karicheri2@ti.com>
Signed-off-by: default avatarHans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent b6456c0c

Documentation/DocBook/media-entities.tmpl

+18 −0
Original line number Diff line number Diff line
@@ -23,6 +23,7 @@ 
<!ENTITY VIDIOC-ENUMINPUT "<link linkend='vidioc-enuminput'><constant>VIDIOC_ENUMINPUT</constant></link>">

<!ENTITY VIDIOC-ENUMOUTPUT "<link linkend='vidioc-enumoutput'><constant>VIDIOC_ENUMOUTPUT</constant></link>">

<!ENTITY VIDIOC-ENUMSTD "<link linkend='vidioc-enumstd'><constant>VIDIOC_ENUMSTD</constant></link>">

<!ENTITY VIDIOC-ENUM-DV-PRESETS "<link linkend='vidioc-enum-dv-presets'><constant>VIDIOC_ENUM_DV_PRESETS</constant></link>">

<!ENTITY VIDIOC-ENUM-FMT "<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link>">

<!ENTITY VIDIOC-ENUM-FRAMEINTERVALS "<link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link>">

<!ENTITY VIDIOC-ENUM-FRAMESIZES "<link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link>">
@@ -30,6 +31,8 @@ 
<!ENTITY VIDIOC-G-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_G_AUDOUT</constant></link>">

<!ENTITY VIDIOC-G-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_G_CROP</constant></link>">

<!ENTITY VIDIOC-G-CTRL "<link linkend='vidioc-g-ctrl'><constant>VIDIOC_G_CTRL</constant></link>">

<!ENTITY VIDIOC-G-DV-PRESET "<link linkend='vidioc-g-dv-preset'><constant>VIDIOC_G_DV_PRESET</constant></link>">

<!ENTITY VIDIOC-G-DV-TIMINGS "<link linkend='vidioc-g-dv-timings'><constant>VIDIOC_G_DV_TIMINGS</constant></link>">

<!ENTITY VIDIOC-G-ENC-INDEX "<link linkend='vidioc-g-enc-index'><constant>VIDIOC_G_ENC_INDEX</constant></link>">

<!ENTITY VIDIOC-G-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_G_EXT_CTRLS</constant></link>">

<!ENTITY VIDIOC-G-FBUF "<link linkend='vidioc-g-fbuf'><constant>VIDIOC_G_FBUF</constant></link>">
@@ -53,6 +56,7 @@ 
<!ENTITY VIDIOC-QUERYCTRL "<link linkend='vidioc-queryctrl'><constant>VIDIOC_QUERYCTRL</constant></link>">

<!ENTITY VIDIOC-QUERYMENU "<link linkend='vidioc-queryctrl'><constant>VIDIOC_QUERYMENU</constant></link>">

<!ENTITY VIDIOC-QUERYSTD "<link linkend='vidioc-querystd'><constant>VIDIOC_QUERYSTD</constant></link>">

<!ENTITY VIDIOC-QUERY-DV-PRESET "<link linkend='vidioc-query-dv-preset'><constant>VIDIOC_QUERY_DV_PRESET</constant></link>">

<!ENTITY VIDIOC-REQBUFS "<link linkend='vidioc-reqbufs'><constant>VIDIOC_REQBUFS</constant></link>">

<!ENTITY VIDIOC-STREAMOFF "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMOFF</constant></link>">

<!ENTITY VIDIOC-STREAMON "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMON</constant></link>">
@@ -60,6 +64,8 @@ 
<!ENTITY VIDIOC-S-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_S_AUDOUT</constant></link>">

<!ENTITY VIDIOC-S-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_S_CROP</constant></link>">

<!ENTITY VIDIOC-S-CTRL "<link linkend='vidioc-g-ctrl'><constant>VIDIOC_S_CTRL</constant></link>">

<!ENTITY VIDIOC-S-DV-PRESET "<link linkend='vidioc-g-dv-preset'><constant>VIDIOC_S_DV_PRESET</constant></link>">

<!ENTITY VIDIOC-S-DV-TIMINGS "<link linkend='vidioc-g-dv-timings'><constant>VIDIOC_S_DV_TIMINGS</constant></link>">

<!ENTITY VIDIOC-S-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_S_EXT_CTRLS</constant></link>">

<!ENTITY VIDIOC-S-FBUF "<link linkend='vidioc-g-fbuf'><constant>VIDIOC_S_FBUF</constant></link>">

<!ENTITY VIDIOC-S-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link>">
@@ -118,6 +124,7 @@ 
<!-- Structures -->

<!ENTITY v4l2-audio "struct&nbsp;<link linkend='v4l2-audio'>v4l2_audio</link>">

<!ENTITY v4l2-audioout "struct&nbsp;<link linkend='v4l2-audioout'>v4l2_audioout</link>">

<!ENTITY v4l2-bt-timings "struct&nbsp;<link linkend='v4l2-bt-timings'>v4l2_bt_timings</link>">

<!ENTITY v4l2-buffer "struct&nbsp;<link linkend='v4l2-buffer'>v4l2_buffer</link>">

<!ENTITY v4l2-capability "struct&nbsp;<link linkend='v4l2-capability'>v4l2_capability</link>">

<!ENTITY v4l2-captureparm "struct&nbsp;<link linkend='v4l2-captureparm'>v4l2_captureparm</link>">
@@ -128,6 +135,9 @@ 
<!ENTITY v4l2-dbg-chip-ident "struct&nbsp;<link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link>">

<!ENTITY v4l2-dbg-match "struct&nbsp;<link linkend='v4l2-dbg-match'>v4l2_dbg_match</link>">

<!ENTITY v4l2-dbg-register "struct&nbsp;<link linkend='v4l2-dbg-register'>v4l2_dbg_register</link>">

<!ENTITY v4l2-dv-enum-preset "struct&nbsp;<link linkend='v4l2-dv-enum-preset'>v4l2_dv_enum_preset</link>">

<!ENTITY v4l2-dv-preset "struct&nbsp;<link linkend='v4l2-dv-preset'>v4l2_dv_preset</link>">

<!ENTITY v4l2-dv-timings "struct&nbsp;<link linkend='v4l2-dv-timings'>v4l2_dv_timings</link>">

<!ENTITY v4l2-enc-idx "struct&nbsp;<link linkend='v4l2-enc-idx'>v4l2_enc_idx</link>">

<!ENTITY v4l2-enc-idx-entry "struct&nbsp;<link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link>">

<!ENTITY v4l2-encoder-cmd "struct&nbsp;<link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link>">
@@ -243,6 +253,10 @@ 
<!ENTITY sub-enumaudioout SYSTEM "v4l/vidioc-enumaudioout.xml">

<!ENTITY sub-enuminput SYSTEM "v4l/vidioc-enuminput.xml">

<!ENTITY sub-enumoutput SYSTEM "v4l/vidioc-enumoutput.xml">

<!ENTITY sub-enum-dv-presets SYSTEM "v4l/vidioc-enum-dv-presets.xml">

<!ENTITY sub-g-dv-preset SYSTEM "v4l/vidioc-g-dv-preset.xml">

<!ENTITY sub-query-dv-preset SYSTEM "v4l/vidioc-query-dv-preset.xml">

<!ENTITY sub-g-dv-timings SYSTEM "v4l/vidioc-g-dv-timings.xml">

<!ENTITY sub-enumstd SYSTEM "v4l/vidioc-enumstd.xml">

<!ENTITY sub-g-audio SYSTEM "v4l/vidioc-g-audio.xml">

<!ENTITY sub-g-audioout SYSTEM "v4l/vidioc-g-audioout.xml">
@@ -333,6 +347,10 @@ 
<!ENTITY enumaudioout SYSTEM "v4l/vidioc-enumaudioout.xml">

<!ENTITY enuminput SYSTEM "v4l/vidioc-enuminput.xml">

<!ENTITY enumoutput SYSTEM "v4l/vidioc-enumoutput.xml">

<!ENTITY enum-dv-presets SYSTEM "v4l/vidioc-enum-dv-presets.xml">

<!ENTITY g-dv-preset SYSTEM "v4l/vidioc-g-dv-preset.xml">

<!ENTITY query-dv-preset SYSTEM "v4l/vidioc-query-dv-preset.xml">

<!ENTITY g-dv-timings SYSTEM "v4l/vidioc-g-dv-timings.xml">

<!ENTITY enumstd SYSTEM "v4l/vidioc-enumstd.xml">

<!ENTITY g-audio SYSTEM "v4l/vidioc-g-audio.xml">

<!ENTITY g-audioout SYSTEM "v4l/vidioc-g-audioout.xml">

Documentation/DocBook/media-indices.tmpl

+4 −0
Original line number Diff line number Diff line
@@ -36,6 +36,7 @@ 
<indexentry><primaryie>enum&nbsp;<link linkend='v4l2-preemphasis'>v4l2_preemphasis</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-audio'>v4l2_audio</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-audioout'>v4l2_audioout</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-bt-timings'>v4l2_bt_timings</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-buffer'>v4l2_buffer</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-capability'>v4l2_capability</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-captureparm'>v4l2_captureparm</link></primaryie></indexentry>
@@ -46,6 +47,9 @@ 
<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dbg-match'>v4l2_dbg_match</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dbg-register'>v4l2_dbg_register</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dv-enum-preset'>v4l2_dv_enum_preset</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dv-preset'>v4l2_dv_preset</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-dv-timings'>v4l2_dv_timings</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-enc-idx'>v4l2_enc_idx</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link></primaryie></indexentry>

<indexentry><primaryie>struct&nbsp;<link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link></primaryie></indexentry>

Documentation/DocBook/v4l/common.xml

+35 −0
Original line number Diff line number Diff line
@@ -716,6 +716,41 @@ if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) { 
}

      </programlisting>

    </example>

  <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

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

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

	<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/v4l/v4l2.xml

+4 −0
Original line number Diff line number Diff line
@@ -411,6 +411,7 @@ and discussions on the V4L mailing list.</revremark> 
    &sub-encoder-cmd;

    &sub-enumaudio;

    &sub-enumaudioout;

    &sub-enum-dv-presets;

    &sub-enum-fmt;

    &sub-enum-framesizes;

    &sub-enum-frameintervals;
@@ -421,6 +422,8 @@ and discussions on the V4L mailing list.</revremark> 
    &sub-g-audioout;

    &sub-g-crop;

    &sub-g-ctrl;

    &sub-g-dv-preset;

    &sub-g-dv-timings;

    &sub-g-enc-index;

    &sub-g-ext-ctrls;

    &sub-g-fbuf;
@@ -441,6 +444,7 @@ and discussions on the V4L mailing list.</revremark> 
    &sub-querybuf;

    &sub-querycap;

    &sub-queryctrl;

    &sub-query-dv-preset;

    &sub-querystd;

    &sub-reqbufs;

    &sub-s-hw-freq-seek;

Documentation/DocBook/v4l/videodev2.h.xml

+114 −2
Original line number Diff line number Diff line
@@ -733,6 +733,99 @@ struct <link linkend="v4l2-standard">v4l2_standard</link> { 
        __u32                reserved[4];

};



/*

 *      V I D E O       T I M I N G S   D V     P R E S E T

 */

struct <link linkend="v4l2-dv-preset">v4l2_dv_preset</link> {

        __u32   preset;

        __u32   reserved[4];

};



/*

 *      D V     P R E S E T S   E N U M E R A T I O N

 */

struct <link linkend="v4l2-dv-enum-preset">v4l2_dv_enum_preset</link> {

        __u32   index;

        __u32   preset;

        __u8    name[32]; /* Name of the preset timing */

        __u32   width;

        __u32   height;

        __u32   reserved[4];

};



/*

 *      D V     P R E S E T     V A L U E S

 */

#define         V4L2_DV_INVALID         0

#define         V4L2_DV_480P59_94       1 /* BT.1362 */

#define         V4L2_DV_576P50          2 /* BT.1362 */

#define         V4L2_DV_720P24          3 /* SMPTE 296M */

#define         V4L2_DV_720P25          4 /* SMPTE 296M */

#define         V4L2_DV_720P30          5 /* SMPTE 296M */

#define         V4L2_DV_720P50          6 /* SMPTE 296M */

#define         V4L2_DV_720P59_94       7 /* SMPTE 274M */

#define         V4L2_DV_720P60          8 /* SMPTE 274M/296M */

#define         V4L2_DV_1080I29_97      9 /* BT.1120/ SMPTE 274M */

#define         V4L2_DV_1080I30         10 /* BT.1120/ SMPTE 274M */

#define         V4L2_DV_1080I25         11 /* BT.1120 */

#define         V4L2_DV_1080I50         12 /* SMPTE 296M */

#define         V4L2_DV_1080I60         13 /* SMPTE 296M */

#define         V4L2_DV_1080P24         14 /* SMPTE 296M */

#define         V4L2_DV_1080P25         15 /* SMPTE 296M */

#define         V4L2_DV_1080P30         16 /* SMPTE 296M */

#define         V4L2_DV_1080P50         17 /* BT.1120 */

#define         V4L2_DV_1080P60         18 /* BT.1120 */



/*

 *      D V     B T     T I M I N G S

 */



/* BT.656/BT.1120 timing data */

struct <link linkend="v4l2-bt-timings">v4l2_bt_timings</link> {

        __u32   width;          /* width in pixels */

        __u32   height;         /* height in lines */

        __u32   interlaced;     /* Interlaced or progressive */

        __u32   polarities;     /* Positive or negative polarity */

        __u64   pixelclock;     /* Pixel clock in HZ. Ex. 74.25MHz-&gt;74250000 */

        __u32   hfrontporch;    /* Horizpontal front porch in pixels */

        __u32   hsync;          /* Horizontal Sync length in pixels */

        __u32   hbackporch;     /* Horizontal back porch in pixels */

        __u32   vfrontporch;    /* Vertical front porch in pixels */

        __u32   vsync;          /* Vertical Sync length in lines */

        __u32   vbackporch;     /* Vertical back porch in lines */

        __u32   il_vfrontporch; /* Vertical front porch for bottom field of

                                 * interlaced field formats

                                 */

        __u32   il_vsync;       /* Vertical sync length for bottom field of

                                 * interlaced field formats

                                 */

        __u32   il_vbackporch;  /* Vertical back porch for bottom field of

                                 * interlaced field formats

                                 */

        __u32   reserved[16];

} __attribute__ ((packed));



/* Interlaced or progressive format */

#define V4L2_DV_PROGRESSIVE     0

#define V4L2_DV_INTERLACED      1



/* Polarities. If bit is not set, it is assumed to be negative polarity */

#define V4L2_DV_VSYNC_POS_POL   0x00000001

#define V4L2_DV_HSYNC_POS_POL   0x00000002





/* DV timings */

struct <link linkend="v4l2-dv-timings">v4l2_dv_timings</link> {

        __u32 type;

        union {

                struct <link linkend="v4l2-bt-timings">v4l2_bt_timings</link>  bt;

                __u32   reserved[32];

        };

} __attribute__ ((packed));



/* Values for the type field */

#define V4L2_DV_BT_656_1120     0       /* BT.656/1120 timing type */



/*

 *      V I D E O   I N P U T S

 */
@@ -744,7 +837,8 @@ struct <link linkend="v4l2-input">v4l2_input</link> { 
        __u32        tuner;             /*  Associated tuner */

        v4l2_std_id  std;

        __u32        status;

        __u32        reserved[4];

        __u32        capabilities;

        __u32        reserved[3];

};



/*  Values for the 'type' field */
@@ -775,6 +869,11 @@ struct <link linkend="v4l2-input">v4l2_input</link> { 
#define V4L2_IN_ST_NO_ACCESS   0x02000000  /* Conditional access denied */

#define V4L2_IN_ST_VTR         0x04000000  /* VTR time constant */



/* capabilities flags */

#define V4L2_IN_CAP_PRESETS             0x00000001 /* Supports S_DV_PRESET */

#define V4L2_IN_CAP_CUSTOM_TIMINGS      0x00000002 /* Supports S_DV_TIMINGS */

#define V4L2_IN_CAP_STD                 0x00000004 /* Supports S_STD */



/*

 *      V I D E O   O U T P U T S

 */
@@ -785,13 +884,19 @@ struct <link linkend="v4l2-output">v4l2_output</link> { 
        __u32        audioset;          /*  Associated audios (bitfield) */

        __u32        modulator;         /*  Associated modulator */

        v4l2_std_id  std;

        __u32        reserved[4];

        __u32        capabilities;

        __u32        reserved[3];

};

/*  Values for the 'type' field */

#define V4L2_OUTPUT_TYPE_MODULATOR              1

#define V4L2_OUTPUT_TYPE_ANALOG                 2

#define V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY       3



/* capabilities flags */

#define V4L2_OUT_CAP_PRESETS            0x00000001 /* Supports S_DV_PRESET */

#define V4L2_OUT_CAP_CUSTOM_TIMINGS     0x00000002 /* Supports S_DV_TIMINGS */

#define V4L2_OUT_CAP_STD                0x00000004 /* Supports S_STD */



/*

 *      C O N T R O L S

 */
@@ -1626,6 +1731,13 @@ struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link> { 
#endif



#define VIDIOC_S_HW_FREQ_SEEK    _IOW('V', 82, struct <link linkend="v4l2-hw-freq-seek">v4l2_hw_freq_seek</link>)

#define VIDIOC_ENUM_DV_PRESETS  _IOWR('V', 83, struct <link linkend="v4l2-dv-enum-preset">v4l2_dv_enum_preset</link>)

#define VIDIOC_S_DV_PRESET      _IOWR('V', 84, struct <link linkend="v4l2-dv-preset">v4l2_dv_preset</link>)

#define VIDIOC_G_DV_PRESET      _IOWR('V', 85, struct <link linkend="v4l2-dv-preset">v4l2_dv_preset</link>)

#define VIDIOC_QUERY_DV_PRESET  _IOR('V',  86, struct <link linkend="v4l2-dv-preset">v4l2_dv_preset</link>)

#define VIDIOC_S_DV_TIMINGS     _IOWR('V', 87, struct <link linkend="v4l2-dv-timings">v4l2_dv_timings</link>)

#define VIDIOC_G_DV_TIMINGS     _IOWR('V', 88, struct <link linkend="v4l2-dv-timings">v4l2_dv_timings</link>)



/* Reminder: when adding new ioctls please add support for them to

   drivers/media/video/v4l2-compat-ioctl32.c as well! */