From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from mx1.redhat.com ([209.132.183.28]:44152 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752872Ab2B1LBG (ORCPT ); Tue, 28 Feb 2012 06:01:06 -0500 Message-ID: <4F4CB3ED.3080509@redhat.com> Date: Tue, 28 Feb 2012 08:01:01 -0300 From: Mauro Carvalho Chehab MIME-Version: 1.0 To: Hans Verkuil CC: linux-media@vger.kernel.org, Hans Verkuil Subject: Re: [RFCv1 PATCH 4/6] V4L2 spec: document the new V4L2 DV timings ioctls. References: <1328263566-21620-1-git-send-email-hverkuil@xs4all.nl> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Sender: linux-media-owner@vger.kernel.org List-ID: Em 03-02-2012 08:06, Hans Verkuil escreveu: > From: Hans Verkuil The comments for patch 1 apply here. So, I won't repeat myself ;) There's just one minor comment below. > > Signed-off-by: Hans Verkuil > --- > Documentation/DocBook/media/v4l/v4l2.xml | 3 + > .../DocBook/media/v4l/vidioc-dv-timings-cap.xml | 205 ++++++++++++++++++++ > .../DocBook/media/v4l/vidioc-enum-dv-timings.xml | 113 +++++++++++ > .../DocBook/media/v4l/vidioc-g-dv-timings.xml | 120 +++++++++++- > .../DocBook/media/v4l/vidioc-query-dv-timings.xml | 98 ++++++++++ > 5 files changed, 531 insertions(+), 8 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/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml > index dce3fef..8bc2ccd 100644 > --- a/Documentation/DocBook/media/v4l/v4l2.xml > +++ b/Documentation/DocBook/media/v4l/v4l2.xml > @@ -481,10 +481,12 @@ and discussions on the V4L mailing list. > &sub-dbg-g-chip-ident; > &sub-dbg-g-register; > &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; > @@ -519,6 +521,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-dv-timings-cap.xml b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml > new file mode 100644 > index 0000000..0477de1 > --- /dev/null > +++ b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml > @@ -0,0 +1,205 @@ > + > + > + 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 > + > + 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-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml > new file mode 100644 > index 0000000..edd6964 > --- /dev/null > +++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml > @@ -0,0 +1,113 @@ > + > + > + 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 > + > + 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. > + > + > + > + > + > + > + Don't insert editor-specific parameters at the file! That violates CodingStyle. > diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml > index 4a8648a..bffd26c 100644 > --- a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml > +++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml > @@ -83,12 +83,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 +126,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 +232,89 @@ 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_NTSC_COMPATIBLE > + CEA-861 specific: set for CEA-861 formats with a framerate of a multiple > +of six. These formats can be optionally played at 1 / 1.001 speed to > +be compatible with the normal NTSC framerate of 29.97 frames per second. > +This is a read-only flag, applications must not set this. > + > + > + > + V4L2_DV_FL_DIVIDE_CLOCK_BY_1_001 > + 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_NTSC_COMPATIBLE 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-query-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml > new file mode 100644 > index 0000000..9d7ac43 > --- /dev/null > +++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml > @@ -0,0 +1,98 @@ > + > + > + 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 > + > + 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. > + > + > + > + > + > +