Sliced VBI Format Negotiation

--- v4l2-spec/Makefile | 1 + v4l2-spec/dev-sliced-vbi.sgml | 315 +++++++++++++++++++++++++++++++++++++++++- v4l2-spec/v4l2.sgml | 17 ++- 3 files changed, 330 insertions(+), 3 deletions(-) (limited to 'v4l2-spec') diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile index d0dde12f4..41dba1cdd 100644 --- a/v4l2-spec/Makefile +++ b/v4l2-spec/Makefile @@ -274,6 +274,7 @@ STRUCTS = \ v4l2_input \ v4l2_jpegcompression \ v4l2_modulator \ + v4l2_mpeg_vbi_fmt_ivtv \ v4l2_output \ v4l2_outputparm \ v4l2_pix_format \ diff --git a/v4l2-spec/dev-sliced-vbi.sgml b/v4l2-spec/dev-sliced-vbi.sgml index 5560650a6..3c260e3e3 100644 --- a/v4l2-spec/dev-sliced-vbi.sgml +++ b/v4l2-spec/dev-sliced-vbi.sgml @@ -48,7 +48,7 @@ vital to program a sliced VBI device, therefore must be supported. -

Sliced VBI Format Negotiation To find out which data services are supported by the @@ -386,6 +386,319 @@ video and VBI data by using buffer timestamps.

+ 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 + Description + + + + + 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. + + + +

+ +

+ + 0x00000004 The hardware supports color decoding, but does not detect color modulation in the signal. + + + Sensor Orientation + + + V4L2_IN_ST_HFLIP + 0x00000010 + The input is connected to a device that produces a signal +that is flipped horizontally and does not correct this before passing the +signal to userspace. + + + V4L2_IN_ST_VFLIP + 0x00000020 + The input is connected to a device that produces a signal +that is flipped vertically and does not correct this before passing the +signal to userspace. Note that a 180 degree rotation is the same as HFLIP | VFLIP Analog Video -- cgit v1.2.3 From 14631b849c940b3898615f8861812f3522707815 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 2 May 2009 17:13:07 +0200 Subject: v4l2-spec: fix V4L2_TUNER_MODE_STEREO doc. From: Hans Verkuil Increased version number and fix V4L2_TUNER_MODE_STEREO documentation. Priority: normal Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- v4l2-spec/Makefile | 2 +- v4l2-spec/v4l2.sgml | 2 +- v4l2-spec/vidioc-g-tuner.sgml | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) (limited to 'v4l2-spec') diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile index e39136569..7a19924d4 100644 --- a/v4l2-spec/Makefile +++ b/v4l2-spec/Makefile @@ -1,5 +1,5 @@ # Also update in v4l2.sgml! -VERSION = 0.25 +VERSION = 0.26 SHELL=/bin/bash SGMLS = \ diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml index a6cbae2bf..470793d29 100644 --- a/v4l2-spec/v4l2.sgml +++ b/v4l2-spec/v4l2.sgml @@ -25,7 +25,7 @@ Video for Linux Two API Specification - Revision 0.25 + Revision 0.26 diff --git a/v4l2-spec/vidioc-g-tuner.sgml b/v4l2-spec/vidioc-g-tuner.sgml index 6285c18de..d5d379838 100644 --- a/v4l2-spec/vidioc-g-tuner.sgml +++ b/v4l2-spec/vidioc-g-tuner.sgml @@ -375,8 +375,8 @@ language. 1 Play stereo audio. When the tuner receives bilingual audio it may play different languages on the left and right -channel or the primary language on both channels. behave as in mono -mode.Playing different languages in this mode is +channel or the primary language is played on both channels.Playing +different languages in this mode is deprecated. New drivers should do this only in MODE_LANG1_LANG2.When the tuner receives no stereo signal or does not support stereo reception the -- cgit v1.2.3 From 02e8081a1e62b49fcf6ea760aef69a419bb183cf Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Jun 2009 10:48:52 +0200 Subject: v4l2-spec: update VIDIOC_G/S_MODULATOR section. From: Hans Verkuil Table 2 with the description of the modulator audio transmission flags contained a few typos that made it a bit confusing. Priority: normal Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- v4l2-spec/vidioc-g-modulator.sgml | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'v4l2-spec') diff --git a/v4l2-spec/vidioc-g-modulator.sgml b/v4l2-spec/vidioc-g-modulator.sgml index e5d4a3f24..a3ea5ef8a 100644 --- a/v4l2-spec/vidioc-g-modulator.sgml +++ b/v4l2-spec/vidioc-g-modulator.sgml @@ -166,7 +166,7 @@ combine with V4L2_TUNER_SUB_STEREO or channel of a stereo audio signal. When the input has only one channel or two channels and V4L2_TUNER_SUB_SAP is also set, channel 1 is encoded as left and right channel. This flag does -not combine with V4L2_TUNER_SUB_MONO or +not combine with V4L2_TUNER_SUB_MONO or V4L2_TUNER_SUB_LANG1. When the driver does not support stereo audio it shall fall back to mono. @@ -177,8 +177,9 @@ support stereo audio it shall fall back to mono. language of a bilingual audio signal. When the input has only one channel it is used for both languages. It is not possible to encode the primary or secondary language only. This flag does not combine -with V4L2_TUNER_SUB_MONO or -V4L2_TUNER_SUB_STEREO. If the hardware does not +with V4L2_TUNER_SUB_MONO, +V4L2_TUNER_SUB_STEREO or +V4L2_TUNER_SUB_SAP. If the hardware does not support the respective audio matrix, or the current video standard does not permit bilingual audio the VIDIOC_S_MODULATOR ioctl shall return an &EINVAL; @@ -188,7 +189,7 @@ and the driver shall fall back to mono or stereo mode. V4L2_TUNER_SUB_LANG2 0x0004 Same effect as -V4L2_TUNER_SUB_LANG1. +V4L2_TUNER_SUB_SAP. V4L2_TUNER_SUB_SAP @@ -198,7 +199,7 @@ and the driver shall fall back to mono or stereo mode. channel as Second Audio Program. When the input has only one channel it is used for both audio tracks. When the input has three channels the mono track is a down-mix of channel 1 and 2. When combined with -V4L2_TUNER_SUB_STEREO channel 1 and 2 are +V4L2_TUNER_SUB_STEREO channel 1 and 2 are encoded as left and right stereo audio, channel 3 as Second Audio Program. When the input has only two channels, the first is encoded as left and right channel and the second as SAP. When the input has only @@ -207,7 +208,7 @@ encode a Second Audio Program only. This flag must combine with V4L2_TUNER_SUB_MONO or V4L2_TUNER_SUB_STEREO. If the hardware does not support the respective audio matrix, or the current video standard -does not permit SAP the VIDIOC_S_MODULATOR ioctl +does not permit SAP the VIDIOC_S_MODULATOR ioctl shall return an &EINVAL; and driver shall fall back to mono or stereo mode. -- cgit v1.2.3 From ce2c39f9dbd553bbec3d1cc6aa926c4e95a2c844 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 20 Jun 2009 10:54:10 +0200 Subject: v4l2-spec: add missing documentation for the OV518 pixel format. From: Hans Verkuil Priority: normal Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- v4l2-spec/pixfmt.sgml | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'v4l2-spec') diff --git a/v4l2-spec/pixfmt.sgml b/v4l2-spec/pixfmt.sgml index 3f39b408e..36a6934c7 100644 --- a/v4l2-spec/pixfmt.sgml +++ b/v4l2-spec/pixfmt.sgml @@ -724,6 +724,11 @@ kernel sources in the file Documentation/video4linux/cx2341x/README.hm 'M310' Compressed BGGR Bayer format used by the gspca driver. + + V4L2_PIX_FMT_OV518 + '0518' + OV518 JPEG format used by the gspca driver. + V4L2_PIX_FMT_PJPG 'PJPG' -- cgit v1.2.3 From d82f58cadb63e341c4fba03c3ce32b61af69108d Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Tue, 23 Jun 2009 08:39:54 +0200 Subject: v4l2-spec: add missing V4L2_PIX_FMT_OV511 documentation. From: Hans Verkuil Priority: normal Signed-off-by: Hans Verkuil --- v4l2-spec/pixfmt.sgml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'v4l2-spec') diff --git a/v4l2-spec/pixfmt.sgml b/v4l2-spec/pixfmt.sgml index 36a6934c7..499cdacda 100644 --- a/v4l2-spec/pixfmt.sgml +++ b/v4l2-spec/pixfmt.sgml @@ -724,9 +724,14 @@ kernel sources in the file Documentation/video4linux/cx2341x/README.hm 'M310' Compressed BGGR Bayer format used by the gspca driver. + + V4L2_PIX_FMT_OV511 + 'O511' + OV511 JPEG format used by the gspca driver. + V4L2_PIX_FMT_OV518 - '0518' + 'O518' OV518 JPEG format used by the gspca driver. -- cgit v1.2.3 From b0b50913254709734afb1bcc907788c1beb15e62 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 30 Jun 2009 16:34:49 -0300 Subject: v4l2-spec: Add doc for bayer V4L2_PIX_FMT_SGRBG8 From: Mauro Carvalho Chehab Fixes a build error at documentation: jade:/home/v4l/master/v4l2-spec/videodev2.h.sgml:329:23:X: reference to non-existent ID "V4L2-PIX-FMT-SGRBG8" Priority: normal Signed-off-by: Mauro Carvalho Chehab --- v4l2-spec/Makefile | 1 + v4l2-spec/pixfmt-sgrbg8.sgml | 75 ++++++++++++++++++++++++++++++++++++++++++++ v4l2-spec/pixfmt.sgml | 1 + 3 files changed, 77 insertions(+) create mode 100644 v4l2-spec/pixfmt-sgrbg8.sgml (limited to 'v4l2-spec') diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile index 7a19924d4..8f40e8614 100644 --- a/v4l2-spec/Makefile +++ b/v4l2-spec/Makefile @@ -41,6 +41,7 @@ SGMLS = \ pixfmt-sbggr16.sgml \ pixfmt-sbggr8.sgml \ pixfmt-sgbrg8.sgml \ + pixfmt-sgrbg8.sgml \ pixfmt-uyvy.sgml \ pixfmt-vyuy.sgml \ pixfmt-y16.sgml \ diff --git a/v4l2-spec/pixfmt-sgrbg8.sgml b/v4l2-spec/pixfmt-sgrbg8.sgml new file mode 100644 index 000000000..553c5264a --- /dev/null +++ b/v4l2-spec/pixfmt-sgrbg8.sgml @@ -0,0 +1,75 @@ + + + V4L2_PIX_FMT_SGRBG8 ('GRBG') + &manvol; + + + V4L2_PIX_FMT_SGRBG8 + Bayer RGB format + + + Description + + This is commonly the native format of digital cameras, +reflecting the arrangement of sensors on the CCD device. Only one red, +green or blue value is given for each pixel. Missing components must +be interpolated from neighbouring pixels. From left to right the first +row consists of a green and blue value, the second row of a red and +green value. This scheme repeats to the right and down for every two +columns and rows. + + + <constant>V4L2_PIX_FMT_SGRBG8</constant> 4 × +4 pixel image + + + Byte Order. + Each cell is one byte. + + + + + + start + 0: + G00 + R01 + G02 + R03 + + + start + 4: + R10 + B11 + R12 + B13 + + + start + 8: + G20 + R21 + G22 + R23 + + + start + 12: + R30 + B31 + R32 + B33 + + + + + + + + + + + diff --git a/v4l2-spec/pixfmt.sgml b/v4l2-spec/pixfmt.sgml index 499cdacda..1be70eea0 100644 --- a/v4l2-spec/pixfmt.sgml +++ b/v4l2-spec/pixfmt.sgml @@ -565,6 +565,7 @@ access the palette, this must be done with ioctls of the Linux framebuffer API.< &sub-packed-rgb; &sub-sbggr8; &sub-sgbrg8; + &sub-sgrbg8 &sub-sbggr16;

