From patchwork Wed Mar 11 19:25:28 2009 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andy Walls X-Patchwork-Id: 11194 Received: from vger.kernel.org (vger.kernel.org [209.132.176.167]) by demeter.kernel.org (8.14.2/8.14.2) with ESMTP id n2BJUUoj020573 for ; Wed, 11 Mar 2009 19:30:31 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753648AbZCKTa3 (ORCPT ); Wed, 11 Mar 2009 15:30:29 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1753242AbZCKTa3 (ORCPT ); Wed, 11 Mar 2009 15:30:29 -0400 Received: from mail1.radix.net ([207.192.128.31]:58967 "EHLO mail1.radix.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753045AbZCKTa1 (ORCPT ); Wed, 11 Mar 2009 15:30:27 -0400 Received: from [192.168.1.2] (01-114.155.popsite.net [66.217.131.114]) (authenticated bits=0) by mail1.radix.net (8.13.4/8.13.4) with ESMTP id n2BJP0kI003717; Wed, 11 Mar 2009 15:25:01 -0400 (EDT) Subject: [REVIEW] Draft of V4L2 API and spec changes for V4L2_MPEG_STREAM_VBI_FMT_IVTV From: Andy Walls To: linux-media@vger.kernel.org Cc: Mauro Carvalho Chehab , ivtv-devel@ivtvdriver.org, hverkuil@xs4all.nl Date: Wed, 11 Mar 2009 15:25:28 -0400 Message-Id: <1236799528.3111.15.camel@palomino.walls.org> Mime-Version: 1.0 X-Mailer: Evolution 2.24.1 (2.24.1-2.fc10) Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org All, The inline diff below has my completed draft of V4L2 API and Specifcation changes to add proper definitions and documentation for the MPEG stream embedded, sliced VBI data format triggered by the V4L2_MPEG_STREAM_VBI_FMT_IVTV control setting. These changes only add to the V4L2 API and do modify or remove exiting elements. Please review. The only question remaining in my mind is whether the type "__le32" can be used in the userspace API structures. I think it can, but I don't know what kernel version introduced "__le32". Mauro, When I make a pull request for this, do you want 1 request, or separate requests for videodev2.h changes and v4l2-spec changes? Regards, Andy Reviewed-by: Hans Verkuil --- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff -r 5361470b10f4 linux/include/linux/ivtv.h --- a/linux/include/linux/ivtv.h Sun Mar 01 21:10:07 2009 -0500 +++ b/linux/include/linux/ivtv.h Wed Mar 11 15:09:50 2009 -0400 @@ -60,10 +60,10 @@ #define IVTV_IOC_DMA_FRAME _IOW ('V', BASE_VIDIOC_PRIVATE+0, struct ivtv_dma_frame) -/* These are the VBI types as they appear in the embedded VBI private packets. */ -#define IVTV_SLICED_TYPE_TELETEXT_B (1) -#define IVTV_SLICED_TYPE_CAPTION_525 (4) -#define IVTV_SLICED_TYPE_WSS_625 (5) -#define IVTV_SLICED_TYPE_VPS (7) +/* Deprecated defines: applications should use the defines from videodev2.h */ +#define IVTV_SLICED_TYPE_TELETEXT_B V4L2_MPEG_VBI_IVTV_TELETEXT_B +#define IVTV_SLICED_TYPE_CAPTION_525 V4L2_MPEG_VBI_IVTV_CAPTION_525 +#define IVTV_SLICED_TYPE_WSS_625 V4L2_MPEG_VBI_IVTV_WSS_625 +#define IVTV_SLICED_TYPE_VPS V4L2_MPEG_VBI_IVTV_VPS #endif /* _LINUX_IVTV_H */ diff -r 5361470b10f4 linux/include/linux/videodev2.h --- a/linux/include/linux/videodev2.h Sun Mar 01 21:10:07 2009 -0500 +++ b/linux/include/linux/videodev2.h Wed Mar 11 15:09:50 2009 -0400 @@ -1348,6 +1348,53 @@ }; /* + * Sliced VBI data inserted into MPEG Streams + */ + +/* + * V4L2_MPEG_STREAM_VBI_FMT_IVTV: + * + * Structure of payload contained in an MPEG 2 Private Stream 1 PES Packet in an + * MPEG-2 Program Pack that contains V4L2_MPEG_STREAM_VBI_FMT_IVTV Sliced VBI + * data + * + * Note, the MPEG-2 Program Pack and Private Stream 1 PES packet header + * definitions are not included here. See the MPEG-2 specifications for details + * on these headers. + */ + +/* Line type IDs */ +#define V4L2_MPEG_VBI_IVTV_TELETEXT_B (1) +#define V4L2_MPEG_VBI_IVTV_CAPTION_525 (4) +#define V4L2_MPEG_VBI_IVTV_WSS_625 (5) +#define V4L2_MPEG_VBI_IVTV_VPS (7) + +struct v4l2_mpeg_vbi_itv0_line { + __u8 id; /* One of V4L2_MPEG_VBI_IVTV_* above */ + __u8 data[42]; /* Sliced VBI data for the line */ +} __attribute__ ((packed)); + +struct v4l2_mpeg_vbi_itv0 { + __le32 linemask[2]; /* Bitmasks of VBI service lines present */ + struct v4l2_mpeg_vbi_itv0_line line[35]; +} __attribute__ ((packed)); + +struct v4l2_mpeg_vbi_ITV0 { + struct v4l2_mpeg_vbi_itv0_line line[36]; +} __attribute__ ((packed)); + +#define V4L2_MPEG_VBI_IVTV_MAGIC0 "itv0" +#define V4L2_MPEG_VBI_IVTV_MAGIC1 "ITV0" + +struct v4l2_mpeg_vbi_fmt_ivtv { + __u8 magic[4]; + union { + struct v4l2_mpeg_vbi_itv0 itv0; + struct v4l2_mpeg_vbi_ITV0 ITV0; + }; +} __attribute__ ((packed)); + +/* * A G G R E G A T E S T R U C T U R E S */ diff -r 5361470b10f4 v4l2-spec/Makefile --- a/v4l2-spec/Makefile Sun Mar 01 21:10:07 2009 -0500 +++ b/v4l2-spec/Makefile Wed Mar 11 15:09:50 2009 -0400 @@ -274,6 +274,7 @@ v4l2_input \ v4l2_jpegcompression \ v4l2_modulator \ + v4l2_mpeg_vbi_fmt_ivtv \ v4l2_output \ v4l2_outputparm \ v4l2_pix_format \ diff -r 5361470b10f4 v4l2-spec/dev-sliced-vbi.sgml --- a/v4l2-spec/dev-sliced-vbi.sgml Sun Mar 01 21:10:07 2009 -0500 +++ b/v4l2-spec/dev-sliced-vbi.sgml Wed Mar 11 15:09:50 2009 -0400 @@ -48,7 +48,7 @@ supported. -
+
Sliced VBI Format Negotiation To find out which data services are supported by the @@ -386,6 +386,319 @@
+
+ Sliced VBI Data in MPEG Streams + + If a device can produce an MPEG output stream, it may be +capable of providing negotiated sliced VBI +services as data embedded in the MPEG stream. Users or +applications control this sliced VBI data insertion with the V4L2_CID_MPEG_STREAM_VBI_FMT +control. + + If the driver does not provide the V4L2_CID_MPEG_STREAM_VBI_FMT +control, or only allows that control to be set to +V4L2_MPEG_STREAM_VBI_FMT_NONE, then the device +cannot embed sliced VBI data in the MPEG stream. + + The +V4L2_CID_MPEG_STREAM_VBI_FMT control does not implicitly set +the device driver to capture nor cease capturing sliced VBI data. The +control only indicates to embed sliced VBI data in the MPEG stream, if +an application has negotiated sliced VBI service be captured. + + It may also be the case that a device can embed sliced VBI +data in only certain types of MPEG streams: for example in an MPEG-2 +PS but not an MPEG-2 TS. In this situation, if sliced VBI data +insertion is requested, the sliced VBI data will be embedded in MPEG +stream types when supported, and silently omitted from MPEG stream +types where sliced VBI data insertion is not supported by the device. + + + The following subsections specify the format of the +embedded sliced VBI data. + +
+ MPEG Stream Embedded, Sliced VBI Data Format: NONE + The +V4L2_MPEG_STREAM_VBI_FMT_NONE embedded sliced VBI +format shall be interpreted by drivers as a control to cease +embedding sliced VBI data in MPEG streams. Neither the device nor +driver shall insert "empty" embedded sliced VBI data packets in the +MPEG stream when this format is set. No MPEG stream data structures +are specified for this format. +
+ +
+ MPEG Stream Embedded, Sliced VBI Data Format: IVTV + The +V4L2_MPEG_STREAM_VBI_FMT_IVTV embedded sliced VBI +format, when supported, indicates to the driver to embed up to 36 +lines of sliced VBI data per frame in an MPEG-2 Private +Stream 1 PES packet encapsulated in an MPEG-2 +Program Pack in the MPEG stream. + + Historical context: This format +specification originates from a custom, embedded, sliced VBI data +format used by the ivtv driver. This format +has already been informally specified in the kernel sources in the +file Documentation/video4linux/cx2341x/README.vbi +. The maximum size of the payload and other aspects of this format +are driven by the CX23415 MPEG decoder's capabilities and limitations +with respect to extracting, decoding, and displaying sliced VBI data +embedded within an MPEG stream. + + This format's use is not exclusive to +the ivtv driver nor +exclusive to CX2341x devices, as the sliced VBI data packet insertion +into the MPEG stream is implemented in driver software. At least the +cx18 driver provides sliced VBI data insertion +into an MPEG-2 PS in this format as well. + + The following definitions specify the payload of the +MPEG-2 Private Stream 1 PES packets that contain +sliced VBI data when +V4L2_MPEG_STREAM_VBI_FMT_IVTV is set. +(The MPEG-2 Private Stream 1 PES packet header +and encapsulating MPEG-2 Program Pack header are +not detailed here. Please refer to the MPEG-2 specifications for +details on those packet headers.) + + The payload of the MPEG-2 Private Stream 1 PES + packets that contain sliced VBI data is specified by +&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable +length, depending on the actual number of lines of sliced VBI data +present in a video frame. The payload may be padded at the end with +unspecified fill bytes to align the end of the payload to a 4-byte +boundary. The payload shall never exceed 1552 bytes (2 fields with +18 lines/field with 43 bytes of data/line and a 4 byte magic number). + + + + struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname> + + + &cs-ustr; + + + __u8 + magic[4] + + A "magic" constant from that indicates +this is a valid sliced VBI data payload and also indicates which +member of the anonymous union, itv0 or +ITV0, to use for the payload data. + + + union + (anonymous) + + + + struct + v4l2_mpeg_vbi_itv0 + + itv0 + The primary form of the sliced VBI data payload +that contains anywhere from 1 to 35 lines of sliced VBI data. +Line masks are provided in this form of the payload indicating +which VBI lines are provided. + + + + struct + v4l2_mpeg_vbi_ITV0 + + ITV0 + An alternate form of the sliced VBI data payload +used when 36 lines of sliced VBI data are present. No line masks are +provided in this form of the payload; all valid line mask bits are +implcitly set. + + + +
+ + + Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv; + <structfield>magic</structfield> field + + &cs-def; + + + Defined Symbol + Value + Description + + + + + V4L2_MPEG_VBI_IVTV_MAGIC0 + + "itv0" + Indicates the itv0 +member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid. + + + V4L2_MPEG_VBI_IVTV_MAGIC1 + + "ITV0" + Indicates the ITV0 +member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and +that 36 lines of sliced VBI data are present. + + + +
+ + + struct <structname>v4l2_mpeg_vbi_itv0</structname> + + + &cs-str; + + + __le32 + linemask[2] + Bitmasks indicating the VBI service lines +present. These linemask values are stored +in little endian byte order in the MPEG stream. Some reference +linemask bit positions with their +corresponding VBI line number and video field are given below. +b0 indicates the least significant bit of a +linemask value: +linemask[0] b0: line 6 first field +linemask[0] b17: line 23 first field +linemask[0] b18: line 6 second field +linemask[0] b31: line 19 second field +linemask[1] b0: line 20 second field +linemask[1] b3: line 23 second field +linemask[1] b4-b31: unused and set to 0 + + + struct + v4l2_mpeg_vbi_itv0_line + + line[35] + This is a variable length array that holds from 1 +to 35 lines of sliced VBI data. The sliced VBI data lines present +correspond to the bits set in the linemask +array, starting from b0 of +linemask[0] up through b31 of +linemask[0], and from b0 + of linemask[1] up through b +3 of linemask[1]. +line[0] corresponds to the first bit +found set in the linemask array, +line[1] corresponds to the second bit +found set in the linemask array, etc. +If no linemask array bits are set, then +line[0] may contain one line of +unspecified data that should be ignored by applications. + + + +
+ + + struct <structname>v4l2_mpeg_vbi_ITV0</structname> + + + &cs-str; + + + struct + v4l2_mpeg_vbi_itv0_line + + line[36] + A fixed length array of 36 lines of sliced VBI +data. line[0] through line +[17] correspond to lines 6 through 23 of the +first field. line[18] through +line[35] corresponds to lines 6 +through 23 of the second field. + + + +
+ + + struct <structname>v4l2_mpeg_vbi_itv0_line</structname> + + + &cs-str; + + + __u8 + id + A line identifier value from + that indicates +the type of sliced VBI data stored on this line. + + + __u8 + data[42] + The sliced VBI data for the line. + + + +
+ + + Line Identifiers for struct <link + linkend="v4l2-mpeg-vbi-itv0-line"><structname> +v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id +</structfield> field + + &cs-def; + + + Defined Symbol + Value + Decription + + + + + V4L2_MPEG_VBI_IVTV_TELETEXT_B + + 1 + Refer to +Sliced VBI services for a description of the line payload. + + + V4L2_MPEG_VBI_IVTV_CAPTION_525 + + 4 + Refer to +Sliced VBI services for a description of the line payload. + + + V4L2_MPEG_VBI_IVTV_WSS_625 + + 5 + Refer to +Sliced VBI services for a description of the line payload. + + + V4L2_MPEG_VBI_IVTV_VPS + + 7 + Refer to +Sliced VBI services for a description of the line payload. + + + +
+ +
+
+ + + + + 0.26 + 2009-03-11 + aw + Added the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV +MPEG stream embedded, sliced VBI data format. + 0.25