-- cgit v1.2.3 From 84e800a7ca6664a01b8b294b4acd673019c0a2a9 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 20 Jun 2009 10:49:43 +0200 Subject: v4l2-spec: finalize the RDS specification. From: Hans Verkuil Priority: normal Signed-off-by: Hans Verkuil --- v4l2-spec/biblio.sgml | 65 ++++----------- v4l2-spec/compat.sgml | 14 +++- v4l2-spec/dev-rds.sgml | 174 ++++++++++++++++++++++++++++++++++------- v4l2-spec/v4l2.sgml | 7 ++ v4l2-spec/vidioc-g-tuner.sgml | 17 +++- v4l2-spec/vidioc-querycap.sgml | 2 +- 6 files changed, 195 insertions(+), 84 deletions(-) (limited to 'v4l2-spec') diff --git a/v4l2-spec/biblio.sgml b/v4l2-spec/biblio.sgml index b013ece1d..afc8a0dd2 100644 --- a/v4l2-spec/biblio.sgml +++ b/v4l2-spec/biblio.sgml @@ -158,54 +158,23 @@ Signal - NTSC for Studio Applications" 1125-Line High-Definition Production" - - V4L - - - Alan - Cox - - Red Hat, Inc. -

- alan@redhat.com -

- - - - Video4Linux API Specification - - This file is part of the Linux kernel sources under -Documentation/video4linux. - - - - - V4LPROG - - - Alan - Cox - - Red Hat, Inc. -

- alan@redhat.com -

- - - - Video4Linux Programming (a.k.a. The Video4Linux -Book) - - About V4L driver programming. This -book is part of the Linux kernel DocBook documentation, for example at - -http://kernelnewbies.org/documents/. SGML sources are included -in the kernel sources. - - - 2000 - Alan Cox - + + EN 50067 + + European Committee for Electrotechnical Standardization +(http://www.cenelec.eu) + + Specification of the radio data system (RDS) for VHF/FM sound broadcasting +in the frequency range from 87,5 to 108,0 MHz + + + + NRSC-4 + + National Radio Systems Committee +(http://www.nrscstandards.org) + + NTSC-4: United States RBDS Standard diff --git a/v4l2-spec/compat.sgml b/v4l2-spec/compat.sgml index 94713023d..c1c725f35 100644 --- a/v4l2-spec/compat.sgml +++ b/v4l2-spec/compat.sgml @@ -1273,9 +1273,8 @@ also the size of the structure changed, which is encoded in the ioctl request code, thus older V4L2 devices will respond with an &EINVAL; to the new &VIDIOC-QUERYCAP; ioctl. - There are new fields to identify the driver, a new (as -of yet unspecified) device function -V4L2_CAP_RDS_CAPTURE, the + There are new fields to identify the driver, a new RDS +device function V4L2_CAP_RDS_CAPTURE, the V4L2_CAP_AUDIO flag indicates if the device has any audio connectors, another I/O capability V4L2_CAP_ASYNCIO can be flagged. In response to @@ -2294,6 +2293,15 @@ was renamed to v4l2_chip_ident_old +

+ V4L2 in Linux 2.6.32 + + + Finalized the RDS capture API. See for +more information. + + +

diff --git a/v4l2-spec/dev-rds.sgml b/v4l2-spec/dev-rds.sgml index 07bfd4c65..8f357d9f0 100644 --- a/v4l2-spec/dev-rds.sgml +++ b/v4l2-spec/dev-rds.sgml @@ -2,38 +2,154 @@ The Radio Data System transmits supplementary information in binary format, for example the station name or travel -information, on a inaudible audio subcarrier of a radio program. This -interface aims at devices capable of receiving and decoding RDS +information, on an inaudible audio subcarrier of a radio program. This +interface is aimed at devices capable of receiving and decoding RDS information. - The V4L API defines its RDS API as follows. - - From radio devices supporting it, RDS data can be read -with the &func-read; function. The data is packed in groups of three, -as follows: - - First Octet Least Significant Byte of RDS Block - - - Second Octet Most Significant Byte of RDS Block - - - Third Octet Bit 7: Error bit. Indicates that an -uncorrectable error occurred during reception of this block. Bit 6: -Corrected bit. Indicates that an error was corrected for this data -block. Bits 5-3: Received Offset. Indicates the offset received by the -sync system. Bits 2-0: Offset Name. Indicates the offset applied to -this data. - - - - It was argued the RDS API should be -extended before integration into V4L2, no new API has been devised yet. -Please write to the linux-media mailing list for discussion: &v4l-ml;. -Meanwhile no V4L2 driver should set the -V4L2_CAP_RDS_CAPTURE capability flag. + For more information see the core RDS standard +and the RBDS standard . + Note that the RBDS standard as is used in the USA is almost identical +to the RDS standard. Any RDS decoder can also handle RBDS. Only some of the fields +have slightly different meanings. See the RBDS standard for more information. + + The RBDS standard also specifies support for MMBS (Modified Mobile Search). +This is a proprietary format which seems to be discontinued. The RDS interface does not +support this format. Should support for MMBS (or the so-called 'E blocks' in general) +be needed, then please contact the linux-media mailing list: &v4l-ml;. + +

+ Querying Capabilities + + Devices supporting the RDS capturing API +set the V4L2_CAP_RDS_CAPTURE flag in +the capabilities field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. + + Any tuner that supports RDS will set the +V4L2_TUNER_CAP_RDS flag in the capability +field of &v4l2-tuner;. + + Whether an RDS signal is present can be detected by looking at +the rxsubchans field of &v4l2-tuner;: the +V4L2_TUNER_SUB_RDS will be set if RDS data was detected. + +

+ +

+ Reading RDS data + + RDS data can be read from the radio device +with the &func-read; function. The data is packed in groups of three bytes, +as follows: + + struct +<structname>v4l2_rds_data</structname> + + + + + + + __u8 + lsb + Least Significant Byte of RDS Block + + + __u8 + msb + Most Significant Byte of RDS Block + + + __u8 + block + Block description + + + +

+ + Block description + + + + + + Bits 0-2 + Block (aka offset) of the received data. + + + Bits 3-5 + Deprecated. Currently identical to bits 0-2. Do not use these bits. + + + Bit 6 + Corrected bit. Indicates that an error was corrected for this data block. + + + Bit 7 + Error bit. Indicates that an uncorrectable error occurred during reception of this block. + + + +

+ + + Block defines + + + + + + + V4L2_RDS_BLOCK_MSK + 7 + Mask for bits 0-2 to get the block ID. + + + V4L2_RDS_BLOCK_A + 0 + Block A. + + + V4L2_RDS_BLOCK_B + 1 + Block B. + + + V4L2_RDS_BLOCK_C + 2 + Block C. + + + V4L2_RDS_BLOCK_D + 3 + Block D. + + + V4L2_RDS_BLOCK_C_ALT + 4 + Block C'. + + + V4L2_RDS_BLOCK_INVALID + 7 + An invalid block. + + + V4L2_RDS_BLOCK_CORRECTED + 0x40 + A bit error was detected but corrected. + + + V4L2_RDS_BLOCK_ERROR + 0x80 + An incorrectable error occurred. + + + +

+ + 0.26 + 2009-06-15 + hv + Finalized the RDS capture API. + + 0.25 2009-01-18 diff --git a/v4l2-spec/vidioc-g-tuner.sgml b/v4l2-spec/vidioc-g-tuner.sgml index d5d379838..eb0b89e9a 100644 --- a/v4l2-spec/vidioc-g-tuner.sgml +++ b/v4l2-spec/vidioc-g-tuner.sgml @@ -120,9 +120,9 @@ field is not quite clear.--> to decode audio subprograms. They will not change, for example with the current video standard.When the structure refers to a radio tuner only the -V4L2_TUNER_CAP_LOW and -V4L2_TUNER_CAP_STEREO flags can be -set. +V4L2_TUNER_CAP_LOW, +V4L2_TUNER_CAP_STEREO and +V4L2_TUNER_CAP_RDS flags can be set. __u32 @@ -312,6 +312,12 @@ carrier for a monaural secondary language. Only supports the V4L2_STD_NTSC_M video standard. + + V4L2_TUNER_CAP_RDS + 0x0080 + RDS capture is supported. This capability is only valid for +radio tuners. + @@ -353,6 +359,11 @@ bilingual audio signal (or a second audio program). V4L2_TUNER_SUB_SAP flag applies when the current video standard is V4L2_STD_NTSC_M. + + V4L2_TUNER_SUB_RDS + 0x0010 + The tuner receives an RDS channel. + diff --git a/v4l2-spec/vidioc-querycap.sgml b/v4l2-spec/vidioc-querycap.sgml index 2715289d8..4a741f5e9 100644 --- a/v4l2-spec/vidioc-querycap.sgml +++ b/v4l2-spec/vidioc-querycap.sgml @@ -184,7 +184,7 @@ data. V4L2_CAP_RDS_CAPTURE 0x00000100 - [to be defined] + The device supports the RDS interface. V4L2_CAP_VIDEO_OUTPUT_OVERLAY -- cgit v1.2.3 From bcadb4347f42dfeb5b2f3eddc7af77c069b302ba Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 20 Jul 2009 13:56:20 +0200 Subject: v4l2-spec: add documentation for missing V4L2_PIX_FMT_SN9C20X_I420 pixfmt. From: Hans Verkuil Priority: normal Signed-off-by: Hans Verkuil --- v4l2-spec/pixfmt.sgml | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'v4l2-spec') diff --git a/v4l2-spec/pixfmt.sgml b/v4l2-spec/pixfmt.sgml index 1be70eea0..9e6bebeb4 100644 --- a/v4l2-spec/pixfmt.sgml +++ b/v4l2-spec/pixfmt.sgml @@ -765,6 +765,11 @@ kernel sources in the file Documentation/video4linux/cx2341x/README.hm 'S910' Compressed format of the SN9C102 driver. + + V4L2_PIX_FMT_SN9C20X_I420 + 'S920' + YUV 4:2:0 format of the gspca sn9c20x driver. + V4L2_PIX_FMT_WNVA 'WNVA' -- cgit v1.2.3 From db54df2055130294d02d4b75e3e9b0a391bb7806 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 20 Jul 2009 14:17:55 +0200 Subject: v4l2-spec: update for new modulator and rds encoder caps. From: Hans Verkuil Document the radio modulator and RDS encoder API. Priority: normal Signed-off-by: Hans Verkuil --- v4l2-spec/common.sgml | 2 +- v4l2-spec/compat.sgml | 3 +++ v4l2-spec/dev-radio.sgml | 14 ++++++++------ v4l2-spec/dev-rds.sgml | 20 ++++++++++++++------ v4l2-spec/v4l2.sgml | 3 ++- v4l2-spec/vidioc-g-modulator.sgml | 5 +++++ v4l2-spec/vidioc-querycap.sgml | 14 +++++++++++--- 7 files changed, 44 insertions(+), 17 deletions(-) (limited to 'v4l2-spec') diff --git a/v4l2-spec/common.sgml b/v4l2-spec/common.sgml index ff595960b..75c7141e3 100644 --- a/v4l2-spec/common.sgml +++ b/v4l2-spec/common.sgml @@ -491,7 +491,7 @@ the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that VIDIOC_S_MODULATOR does not switch the current modulator, when there is more than one at all. The modulator is solely determined by the current video output. Drivers must support both -ioctls and set the V4L2_CAP_TUNER (sic) flag in +ioctls and set the V4L2_CAP_MODULATOR flag in the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or more modulators.

diff --git a/v4l2-spec/compat.sgml b/v4l2-spec/compat.sgml index c1c725f35..bcc372c18 100644 --- a/v4l2-spec/compat.sgml +++ b/v4l2-spec/compat.sgml @@ -2300,6 +2300,9 @@ was renamed to v4l2_chip_ident_oldFinalized the RDS capture API. See for more information. + + Added new capabilities for modulators and RDS encoders. + diff --git a/v4l2-spec/dev-radio.sgml b/v4l2-spec/dev-radio.sgml index ae8367219..4d521d2a8 100644 --- a/v4l2-spec/dev-radio.sgml +++ b/v4l2-spec/dev-radio.sgml @@ -1,7 +1,7 @@ Radio Interface This interface is intended for AM and FM (analog) radio -receivers. +receivers and transmitters. Conventionally V4L2 radio devices are accessed through character device special files named /dev/radio @@ -14,7 +14,8 @@ numbers 64 to 127. Devices supporting the radio interface set the V4L2_CAP_RADIO and -V4L2_CAP_TUNER flag in the +V4L2_CAP_TUNER or +V4L2_CAP_MODULATOR flag in the capabilities field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of capability flags are reserved for future extensions. @@ -25,7 +26,7 @@ capability flags are reserved for future extensions. Radio devices can support controls, and must support the tuner ioctls. +linkend="tuner">tuner or modulator ioctls. They do not support the video input or output, audio input or output, video standard, cropping and scaling, compression and @@ -38,11 +39,12 @@ methods are reserved for future extensions. Radio devices may have a couple audio controls (as discussed in ) such as a volume control, possibly custom -controls. Further all radio devices have one tuner (these are +controls. Further all radio devices have one tuner or modulator (these are discussed in ) with index number zero to select the radio frequency and to determine if a monaural or FM stereo -program is received. Drivers switch automatically between AM and FM -depending on the selected frequency. The &VIDIOC-G-TUNER; ioctl +program is received/emitted. Drivers switch automatically between AM and FM +depending on the selected frequency. The &VIDIOC-G-TUNER; or +&VIDIOC-G-MODULATOR; ioctl reports the supported frequency range. diff --git a/v4l2-spec/dev-rds.sgml b/v4l2-spec/dev-rds.sgml index 8f357d9f0..9d59d0cb0 100644 --- a/v4l2-spec/dev-rds.sgml +++ b/v4l2-spec/dev-rds.sgml @@ -24,16 +24,24 @@ be needed, then please contact the linux-media mailing list: &v4l-ml;. Devices supporting the RDS capturing API set the V4L2_CAP_RDS_CAPTURE flag in the capabilities field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl. - - Any tuner that supports RDS will set the +returned by the &VIDIOC-QUERYCAP; ioctl. +Any tuner that supports RDS will set the V4L2_TUNER_CAP_RDS flag in the capability -field of &v4l2-tuner;. - - Whether an RDS signal is present can be detected by looking at +field of &v4l2-tuner;. +Whether an RDS signal is present can be detected by looking at the rxsubchans field of &v4l2-tuner;: the V4L2_TUNER_SUB_RDS will be set if RDS data was detected. + Devices supporting the RDS output API +set the V4L2_CAP_RDS_OUTPUT flag in +the capabilities field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. +Any modulator that supports RDS will set the +V4L2_TUNER_CAP_RDS flag in the capability +field of &v4l2-modulator;. +In order to enable the RDS transmission one must set the V4L2_TUNER_SUB_RDS +bit in the txsubchans field of &v4l2-modulator;. +

diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml index 815e96ab5..bae7eb441 100644 --- a/v4l2-spec/v4l2.sgml +++ b/v4l2-spec/v4l2.sgml @@ -134,7 +134,8 @@ applications. --> 0.26 2009-06-15 hv - Finalized the RDS capture API. + Finalized the RDS capture API. Added modulator and RDS encoder +capabilities. diff --git a/v4l2-spec/vidioc-g-modulator.sgml b/v4l2-spec/vidioc-g-modulator.sgml index a3ea5ef8a..945147f90 100644 --- a/v4l2-spec/vidioc-g-modulator.sgml +++ b/v4l2-spec/vidioc-g-modulator.sgml @@ -212,6 +212,11 @@ does not permit SAP the VIDIOC_S_MODULATOR ioctl shall return an &EINVAL; and driver shall fall back to mono or stereo mode. + + V4L2_TUNER_SUB_RDS + 0x0010 + Enable the RDS encoder for a radio FM transmitter. + diff --git a/v4l2-spec/vidioc-querycap.sgml b/v4l2-spec/vidioc-querycap.sgml index 4a741f5e9..fa12ae738 100644 --- a/v4l2-spec/vidioc-querycap.sgml +++ b/v4l2-spec/vidioc-querycap.sgml @@ -208,9 +208,9 @@ hardware frequency seeking. V4L2_CAP_TUNER 0x00010000 - The device has some sort of tuner or modulator to -receive or emit RF-modulated video signals. For more information about -tuner and modulator programming see + The device has some sort of tuner to +receive RF-modulated video signals. For more information about +tuner programming see . @@ -227,6 +227,14 @@ interface. For more information on audio inputs and outputs see 0x00040000 This is a radio receiver. + + V4L2_CAP_MODULATOR + 0x00080000 + The device has some sort of modulator to +emit RF-modulated video/audio signals. For more information about +modulator programming see +. + V4L2_CAP_READWRITE 0x01000000 -- cgit v1.2.3 From 663970b7c101bbe35646a5003e25e40087bea009 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 16 Aug 2009 21:09:23 -0300 Subject: Document libv4l at V4L2 API specs From: Mauro Carvalho Chehab Since applications aren't prepared to handle all V4L2 available formats, an effort is done to have a library capable of understanding especially the proprietary formats. This patch documents this library, and adds v4l2grab.c as an example on how to use it. Parts of the text are based at the libv4l README file (c) by Hans de Goede. Thanks to Hans de Goede for his good work with libv4l. Priority: normal Signed-off-by: Mauro Carvalho Chehab --- v4l2-spec/Makefile | 16 +++++ v4l2-spec/libv4l.sgml | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++ v4l2-spec/v4l2.sgml | 38 +++++++++++- 3 files changed, 219 insertions(+), 3 deletions(-) create mode 100644 v4l2-spec/libv4l.sgml (limited to 'v4l2-spec') diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile index 8f40e8614..616445137 100644 --- a/v4l2-spec/Makefile +++ b/v4l2-spec/Makefile @@ -5,6 +5,7 @@ SHELL=/bin/bash SGMLS = \ biblio.sgml \ capture.c.sgml \ + v4l2grab.c.sgml \ common.sgml \ compat.sgml \ controls.sgml \ @@ -20,6 +21,7 @@ SGMLS = \ dev-sliced-vbi.sgml \ dev-teletext.sgml \ driver.sgml \ + libv4l.sgml \ entities.sgml \ fdl-appendix.sgml \ func-close.sgml \ @@ -323,6 +325,12 @@ DOCUMENTED = \ -e "s/$V4L2_PIX_FMT_[A-Z0-9_]\+$ /\1<\/link> /g" \ -e ":a;s/$linkend=\".*$_$.*\">$/\1-\2/;ta" +libv4l-fmt.sgml: + cat ../v4l2-apps/libv4l/libv4lconvert/*.c| \ + perl -ne 'if (m/(V4L2_PIX_FMT_[^\s\;\\)\,:]+)/) { printf "$$1,\n"; };' \ + |sort|uniq| \ + sed -e ":a;s/$linkend=\".*$_$.*\">$/\1-\2/;ta" > $@ + capture.c.sgml: ../v4l2-apps/test/capture-example.c Makefile echo "" > $@ expand --tabs=8 < $< | \ @@ -330,6 +338,13 @@ capture.c.sgml: ../v4l2-apps/test/capture-example.c Makefile sed 's/i\.e\./&ie;/' >> $@ echo "" >> $@ +v4l2grab.c.sgml: ../v4l2-apps/test/v4l2grab.c Makefile + echo "" > $@ + expand --tabs=8 < $< | \ + sed $(ESCAPE) $(DOCUMENTED) | \ + sed 's/i\.e\./&ie;/' >> $@ + echo "" >> $@ + videodev2.h.sgml: ../linux/include/linux/videodev2.h Makefile echo "" > $@ expand --tabs=8 < $< | \ @@ -488,6 +503,7 @@ distclean clean: rm -f *.stamp rm -f videodev2.h.sgml rm -f capture.c.sgml + rm -f v4l2grab.c.sgml rm -f capture rm -f indices.sgml entities.sgml rm -rf v4l2 v4l2-single v4l2.pdf diff --git a/v4l2-spec/libv4l.sgml b/v4l2-spec/libv4l.sgml new file mode 100644 index 000000000..ec1f8b6fe --- /dev/null +++ b/v4l2-spec/libv4l.sgml @@ -0,0 +1,168 @@ +Libv4l Userspace Library +

+ Introduction + + libv4l is a collection of libraries which adds a thin abstraction +layer on top of video4linux2 devices. The purpose of this (thin) layer +is to make it easy for application writers to support a wide variety of +devices without having to write separate code for different devices in the +same class. +An example of using libv4l is provided by +v4l2grab. + + + libv4l consists of 3 different libraries: +

+ libv4lconvert + + libv4lconvert is a library that converts several +different pixelformats found in V4L2 drivers into a few common RGB and +YUY formats. + It currently accepts the following V4L2 driver formats: +V4L2_PIX_FMT_BGR24, +V4L2_PIX_FMT_HM12, +V4L2_PIX_FMT_JPEG, +V4L2_PIX_FMT_MJPEG, +V4L2_PIX_FMT_MR97310A, +V4L2_PIX_FMT_OV511, +V4L2_PIX_FMT_OV518, +V4L2_PIX_FMT_PAC207, +V4L2_PIX_FMT_PJPG, +V4L2_PIX_FMT_RGB24, +V4L2_PIX_FMT_SBGGR8, +V4L2_PIX_FMT_SGBRG8, +V4L2_PIX_FMT_SGRBG8, +V4L2_PIX_FMT_SN9C10X, +V4L2_PIX_FMT_SN9C20X_I420, +V4L2_PIX_FMT_SPCA501, +V4L2_PIX_FMT_SPCA505, +V4L2_PIX_FMT_SPCA508, +V4L2_PIX_FMT_SPCA561, +V4L2_PIX_FMT_SQ905C, +V4L2_PIX_FMT_SRGGB8, +V4L2_PIX_FMT_UYVY, +V4L2_PIX_FMT_YUV420, +V4L2_PIX_FMT_YUYV, +V4L2_PIX_FMT_YVU420, +and V4L2_PIX_FMT_YVYU. + + Later on libv4lconvert was expanded to also be able to do +various video processing functions to improve webcam video quality. +The video processing is split in to 2 parts: libv4lconvert/control and +libv4lconvert/processing. + + The control part is used to offer video controls which can +be used to control the video processing functions made available by + libv4lconvert/processing. These controls are stored application wide +(until reboot) by using a persistent shared memory object. + + libv4lconvert/processing offers the actual video +processing functionality. +

+ libv4l1 + This library offers functions that can be used to quickly +make v4l1 applications work with v4l2 devices. These functions work exactly +like the normal open/close/etc, except that libv4l1 does full emulation of +the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it +will just pass calls through. + Since those functions are emulations of the old V4L1 API, +it shouldn't be used for new applications. +

+ libv4l2 + This library should be used for all modern V4L2 +applications. + It provides handles to call V4L2 open/ioctl/close/poll +methods. Instead of just providing the raw output of the device, it enhances +the calls in the sense that it will use libv4lconvert to provide more video +formats and to enhance the image quality. + In most cases, libv4l2 just passes the calls directly +through to the v4l2 driver, intercepting the calls to +VIDIOC_TRY_FMT, +VIDIOC_G_FMT +VIDIOC_S_FMT +VIDIOC_ENUM_FRAMESIZES +and +VIDIOC_ENUM_FRAMEINTERVALS +in order to emulate the formats +V4L2_PIX_FMT_BGR24, +V4L2_PIX_FMT_RGB24, +V4L2_PIX_FMT_YUV420, +and V4L2_PIX_FMT_YVU420, +if they aren't available in the driver. +VIDIOC_ENUM_FMT +keeps enumerating the hardware supported formats, plus the emulated formats +offered by libv4l at the end. + +

+ Libv4l device control functions + The common file operation methods are provided by +libv4l. + Those functions operate just like glibc +open/close/dup/ioctl/read/mmap/munmap: + + int v4l2_open(const char *file, int oflag, +...) - +operates like the standard open() function. + + int v4l2_close(int fd) - +operates like the standard close() function. + + int v4l2_dup(int fd) - +operates like the standard dup() function, duplicating a file handler. + + int v4l2_ioctl (int fd, unsigned long int request, ...) - +operates like the standard ioctl() function. + + int v4l2_read (int fd, void* buffer, size_t n) - +operates like the standard read() function. + + void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - +operates like the standard mmap() function. + + int v4l2_munmap(void *_start, size_t length); - +operates like the standard munmap() function. + + + Those functions provide additional control: + + int v4l2_fd_open(int fd, int v4l2_flags) - +opens an already opened fd for further use through v4l2lib and possibly +modify libv4l2's default behavior through the v4l2_flags argument. +Currently, v4l2_flags can be V4L2_DISABLE_CONVERSION, +to disable format conversion. + + int v4l2_set_control(int fd, int cid, int value) - +This function takes a value of 0 - 65535, and then scales that range to +the actual range of the given v4l control id, and then if the cid exists +and is not locked sets the cid to the scaled value. + + int v4l2_get_control(int fd, int cid) - +This function returns a value of 0 - 65535, scaled to from the actual range +of the given v4l control id. when the cid does not exist, could not be +accessed for some reason, or some error occured 0 is returned. + + +

+ + v4l1compat.so wrapper library + + This library intercepts calls to +open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l +counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also +emulates V4L1 calls via V4L2 API. + It allows usage of binary legacy applications that +still don't use libv4l. +

+ +

+ diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml index bae7eb441..8e7610685 100644 --- a/v4l2-spec/v4l2.sgml +++ b/v4l2-spec/v4l2.sgml @@ -25,7 +25,7 @@ Video for Linux Two API Specification - Revision 0.26 + Revision 0.27 @@ -92,6 +92,18 @@ MPEG stream embedded, sliced VBI data format in this specification. + + Mauro + Carvalho Chehab + Documented libv4l, designed and added v4l2grab example + + +

+ mchehab@redhat.com +

+ + + 1999 2000 @@ -105,12 +117,13 @@ MPEG stream embedded, sliced VBI data format in this specification. 2008 2009 Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin -Rubli, Andy Walls +Rubli, Andy Walls, Mauro Carvalho Chehab This document is copyrighted © 1999-2009 by Bill -Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, and Andy Walls. +Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls and +Mauro Carvalho Chehab. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -130,6 +143,13 @@ structs, ioctls) must be noted in more detail in the history chapter (compat.sgml), along with the possible impact on existing drivers and applications. --> + + 0.27 + 2009-08-15 + mcc + Added libv4l documentation and v4l2grab example. + + 0.26 2009-06-15 @@ -471,6 +491,10 @@ available here: + &sub-libv4l; + + &sub-compat; @@ -485,6 +509,14 @@ available here: + Video Grabber example using libv4l + This program demonstrates how to grab V4L2 images in ppm format by +using libv4l handlers. The advantage is that this grabber can potentially work +with any V4L2 driver. + &sub-v4l2grab-c; + + &sub-fdl-appendix; &sub-indices; -- cgit v1.2.3 From 39260c5d799177f03ba4a0cea40f998ebff7d8c9 Mon Sep 17 00:00:00 2001 From: Guennadi Liakhovetski Date: Wed, 26 Aug 2009 20:39:27 +0200 Subject: Document the new V4L2_CID_BAND_STOP_FILTER control From: Guennadi Liakhovetski Add V4L2 API documentation for the new V4L2_CID_BAND_STOP_FILTER control Signed-off-by: Guennadi Liakhovetski --- v4l2-spec/controls.sgml | 8 ++++++++ v4l2-spec/v4l2.sgml | 9 ++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) (limited to 'v4l2-spec') diff --git a/v4l2-spec/controls.sgml b/v4l2-spec/controls.sgml index 477a97077..a806eddcd 100644 --- a/v4l2-spec/controls.sgml +++ b/v4l2-spec/controls.sgml @@ -1811,6 +1811,14 @@ mechanical obturation of the sensor and firmware image processing, but the device is not restricted to these methods. Devices that implement the privacy control must support read access and may support write access. + + + V4L2_CID_BAND_STOP_FILTER + integer + Switch the band-stop filter of a +camera sensor on or off, or specify its strength. Such band-stop filters can +be used, for example, to filter out the fluorescent light component. + diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml index 8e7610685..a433a1fc2 100644 --- a/v4l2-spec/v4l2.sgml +++ b/v4l2-spec/v4l2.sgml @@ -25,7 +25,7 @@ Video for Linux Two API Specification - Revision 0.27 + Revision 0.28 @@ -143,6 +143,13 @@ structs, ioctls) must be noted in more detail in the history chapter (compat.sgml), along with the possible impact on existing drivers and applications. --> + + 0.28 + 2009-08-26 + gl + Added V4L2_CID_BAND_STOP_FILTER documentation. + + 0.27 2009-08-15 -- cgit v1.2.3 From 31901a2ad985c7839b68b5b43788d5d62ea32f58 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 2 Aug 2009 11:58:43 +0200 Subject: v4l2-spec: document the new string control type. From: Hans Verkuil Priority: normal Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- v4l2-spec/Makefile | 1 + v4l2-spec/compat.sgml | 3 ++ v4l2-spec/controls.sgml | 3 +- v4l2-spec/v4l2.sgml | 4 +-- v4l2-spec/vidioc-g-ext-ctrls.sgml | 72 ++++++++++++++++++++++++++++++++------- v4l2-spec/vidioc-queryctrl.sgml | 42 +++++++++++++++++------ 6 files changed, 98 insertions(+), 27 deletions(-) (limited to 'v4l2-spec') diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile index 616445137..3b4c321c4 100644 --- a/v4l2-spec/Makefile +++ b/v4l2-spec/Makefile @@ -307,6 +307,7 @@ ERRORS = \ EINVAL \ ENFILE \ ENOMEM \ + ENOSPC \ ENOTTY \ ENXIO \ EMFILE \ diff --git a/v4l2-spec/compat.sgml b/v4l2-spec/compat.sgml index bcc372c18..c18ddf3db 100644 --- a/v4l2-spec/compat.sgml +++ b/v4l2-spec/compat.sgml @@ -2303,6 +2303,9 @@ more information. Added new capabilities for modulators and RDS encoders. + + Added support for string controls. +

diff --git a/v4l2-spec/controls.sgml b/v4l2-spec/controls.sgml index a806eddcd..dbe4f6f86 100644 --- a/v4l2-spec/controls.sgml +++ b/v4l2-spec/controls.sgml @@ -492,8 +492,7 @@ supported. The control array is a &v4l2-ext-control; array. The v4l2_ext_control structure is very similar to &v4l2-control;, except for the fact that it also allows for 64-bit -values and pointers to be passed (although the latter is not yet used -anywhere). +values and pointers to be passed. It is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml index a433a1fc2..fe13602f7 100644 --- a/v4l2-spec/v4l2.sgml +++ b/v4l2-spec/v4l2.sgml @@ -159,10 +159,10 @@ applications. --> 0.26 - 2009-06-15 + 2009-07-23 hv Finalized the RDS capture API. Added modulator and RDS encoder -capabilities. +capabilities. Added support for string controls. diff --git a/v4l2-spec/vidioc-g-ext-ctrls.sgml b/v4l2-spec/vidioc-g-ext-ctrls.sgml index 510520254..44a8f5575 100644 --- a/v4l2-spec/vidioc-g-ext-ctrls.sgml +++ b/v4l2-spec/vidioc-g-ext-ctrls.sgml @@ -68,20 +68,35 @@ initialize the &v4l2-ext-control; array pointed to by the controls fields. To get the current value of a set of controls applications -initialize the id field of each -&v4l2-ext-control; and call the -VIDIOC_G_EXT_CTRLS ioctl. +initialize the id, +size and reserved2 fields +of each &v4l2-ext-control; and call the +VIDIOC_G_EXT_CTRLS ioctl. String controls controls +must also set the string field. + + If the size is too small to +receive the control result (only relevant for pointer-type controls +like strings), then the driver will set size +to a valid value and return an &ENOSPC;. You should re-allocate the +string memory to this new size and try again. It is possible that the +same issue occurs again if the string has grown in the meantime. It is +recommended to call &VIDIOC-QUERYCTRL; first and use +maximum+1 as the new size +value. It is guaranteed that that is sufficient memory. + To change the value of a set of controls applications -initialize the id and -value fields of a &v4l2-ext-control; and +initialize the id, size, +reserved2 and +value/string fields of each &v4l2-ext-control; and call the VIDIOC_S_EXT_CTRLS ioctl. The controls will only be set if all control values are valid. - To check if the a set of controls have correct values -applications initialize the id and -value fields of a &v4l2-ext-control; and + To check if a set of controls have correct values applications +initialize the id, size, +reserved2 and +value/string fields of each &v4l2-ext-control; and call the VIDIOC_TRY_EXT_CTRLS ioctl. It is up to the driver whether wrong values are automatically adjusted to a valid value or if an error is returned. @@ -112,7 +127,23 @@ application. __u32 - reserved2[2] + size + + The total size in bytes of the payload of this +control. This is normally 0, but for pointer controls this should be +set to the size of the memory containing the payload, or that will +receive the payload. If VIDIOC_G_EXT_CTRLS finds +that this value is less than is required to store +the payload result, then it is set to a value large enough to store the +payload result and ENOSPC is returned. Note that for string controls +this size field should not be confused with the length of the string. +This field refers to the size of the memory that contains the string. +The actual length of the string may well be much smaller. + + + + __u32 + reserved2[1] Reserved for future extensions. Drivers and applications must set the array to zero. @@ -135,9 +166,9 @@ applications must set the array to zero. - void * - reserved - Reserved for future pointer-type controls. Currently unused. + char * + string + A pointer to a string. @@ -202,9 +233,16 @@ class. V4L2_CTRL_CLASS_MPEG 0x990000 The class containing MPEG compression controls. -These controls are described in section . + + V4L2_CTRL_CLASS_CAMERA + 0x9a0000 + The class containing camera controls. +These controls are described in . + @@ -241,6 +279,14 @@ because another applications took over control of the device function this control belongs to. + + ENOSPC + + The space reserved for the control's payload is insufficient. +The field size is set to a value that is enough +to store the payload and this error code is returned. + + diff --git a/v4l2-spec/vidioc-queryctrl.sgml b/v4l2-spec/vidioc-queryctrl.sgml index 9908a964d..413930226 100644 --- a/v4l2-spec/vidioc-queryctrl.sgml +++ b/v4l2-spec/vidioc-queryctrl.sgml @@ -93,8 +93,8 @@ next supported control, or EINVAL if there is none. Drivers which do not support this flag yet always return EINVAL. - Additional information is required for menu controls, the -name of menu items. To query them applications set the + Additional information is required for menu controls: the +names of the menu items. To query them applications set the id and index fields of &v4l2-querymenu; and call the VIDIOC_QUERYMENU ioctl with a pointer to this @@ -138,9 +138,12 @@ string. This information is intended for the user. __s32 minimum Minimum value, inclusive. This field gives a lower -bound for V4L2_CTRL_TYPE_INTEGER controls. It may -not be valid for any other type of control, including -V4L2_CTRL_TYPE_INTEGER64 controls. Note this is a +bound for V4L2_CTRL_TYPE_INTEGER controls and the +lowest valid index (always 0) for V4L2_CTRL_TYPE_MENU controls. +For V4L2_CTRL_TYPE_STRING controls the minimum value +gives the minimum length of the string. This length does not include the terminating +zero. It may not be valid for any other type of control, including +V4L2_CTRL_TYPE_INTEGER64 controls. Note that this is a signed value. @@ -149,16 +152,21 @@ signed value. Maximum value, inclusive. This field gives an upper bound for V4L2_CTRL_TYPE_INTEGER controls and the highest valid index for V4L2_CTRL_TYPE_MENU -controls. It may not be valid for any other type of control, including -V4L2_CTRL_TYPE_INTEGER64 controls. Note this is a +controls. +For V4L2_CTRL_TYPE_STRING controls the maximum value +gives the maximum length of the string. This length does not include the terminating +zero. It may not be valid for any other type of control, including +V4L2_CTRL_TYPE_INTEGER64 controls. Note that this is a signed value. __s32 step This field gives a step size for -V4L2_CTRL_TYPE_INTEGER controls. It may not be -valid for any other type of control, including +V4L2_CTRL_TYPE_INTEGER controls. For +V4L2_CTRL_TYPE_STRING controls this field refers to +the string length that has to be a multiple of this step size. +It may not be valid for any other type of control, including V4L2_CTRL_TYPE_INTEGER64 controls.Generally drivers should not scale hardware control values. It may be necessary for example when the @@ -171,7 +179,7 @@ an integer control actually affecting hardware. Often the information is needed when the user can change controls by keyboard or GUI buttons, rather than a slider. When for example a hardware register accepts values 0-511 and the driver reports 0-65535, step should be -128.Note although signed, the step value is supposed to +128.Note that although signed, the step value is supposed to be always positive. @@ -295,6 +303,20 @@ Drivers must ignore the value passed with n/a A 64-bit integer valued control. Minimum, maximum and step size cannot be queried. + + + V4L2_CTRL_TYPE_STRING + >=0 + >=1 + >=0 + The minimum and maximum string lengths. The step size +means that the string must be (minimum + N * step) characters long for +N >= 0. These lengths do not include the terminating zero, so in order to +pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the +size field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can +set the size field to maximum+1. +Which character encoding is used will depend on the string control itself and +should be part of the control documentation. V4L2_CTRL_TYPE_CTRL_CLASS -- cgit v1.2.3 From 70c355bfe650b41cd70b5b55c2cc90cd810d0f13 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 8 Aug 2009 13:42:52 +0200 Subject: v4l2-spec: Add documentation description for FM TX extended control class From: Eduardo Valentin This single patch adds documentation description for FM Modulator (FM TX) Extended Control Class and its Control IDs. The text was added under "Extended Controls" section. The vidioc-g-ext-ctrls.sgml file was updated as well. Priority: normal Signed-off-by: Eduardo Valentin Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- v4l2-spec/Makefile | 1 + v4l2-spec/controls.sgml | 215 ++++++++++++++++++++++++++++++++++++++ v4l2-spec/vidioc-g-ext-ctrls.sgml | 7 ++ 3 files changed, 223 insertions(+) (limited to 'v4l2-spec') diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile index 3b4c321c4..a88420286 100644 --- a/v4l2-spec/Makefile +++ b/v4l2-spec/Makefile @@ -245,6 +245,7 @@ ENUMS = \ v4l2_power_line_frequency \ v4l2_priority \ v4l2_tuner_type \ + v4l2_preemphasis \ STRUCTS = \ v4l2_audio \ diff --git a/v4l2-spec/controls.sgml b/v4l2-spec/controls.sgml index dbe4f6f86..869198601 100644 --- a/v4l2-spec/controls.sgml +++ b/v4l2-spec/controls.sgml @@ -458,6 +458,12 @@ video is actually encoded into that format. Unfortunately, the original control API lacked some features needed for these new uses and so it was extended into the (not terribly originally named) extended control API. + + Even though the MPEG encoding API was the first effort +to use the Extended Control API, nowadays there are also other classes +of Extended Controls, such as Camera Controls and FM Transmitter Controls. +The Extended Controls API as well as all Extended Controls classes are +described in the following text.

@@ -1823,6 +1829,215 @@ be used, for example, to filter out the fluorescent light component.

+ +

+ FM Transmitter Control Reference + + The FM Transmitter (FM_TX) class includes controls for common features of +FM transmissions capable devices. Currently this class includes parameters for audio +compression, pilot tone generation, audio deviation limiter, RDS transmission and +tuning power features. + + + FM_TX Control IDs + + + + + + + + + + + ID + Type + Description + + + + + + V4L2_CID_FM_TX_CLASS + class + The FM_TX class +descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a +description of this control class. + + + V4L2_CID_RDS_TX_DEVIATION + integer + + Configures RDS signal frequency deviation level in Hz. +The range and step are driver-specific. + + + V4L2_CID_RDS_TX_PI + integer + + Sets the RDS Programme Identification field +for transmission. + + + V4L2_CID_RDS_TX_PTY + integer + + Sets the RDS Programme Type field for transmission. +This encodes up to 31 pre-defined programme types. + + + V4L2_CID_RDS_TX_PS_NAME + string + + Sets the Programme Service name (PS_NAME) for transmission. +It is intended for static display on a receiver. It is the primary aid to listeners in programme service +identification and selection. In Annex E of , the RDS specification, +there is a full description of the correct character encoding for Programme Service name strings. +Also from RDS specification, PS is usually a single eight character text. However, it is also possible +to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured +with steps of 8 characters. The result is it must always contain a string with size multiple of 8. + + + V4L2_CID_RDS_TX_RADIO_TEXT + string + + Sets the Radio Text info for transmission. It is a textual description of +what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names, +programme-related information or any other text. In these cases, RadioText should be used in addition to +V4L2_CID_RDS_TX_PS_NAME. The encoding for Radio Text strings is also fully described +in Annex E of . The length of Radio Text strings depends on which RDS Block is being +used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible +to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured +with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. + + + V4L2_CID_AUDIO_LIMITER_ENABLED + boolean + + Enables or disables the audio deviation limiter feature. +The limiter is useful when trying to maximize the audio volume, minimize receiver-generated +distortion and prevent overmodulation. + + + + V4L2_CID_AUDIO_LIMITER_RELEASE_TIME + integer + + Sets the audio deviation limiter feature release time. +Unit is in useconds. Step and range are driver-specific. + + + V4L2_CID_AUDIO_LIMITER_DEVIATION + integer + + Configures audio frequency deviation level in Hz. +The range and step are driver-specific. + + + V4L2_CID_AUDIO_COMPRESSION_ENABLED + boolean + + Enables or disables the audio compression feature. +This feature amplifies signals below the threshold by a fixed gain and compresses audio +signals above the threshold by the ratio of Threshold/(Gain + Threshold). + + + V4L2_CID_AUDIO_COMPRESSION_GAIN + integer + + Sets the gain for audio compression feature. It is +a dB value. The range and step are driver-specific. + + + V4L2_CID_AUDIO_COMPRESSION_THRESHOLD + integer + + Sets the threshold level for audio compression freature. +It is a dB value. The range and step are driver-specific. + + + V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME + integer + + Sets the attack time for audio compression feature. +It is a useconds value. The range and step are driver-specific. + + + V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME + integer + + Sets the release time for audio compression feature. +It is a useconds value. The range and step are driver-specific. + + + V4L2_CID_PILOT_TONE_ENABLED + boolean + + Enables or disables the pilot tone generation feature. + + + V4L2_CID_PILOT_TONE_DEVIATION + integer + + Configures pilot tone frequency deviation level. Unit is +in Hz. The range and step are driver-specific. + + + V4L2_CID_PILOT_TONE_FREQUENCY + integer + + Configures pilot tone frequency value. Unit is +in Hz. The range and step are driver-specific. + + + V4L2_CID_TUNE_PREEMPHASIS + integer + + Configures the pre-emphasis value for broadcasting. +A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies. +Depending on the region, a time constant of either 50 or 75 useconds is used. The enum v4l2_preemphasis +defines possible values for pre-emphasis. Here they are: + + + + + V4L2_PREEMPHASIS_DISABLED + No pre-emphasis is applied. + + + V4L2_PREEMPHASIS_50_uS + A pre-emphasis of 50 uS is used. + + + V4L2_PREEMPHASIS_75_uS + A pre-emphasis of 75 uS is used. + + + + + + + V4L2_CID_TUNE_POWER_LEVEL + integer + + Sets the output power level for signal transmission. +Unit is in dBuV. Range and step are driver-specific. + + + V4L2_CID_TUNE_ANTENNA_CAPACITOR + integer + + This selects the value of antenna tuning capacitor +manually or automatically if set to zero. Unit, range and step are driver-specific. + + + + +

+ +For more details about RDS specification, refer to + document, from CENELEC. +

+ + 0.29 + 2009-08-26 + ev + Added documentation for string controls and for FM Transmitter controls. + + 0.28 2009-08-26 diff --git a/v4l2-spec/vidioc-queryctrl.sgml b/v4l2-spec/vidioc-queryctrl.sgml index 413930226..abf56b22e 100644 --- a/v4l2-spec/vidioc-queryctrl.sgml +++ b/v4l2-spec/vidioc-queryctrl.sgml @@ -306,15 +306,15 @@ and step size cannot be queried. V4L2_CTRL_TYPE_STRING - >=0 - >=1 - >=0 + ≥ 0 + ≥ 1 + ≥ 0 The minimum and maximum string lengths. The step size means that the string must be (minimum + N * step) characters long for -N >= 0. These lengths do not include the terminating zero, so in order to +N ≥ 0. These lengths do not include the terminating zero, so in order to pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the size field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can -set the size field to maximum+1. +set the size field to maximum + 1. Which character encoding is used will depend on the string control itself and should be part of the control documentation. -- cgit v1.2.3