From aeda3e7c6524956c616040f4265f16343b3edd83 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Thu, 31 May 2012 19:51:05 -0300 Subject: [media] v4l: Correct create_bufs documentation Patch id 6016af82eafcb6e086a8f2a2197b46029a843d68 ("[media] v4l2: use __u32 rather than enums in ioctl() structs") unintentionally changes the type of the format field in struct v4l2_create_buffers from struct v4l2_format to __u32. Revert that change. Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-create-bufs.xml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index 765549ff8a71..7cf3116c2cc5 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -108,10 +108,9 @@ information. /> - __u32 + &v4l2-format; format - Filled in by the application, preserved by the driver. - See . + Filled in by the application, preserved by the driver. __u32 -- cgit v1.2.3 From e4cca4edbce693238ba4d75269db082f34da48bb Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 28 May 2012 07:30:28 -0300 Subject: [media] v4l2 spec: document the new v4l2_tuner capabilities Update the spec with the new capabilities and specify new error codes for S_HW_FREQ_SEEK. Signed-off-by: Hans Verkuil Acked-by: Hans de Goede Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-g-frequency.xml | 6 ++++++ Documentation/DocBook/media/v4l/vidioc-g-tuner.xml | 12 ++++++++++++ .../DocBook/media/v4l/vidioc-s-hw-freq-seek.xml | 18 +++++++++++++++--- 3 files changed, 33 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml index 69c178a4d205..40e58a42eb26 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml @@ -135,6 +135,12 @@ bounds or the value in the type field is wrong. + + EBUSY + + A hardware seek is in progress. + + diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index 62a1aa200a36..95d5371c1709 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -275,6 +275,18 @@ can or must be switched. (B/G PAL tuners for example are typically not see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only V4L2_TUNER_ANALOG_TV tuners can have this capability. + + V4L2_TUNER_CAP_HWSEEK_BOUNDED + 0x0004 + If set, then this tuner supports the hardware seek functionality + where the seek stops when it reaches the end of the frequency range. + + + V4L2_TUNER_CAP_HWSEEK_WRAP + 0x0008 + If set, then this tuner supports the hardware seek functionality + where the seek wraps around when it reaches the end of the frequency range. + V4L2_TUNER_CAP_STEREO 0x0010 diff --git a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml index 407dfceb71f0..f4db44d0d95a 100644 --- a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml +++ b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml @@ -58,6 +58,9 @@ To do this applications initialize the tuner, call the VIDIOC_S_HW_FREQ_SEEK ioctl with a pointer to this structure. + If an error is returned, then the original frequency will + be restored. + This ioctl is supported if the V4L2_CAP_HW_FREQ_SEEK capability is set. @@ -87,7 +90,10 @@ field and the &v4l2-tuner; index field. __u32 wrap_around - If non-zero, wrap around when at the end of the frequency range, else stop seeking. + If non-zero, wrap around when at the end of the frequency range, else stop seeking. + The &v4l2-tuner; capability field will tell you what the + hardware supports. + __u32 @@ -118,9 +124,15 @@ wrong. - EAGAIN + ENODATA + + The hardware seek found no channels. + + + + EBUSY - The ioctl timed-out. Try again. + Another hardware seek is already in progress. -- cgit v1.2.3 From efcf5bdac839f0dc9dc39ed1ad9fe2dbab49d00a Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 28 May 2012 07:42:54 -0300 Subject: [media] V4L2 spec: clarify a few modulator issues Signed-off-by: Hans Verkuil Acked-by: Hans de Goede Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/common.xml | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index 4101aeb56540..b91d25313b63 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -464,14 +464,14 @@ The type field of the respective tuner field contains the index number of the tuner. - Radio devices have exactly one tuner with index zero, no + Radio input devices have exactly one tuner with index zero, no video inputs. To query and change tuner properties applications use the &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The &v4l2-tuner; returned by VIDIOC_G_TUNER also contains signal status information applicable when the tuner of the -current video input, or a radio tuner is queried. Note that +current video or radio input is queried. Note that VIDIOC_S_TUNER does not switch the current tuner, when there is more than one at all. The tuner is solely determined by the current video input. Drivers must support both ioctls and set the @@ -491,8 +491,17 @@ the modulator. The type field of the respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is set to V4L2_OUTPUT_TYPE_MODULATOR and its modulator field contains the index number -of the modulator. This specification does not define radio output -devices. +of the modulator. + + Radio output devices have exactly one modulator with index +zero, no video outputs. + + A video or radio device cannot support both a tuner and a +modulator. Two separate device nodes will have to be used for such +hardware, one that supports the tuner functionality and one that supports +the modulator functionality. The reason is a limitation with the +&VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency +is for a tuner or a modulator. To query and change modulator properties applications use the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that -- cgit v1.2.3 From f7dd6c247f4318c47677a659dbb4622cc5da0690 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Thu, 31 May 2012 05:09:08 -0300 Subject: [media] V4L2 Spec: fix typo: NTSC -> NRSC Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/biblio.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index 7c49facecd25..1078e45f189f 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -194,7 +194,7 @@ in the frequency range from 87,5 to 108,0 MHz National Radio Systems Committee (http://www.nrscstandards.org) - NTSC-4: United States RBDS Standard + NRSC-4: United States RBDS Standard -- cgit v1.2.3 From 7bdc0fb14f106875c840d47b53f497f6e2b30382 Mon Sep 17 00:00:00 2001 From: Martin Blumenstingl Date: Tue, 12 Jun 2012 18:19:26 -0300 Subject: [media] Add support for downloading the firmware of the Terratec Cinergy HTC Stick HD's firmware As of June 2012 it uses the same firmware as the Hauppauge WinTV HVR 930C. Signed-off-by: Martin Blumenstingl Signed-off-by: Mauro Carvalho Chehab --- Documentation/dvb/get_dvb_firmware | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware index fbb241174486..94b01689808d 100755 --- a/Documentation/dvb/get_dvb_firmware +++ b/Documentation/dvb/get_dvb_firmware @@ -29,7 +29,7 @@ use IO::Handle; "af9015", "ngene", "az6027", "lme2510_lg", "lme2510c_s7395", "lme2510c_s7395_old", "drxk", "drxk_terratec_h5", "drxk_hauppauge_hvr930c", "tda10071", "it9135", "it9137", - "drxk_pctv"); + "drxk_pctv", "drxk_terratec_htc_stick"); # Check args syntax() if (scalar(@ARGV) != 1); @@ -676,6 +676,24 @@ sub drxk_terratec_h5 { "$fwfile" } +sub drxk_terratec_htc_stick { + my $url = "http://ftp.terratec.de/Receiver/Cinergy_HTC_Stick/Updates/"; + my $zipfile = "Cinergy_HTC_Stick_Drv_5.09.1202.00_XP_Vista_7.exe"; + my $hash = "6722a2442a05423b781721fbc069ed5e"; + my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 0); + my $drvfile = "Cinergy HTC Stick/BDA Driver 5.09.1202.00/Windows 32 Bit/emOEM.sys"; + my $fwfile = "dvb-usb-terratec-htc-stick-drxk.fw"; + + checkstandard(); + + wgetfile($zipfile, $url . $zipfile); + verify($zipfile, $hash); + unzip($zipfile, $tmpdir); + extract("$tmpdir/$drvfile", 0x4e5c0, 42692, "$fwfile"); + + "$fwfile" +} + sub it9135 { my $sourcefile = "dvb-usb-it9135.zip"; my $url = "http://www.ite.com.tw/uploads/firmware/v3.6.0.0/$sourcefile"; -- cgit v1.2.3 From 2b719d7baf490e24ce7d817c6337b7c87fda84c1 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Wed, 2 May 2012 09:40:03 -0300 Subject: [media] v4l: drop v4l2_buffer.input and V4L2_BUF_FLAG_INPUT Remove input field in struct v4l2_buffer and flag V4L2_BUF_FLAG_INPUT which tells the former is valid. The flag is used by no driver currently. Also change the documentation accordingly. Signed-off-by: Sakari Ailus Acked-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 12 ++++++++++++ Documentation/DocBook/media/v4l/io.xml | 19 +++++-------------- Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 9 +++------ drivers/media/video/cpia2/cpia2_v4l.c | 2 +- drivers/media/video/v4l2-compat-ioctl32.c | 11 +++++------ drivers/media/video/videobuf-core.c | 16 ---------------- drivers/media/video/videobuf2-core.c | 5 ++--- include/linux/videodev2.h | 3 +-- 8 files changed, 29 insertions(+), 48 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index ea42ef824948..a8b374930405 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2458,6 +2458,18 @@ details. +
+ V4L2 in Linux 3.5 + + + Replaced input in + v4l2_buffer by + reserved2 and removed + V4L2_BUF_FLAG_INPUT. + + +
+
Relation of V4L2 to other Linux multimedia APIs diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index fd6aca2922b6..1885cc0755cb 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -683,14 +683,12 @@ memory, set by the application. See for details. __u32 - input + reserved2 - Some video capture drivers support rapid and -synchronous video input changes, a function useful for example in -video surveillance applications. For this purpose applications set the -V4L2_BUF_FLAG_INPUT flag, and this field to the -number of a video input as in &v4l2-input; field -index. + A place holder for future extensions and custom +(driver defined) buffer types +V4L2_BUF_TYPE_PRIVATE and higher. Applications +should set this to 0. __u32 @@ -921,13 +919,6 @@ previous key frame. The timecode field is valid. Drivers set or clear this flag when the VIDIOC_DQBUF ioctl is called. - - - V4L2_BUF_FLAG_INPUT - 0x0200 - The input field is valid. -Applications set or clear this flag before calling the -VIDIOC_QBUF ioctl. V4L2_BUF_FLAG_PREPARED diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 9caa49af580f..77ff5be0809d 100644 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml @@ -71,12 +71,9 @@ initialize the bytesused, field and timestamp fields, see for details. -Applications must also set flags to 0. If a driver -supports capturing from specific video inputs and you want to specify a video -input, then flags should be set to -V4L2_BUF_FLAG_INPUT and the field -input must be initialized to the desired input. -The reserved field must be set to 0. When using +Applications must also set flags to 0. +The reserved2 and +reserved fields must be set to 0. When using the multi-planar API, the m.planes field must contain a userspace pointer to a filled-in array of &v4l2-plane; and the length diff --git a/drivers/media/video/cpia2/cpia2_v4l.c b/drivers/media/video/cpia2/cpia2_v4l.c index 55e92902a76c..a62a7b739991 100644 --- a/drivers/media/video/cpia2/cpia2_v4l.c +++ b/drivers/media/video/cpia2/cpia2_v4l.c @@ -932,7 +932,7 @@ static int cpia2_dqbuf(struct file *file, void *fh, struct v4l2_buffer *buf) buf->sequence = cam->buffers[buf->index].seq; buf->m.offset = cam->buffers[buf->index].data - cam->frame_buffer; buf->length = cam->frame_size; - buf->input = 0; + buf->reserved2 = 0; buf->reserved = 0; memset(&buf->timecode, 0, sizeof(buf->timecode)); diff --git a/drivers/media/video/v4l2-compat-ioctl32.c b/drivers/media/video/v4l2-compat-ioctl32.c index 5327ad3a6390..658ba46ee9d2 100644 --- a/drivers/media/video/v4l2-compat-ioctl32.c +++ b/drivers/media/video/v4l2-compat-ioctl32.c @@ -327,7 +327,7 @@ struct v4l2_buffer32 { compat_caddr_t planes; } m; __u32 length; - __u32 input; + __u32 reserved2; __u32 reserved; }; @@ -387,8 +387,7 @@ static int get_v4l2_buffer32(struct v4l2_buffer *kp, struct v4l2_buffer32 __user get_user(kp->index, &up->index) || get_user(kp->type, &up->type) || get_user(kp->flags, &up->flags) || - get_user(kp->memory, &up->memory) || - get_user(kp->input, &up->input)) + get_user(kp->memory, &up->memory) return -EFAULT; if (V4L2_TYPE_IS_OUTPUT(kp->type)) @@ -472,8 +471,7 @@ static int put_v4l2_buffer32(struct v4l2_buffer *kp, struct v4l2_buffer32 __user put_user(kp->index, &up->index) || put_user(kp->type, &up->type) || put_user(kp->flags, &up->flags) || - put_user(kp->memory, &up->memory) || - put_user(kp->input, &up->input)) + put_user(kp->memory, &up->memory) return -EFAULT; if (put_user(kp->bytesused, &up->bytesused) || @@ -482,7 +480,8 @@ static int put_v4l2_buffer32(struct v4l2_buffer *kp, struct v4l2_buffer32 __user put_user(kp->timestamp.tv_usec, &up->timestamp.tv_usec) || copy_to_user(&up->timecode, &kp->timecode, sizeof(struct v4l2_timecode)) || put_user(kp->sequence, &up->sequence) || - put_user(kp->reserved, &up->reserved)) + put_user(kp->reserved2, &up->reserved2) || + put_user(kp->reserved, &up->reserved) return -EFAULT; if (V4L2_TYPE_IS_MULTIPLANAR(kp->type)) { diff --git a/drivers/media/video/videobuf-core.c b/drivers/media/video/videobuf-core.c index ffdf59cfe405..bf7a326b1cdc 100644 --- a/drivers/media/video/videobuf-core.c +++ b/drivers/media/video/videobuf-core.c @@ -359,11 +359,6 @@ static void videobuf_status(struct videobuf_queue *q, struct v4l2_buffer *b, break; } - if (vb->input != UNSET) { - b->flags |= V4L2_BUF_FLAG_INPUT; - b->input = vb->input; - } - b->field = vb->field; b->timestamp = vb->ts; b->bytesused = vb->size; @@ -402,7 +397,6 @@ int __videobuf_mmap_setup(struct videobuf_queue *q, break; q->bufs[i]->i = i; - q->bufs[i]->input = UNSET; q->bufs[i]->memory = memory; q->bufs[i]->bsize = bsize; switch (memory) { @@ -566,16 +560,6 @@ int videobuf_qbuf(struct videobuf_queue *q, struct v4l2_buffer *b) goto done; } - if (b->flags & V4L2_BUF_FLAG_INPUT) { - if (b->input >= q->inputs) { - dprintk(1, "qbuf: wrong input.\n"); - goto done; - } - buf->input = b->input; - } else { - buf->input = UNSET; - } - switch (b->memory) { case V4L2_MEMORY_MMAP: if (0 == buf->baddr) { diff --git a/drivers/media/video/videobuf2-core.c b/drivers/media/video/videobuf2-core.c index 9d4e9edbd2e7..ec24718b3ed0 100644 --- a/drivers/media/video/videobuf2-core.c +++ b/drivers/media/video/videobuf2-core.c @@ -336,9 +336,9 @@ static int __fill_v4l2_buffer(struct vb2_buffer *vb, struct v4l2_buffer *b) struct vb2_queue *q = vb->vb2_queue; int ret; - /* Copy back data such as timestamp, flags, input, etc. */ + /* Copy back data such as timestamp, flags, etc. */ memcpy(b, &vb->v4l2_buf, offsetof(struct v4l2_buffer, m)); - b->input = vb->v4l2_buf.input; + b->reserved2 = vb->v4l2_buf.reserved2; b->reserved = vb->v4l2_buf.reserved; if (V4L2_TYPE_IS_MULTIPLANAR(q->type)) { @@ -860,7 +860,6 @@ static int __fill_vb2_buffer(struct vb2_buffer *vb, const struct v4l2_buffer *b, vb->v4l2_buf.field = b->field; vb->v4l2_buf.timestamp = b->timestamp; - vb->v4l2_buf.input = b->input; vb->v4l2_buf.flags = b->flags & ~V4L2_BUFFER_STATE_FLAGS; return 0; diff --git a/include/linux/videodev2.h b/include/linux/videodev2.h index f79d0cc565ab..a61edb353273 100644 --- a/include/linux/videodev2.h +++ b/include/linux/videodev2.h @@ -657,7 +657,7 @@ struct v4l2_buffer { struct v4l2_plane *planes; } m; __u32 length; - __u32 input; + __u32 reserved2; __u32 reserved; }; @@ -671,7 +671,6 @@ struct v4l2_buffer { /* Buffer is ready, but the data contained within is corrupted. */ #define V4L2_BUF_FLAG_ERROR 0x0040 #define V4L2_BUF_FLAG_TIMECODE 0x0100 /* timecode field is valid */ -#define V4L2_BUF_FLAG_INPUT 0x0200 /* input field is valid */ #define V4L2_BUF_FLAG_PREPARED 0x0400 /* Buffer is prepared for queuing */ /* Cache handling flags */ #define V4L2_BUF_FLAG_NO_CACHE_INVALIDATE 0x0800 -- cgit v1.2.3 From f244e6c308be3acc445719f0fd72b5fb182c0895 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 5 Jul 2012 22:35:55 -0300 Subject: [media] get_dvb_firmware: add logic to get sms1xx-hcw* firmware The firmwares are there at the same place for a long time. However, each time I need to remember where it is, I need to seek at the net. The better is to just add a logic at the get_dvb_firmare script, in order to obtain it from a reliable source. Cc: Steven Toth Signed-off-by: Mauro Carvalho Chehab --- Documentation/dvb/get_dvb_firmware | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware index 94b01689808d..12d3952e83d5 100755 --- a/Documentation/dvb/get_dvb_firmware +++ b/Documentation/dvb/get_dvb_firmware @@ -29,7 +29,7 @@ use IO::Handle; "af9015", "ngene", "az6027", "lme2510_lg", "lme2510c_s7395", "lme2510c_s7395_old", "drxk", "drxk_terratec_h5", "drxk_hauppauge_hvr930c", "tda10071", "it9135", "it9137", - "drxk_pctv", "drxk_terratec_htc_stick"); + "drxk_pctv", "drxk_terratec_htc_stick", "sms1xxx_hcw"); # Check args syntax() if (scalar(@ARGV) != 1); @@ -766,6 +766,28 @@ sub drxk_pctv { "$fwfile"; } +sub sms1xxx_hcw { + my $url = "http://steventoth.net/linux/sms1xxx/"; + my %files = ( + 'sms1xxx-hcw-55xxx-dvbt-01.fw' => "afb6f9fb9a71d64392e8564ef9577e5a", + 'sms1xxx-hcw-55xxx-dvbt-02.fw' => "b44807098ba26e52cbedeadc052ba58f", + 'sms1xxx-hcw-55xxx-isdbt-02.fw' => "dae934eeea85225acbd63ce6cfe1c9e4", + ); + + checkstandard(); + + my $allfiles; + foreach my $fwfile (keys %files) { + wgetfile($fwfile, "$url/$fwfile"); + verify($fwfile, $files{$fwfile}); + $allfiles .= " $fwfile"; + } + + $allfiles =~ s/^\s//; + + $allfiles; +} + # --------------------------------------------------------------- # Utilities -- cgit v1.2.3 From 5d44f5e3e388739f017a74e73dab2a995673915f Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 22 Jun 2012 05:47:30 -0300 Subject: [media] Spec: document CREATE_BUFS behavior if count == 0 Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-create-bufs.xml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index a2474ecb574a..5e73b1c8d095 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -97,7 +97,13 @@ information. __u32 count - The number of buffers requested or granted. + The number of buffers requested or granted. If count == 0, then + VIDIOC_CREATE_BUFS will set index + to the current number of created buffers, and it will check the validity of + memory and format.type. + If those are invalid -1 is returned and errno is set to &EINVAL;, + otherwise VIDIOC_CREATE_BUFS returns 0. It will + never set errno to &EBUSY; in this particular case. __u32 -- cgit v1.2.3 From 4a77a8361fe79b78b741640b484a97c8d47e307f Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 2 Jul 2012 05:43:34 -0300 Subject: [media] v4l2-framework.txt: Update the locking documentation This documents the new queue->lock and how to use it. It also removes the documentation of v4l2_disable_ioctl_locking: this is only used in gspca and will be removed once gspca has been converted to vb2. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/v4l2-framework.txt | 73 +++++++++++++++------------- 1 file changed, 39 insertions(+), 34 deletions(-) (limited to 'Documentation') diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index 1f5905270050..89318be6c1d2 100644 --- a/Documentation/video4linux/v4l2-framework.txt +++ b/Documentation/video4linux/v4l2-framework.txt @@ -594,6 +594,15 @@ You should also set these fields: unlocked_ioctl file operation is called this lock will be taken by the core and released afterwards. See the next section for more details. +- queue: a pointer to the struct vb2_queue associated with this device node. + If queue is non-NULL, and queue->lock is non-NULL, then queue->lock is + used for the queuing ioctls (VIDIOC_REQBUFS, CREATE_BUFS, QBUF, DQBUF, + QUERYBUF, PREPARE_BUF, STREAMON and STREAMOFF) instead of the lock above. + That way the vb2 queuing framework does not have to wait for other ioctls. + This queue pointer is also used by the vb2 helper functions to check for + queuing ownership (i.e. is the filehandle calling it allowed to do the + operation). + - prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY. If left to NULL, then it will use the struct v4l2_prio_state in v4l2_device. If you want to have a separate priority state per (group of) device node(s), @@ -647,47 +656,43 @@ manually set the struct media_entity type and name fields. A reference to the entity will be automatically acquired/released when the video device is opened/closed. -v4l2_file_operations and locking --------------------------------- - -You can set a pointer to a mutex_lock in struct video_device. Usually this -will be either a top-level mutex or a mutex per device node. By default this -lock will be used for unlocked_ioctl, but you can disable locking for -selected ioctls by calling: - - void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd); - -E.g.: v4l2_disable_ioctl_locking(vdev, VIDIOC_DQBUF); +ioctls and locking +------------------ -You have to call this before you register the video_device. +The V4L core provides optional locking services. The main service is the +lock field in struct video_device, which is a pointer to a mutex. If you set +this pointer, then that will be used by unlocked_ioctl to serialize all ioctls. -Particularly with USB drivers where certain commands such as setting controls -can take a long time you may want to do your own locking for the buffer queuing -ioctls. +If you are using the videobuf2 framework, then there is a second lock that you +can set: video_device->queue->lock. If set, then this lock will be used instead +of video_device->lock to serialize all queuing ioctls (see the previous section +for the full list of those ioctls). -If you want still finer-grained locking then you have to set mutex_lock to NULL -and do you own locking completely. +The advantage of using a different lock for the queuing ioctls is that for some +drivers (particularly USB drivers) certain commands such as setting controls +can take a long time, so you want to use a separate lock for the buffer queuing +ioctls. That way your VIDIOC_DQBUF doesn't stall because the driver is busy +changing the e.g. exposure of the webcam. -It is up to the driver developer to decide which method to use. However, if -your driver has high-latency operations (for example, changing the exposure -of a USB webcam might take a long time), then you might be better off with -doing your own locking if you want to allow the user to do other things with -the device while waiting for the high-latency command to finish. +Of course, you can always do all the locking yourself by leaving both lock +pointers at NULL. -If a lock is specified then all ioctl commands will be serialized on that -lock. If you use videobuf then you must pass the same lock to the videobuf -queue initialize function: if videobuf has to wait for a frame to arrive, then -it will temporarily unlock the lock and relock it afterwards. If your driver -also waits in the code, then you should do the same to allow other processes -to access the device node while the first process is waiting for something. +If you use the old videobuf then you must pass the video_device lock to the +videobuf queue initialize function: if videobuf has to wait for a frame to +arrive, then it will temporarily unlock the lock and relock it afterwards. If +your driver also waits in the code, then you should do the same to allow other +processes to access the device node while the first process is waiting for +something. In the case of videobuf2 you will need to implement the wait_prepare and -wait_finish callbacks to unlock/lock if applicable. In particular, if you use -the lock in struct video_device then you must unlock/lock this mutex in -wait_prepare and wait_finish. - -The implementation of a hotplug disconnect should also take the lock before -calling v4l2_device_disconnect. +wait_finish callbacks to unlock/lock if applicable. If you use the queue->lock +pointer, then you can use the helper functions vb2_ops_wait_prepare/finish. + +The implementation of a hotplug disconnect should also take the lock from +video_device before calling v4l2_device_disconnect. If you are also using +video_device->queue->lock, then you have to first lock video_device->queue->lock +followed by video_device->lock. That way you can be sure no ioctl is running +when you call v4l2_device_disconnect. video_device registration ------------------------- -- cgit v1.2.3 From c133482300113b3b71fa4a1fd2118531e765b36a Mon Sep 17 00:00:00 2001 From: Sylwester Nawrocki Date: Sun, 20 May 2012 11:17:12 -0300 Subject: [media] V4L: Remove "_ACTIVE" from the selection target name definitions This patch drops the _ACTIVE part from the selection target names as a prerequisite to unify the selection target names across the subdev and regular video node API. The meaning of V4L2_SEL_TGT_*_ACTIVE and V4L2_SUBDEV_SEL_TGT_*_ACTUAL selection targets is logically the same. Different names add to confusion where both APIs are used in a single driver or an application. For some system configurations different names may lead to interoperability issues. For backwards compatibility V4L2_SEL_TGT_CROP_ACTIVE and V4L2_SEL_TGT_COMPOSE_ACTIVE are defined as aliases to V4L2_SEL_TGT_CROP and V4L2_SEL_TGT_COMPOSE. These aliases will be removed after deprecation period, according to Documentation/feature-removal-schedule.txt. Signed-off-by: Sylwester Nawrocki Signed-off-by: Kyungmin Park Acked-by: Laurent Pinchart Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/selection-api.xml | 24 +++++++++++----------- .../DocBook/media/v4l/vidioc-g-selection.xml | 15 +++++++------- drivers/media/video/s5p-fimc/fimc-capture.c | 14 ++++++------- drivers/media/video/s5p-fimc/fimc-lite.c | 4 ++-- drivers/media/video/s5p-jpeg/jpeg-core.c | 4 ++-- drivers/media/video/s5p-tv/mixer_video.c | 8 ++++---- include/linux/videodev2.h | 8 ++++++-- 7 files changed, 41 insertions(+), 36 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index b299e4779354..ac013e50e0bd 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -91,7 +91,7 @@ top/left corner at position (0,0) . The rectangle's coordinates are expressed in pixels. The top left corner, width and height of the source rectangle, that is -the area actually sampled, is given by the V4L2_SEL_TGT_CROP_ACTIVE +the area actually sampled, is given by the V4L2_SEL_TGT_CROP target. It uses the same coordinate system as V4L2_SEL_TGT_CROP_BOUNDS . The active cropping area must lie completely inside the capture boundaries. The driver may further adjust the @@ -111,7 +111,7 @@ height are equal to the image size set by VIDIOC_S_FMT . The part of a buffer into which the image is inserted by the hardware is -controlled by the V4L2_SEL_TGT_COMPOSE_ACTIVE target. +controlled by the V4L2_SEL_TGT_COMPOSE target. The rectangle's coordinates are also expressed in the same coordinate system as the bounds rectangle. The composing rectangle must lie completely inside bounds rectangle. The driver must adjust the composing rectangle to fit to the @@ -125,7 +125,7 @@ bounding rectangle. The part of a buffer that is modified by the hardware is given by V4L2_SEL_TGT_COMPOSE_PADDED . It contains all pixels -defined using V4L2_SEL_TGT_COMPOSE_ACTIVE plus all +defined using V4L2_SEL_TGT_COMPOSE plus all padding data modified by hardware during insertion process. All pixels outside this rectangle must not be changed by the hardware. The content of pixels that lie inside the padded area but outside active area is @@ -153,7 +153,7 @@ specified using VIDIOC_S_FMT ioctl. The top left corner, width and height of the source rectangle, that is the area from which image date are processed by the hardware, is given by the - V4L2_SEL_TGT_CROP_ACTIVE . Its coordinates are expressed + V4L2_SEL_TGT_CROP . Its coordinates are expressed in in the same coordinate system as the bounds rectangle. The active cropping area must lie completely inside the crop boundaries and the driver may further adjust the requested size and/or position according to hardware @@ -165,7 +165,7 @@ bounding rectangle. The part of a video signal or graphics display where the image is inserted by the hardware is controlled by -V4L2_SEL_TGT_COMPOSE_ACTIVE target. The rectangle's coordinates +V4L2_SEL_TGT_COMPOSE target. The rectangle's coordinates are expressed in pixels. The composing rectangle must lie completely inside the bounds rectangle. The driver must adjust the area to fit to the bounding limits. Moreover, the driver can perform other adjustments according to @@ -184,7 +184,7 @@ such a padded area is driver-dependent feature not covered by this document. Driver developers are encouraged to keep padded rectangle equal to active one. The padded target is accessed by the V4L2_SEL_TGT_COMPOSE_PADDED identifier. It must contain all pixels from the -V4L2_SEL_TGT_COMPOSE_ACTIVE target. +V4L2_SEL_TGT_COMPOSE target.
@@ -193,8 +193,8 @@ V4L2_SEL_TGT_COMPOSE_ACTIVE target. Scaling control An application can detect if scaling is performed by comparing the width -and the height of rectangles obtained using V4L2_SEL_TGT_CROP_ACTIVE - and V4L2_SEL_TGT_COMPOSE_ACTIVE targets. If +and the height of rectangles obtained using V4L2_SEL_TGT_CROP + and V4L2_SEL_TGT_COMPOSE targets. If these are not equal then the scaling is applied. The application can compute the scaling ratios using these values. @@ -252,7 +252,7 @@ area) ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); if (ret) exit(-1); - sel.target = V4L2_SEL_TGT_CROP_ACTIVE; + sel.target = V4L2_SEL_TGT_CROP; ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); if (ret) exit(-1); @@ -281,7 +281,7 @@ area) r.left = sel.r.width / 4; r.top = sel.r.height / 4; sel.r = r; - sel.target = V4L2_SEL_TGT_COMPOSE_ACTIVE; + sel.target = V4L2_SEL_TGT_COMPOSE; sel.flags = V4L2_SEL_FLAG_LE; ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); if (ret) @@ -298,11 +298,11 @@ V4L2_BUF_TYPE_VIDEO_OUTPUT for other devices &v4l2-selection; compose = { .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, - .target = V4L2_SEL_TGT_COMPOSE_ACTIVE, + .target = V4L2_SEL_TGT_COMPOSE, }; &v4l2-selection; crop = { .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, - .target = V4L2_SEL_TGT_CROP_ACTIVE, + .target = V4L2_SEL_TGT_CROP, }; double hscale, vscale; diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index bb04eff75f45..6376e57ff576 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -65,8 +65,8 @@ Do not use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE . Use V4L2_BUF_TYPE_VIDEO_OUTPUT instead of V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE . The next step is setting the value of &v4l2-selection; target field -to V4L2_SEL_TGT_CROP_ACTIVE ( -V4L2_SEL_TGT_COMPOSE_ACTIVE ). Please refer to table V4L2_SEL_TGT_CROP ( +V4L2_SEL_TGT_COMPOSE ). Please refer to table or for additional targets. The flags and reserved fields of &v4l2-selection; are ignored and they must be filled @@ -86,8 +86,8 @@ use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE . Use V4L2_BUF_TYPE_VIDEO_OUTPUT instead of V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE . The next step is setting the value of &v4l2-selection; target to -V4L2_SEL_TGT_CROP_ACTIVE ( -V4L2_SEL_TGT_COMPOSE_ACTIVE ). Please refer to table V4L2_SEL_TGT_CROP ( +V4L2_SEL_TGT_COMPOSE ). Please refer to table or for additional targets. The &v4l2-rect; r rectangle need to be set to the desired active area. Field &v4l2-selection; reserved @@ -161,7 +161,7 @@ exist no rectangle that satisfies the constraints. &cs-def; - V4L2_SEL_TGT_CROP_ACTIVE + V4L2_SEL_TGT_CROP 0x0000 The area that is currently cropped by hardware. @@ -176,7 +176,7 @@ exist no rectangle that satisfies the constraints.Limits for the cropping rectangle. - V4L2_SEL_TGT_COMPOSE_ACTIVE + V4L2_SEL_TGT_COMPOSE 0x0100 The area to which data is composed by hardware. @@ -193,7 +193,8 @@ exist no rectangle that satisfies the constraints. V4L2_SEL_TGT_COMPOSE_PADDED 0x0103 - The active area and all padding pixels that are inserted or modified by hardware. + The active area and all padding pixels that are inserted or + modified by hardware. diff --git a/drivers/media/video/s5p-fimc/fimc-capture.c b/drivers/media/video/s5p-fimc/fimc-capture.c index 62ce5399c4cf..a3cd78d33913 100644 --- a/drivers/media/video/s5p-fimc/fimc-capture.c +++ b/drivers/media/video/s5p-fimc/fimc-capture.c @@ -655,7 +655,7 @@ static void fimc_capture_try_selection(struct fimc_ctx *ctx, r->left = r->top = 0; return; } - if (target == V4L2_SEL_TGT_COMPOSE_ACTIVE) { + if (target == V4L2_SEL_TGT_COMPOSE) { if (ctx->rotation != 90 && ctx->rotation != 270) align_h = 1; max_sc_h = min(SCALER_MAX_HRATIO, 1 << (ffs(sink->width) - 3)); @@ -682,7 +682,7 @@ static void fimc_capture_try_selection(struct fimc_ctx *ctx, rotate ? sink->f_height : sink->f_width); max_h = min_t(u32, FIMC_CAMIF_MAX_HEIGHT, sink->f_height); - if (target == V4L2_SEL_TGT_COMPOSE_ACTIVE) { + if (target == V4L2_SEL_TGT_COMPOSE) { min_w = min_t(u32, max_w, sink->f_width / max_sc_h); min_h = min_t(u32, max_h, sink->f_height / max_sc_v); if (rotate) { @@ -1147,9 +1147,9 @@ static int fimc_cap_g_selection(struct file *file, void *fh, s->r.height = f->o_height; return 0; - case V4L2_SEL_TGT_COMPOSE_ACTIVE: + case V4L2_SEL_TGT_COMPOSE: f = &ctx->d_frame; - case V4L2_SEL_TGT_CROP_ACTIVE: + case V4L2_SEL_TGT_CROP: s->r.left = f->offs_h; s->r.top = f->offs_v; s->r.width = f->width; @@ -1185,9 +1185,9 @@ static int fimc_cap_s_selection(struct file *file, void *fh, if (s->type != V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) return -EINVAL; - if (s->target == V4L2_SEL_TGT_COMPOSE_ACTIVE) + if (s->target == V4L2_SEL_TGT_COMPOSE) f = &ctx->d_frame; - else if (s->target == V4L2_SEL_TGT_CROP_ACTIVE) + else if (s->target == V4L2_SEL_TGT_CROP) f = &ctx->s_frame; else return -EINVAL; @@ -1483,7 +1483,7 @@ static int fimc_subdev_set_selection(struct v4l2_subdev *sd, return -EINVAL; mutex_lock(&fimc->lock); - fimc_capture_try_selection(ctx, r, V4L2_SEL_TGT_CROP_ACTIVE); + fimc_capture_try_selection(ctx, r, V4L2_SEL_TGT_CROP); switch (sel->target) { case V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS: diff --git a/drivers/media/video/s5p-fimc/fimc-lite.c b/drivers/media/video/s5p-fimc/fimc-lite.c index 400d701aef04..52ede56e0758 100644 --- a/drivers/media/video/s5p-fimc/fimc-lite.c +++ b/drivers/media/video/s5p-fimc/fimc-lite.c @@ -871,7 +871,7 @@ static int fimc_lite_g_selection(struct file *file, void *fh, sel->r.height = f->f_height; return 0; - case V4L2_SEL_TGT_COMPOSE_ACTIVE: + case V4L2_SEL_TGT_COMPOSE: sel->r = f->rect; return 0; } @@ -888,7 +888,7 @@ static int fimc_lite_s_selection(struct file *file, void *fh, unsigned long flags; if (sel->type != V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE || - sel->target != V4L2_SEL_TGT_COMPOSE_ACTIVE) + sel->target != V4L2_SEL_TGT_COMPOSE) return -EINVAL; fimc_lite_try_compose(fimc, &rect); diff --git a/drivers/media/video/s5p-jpeg/jpeg-core.c b/drivers/media/video/s5p-jpeg/jpeg-core.c index e40e79b33df6..95f23024b17d 100644 --- a/drivers/media/video/s5p-jpeg/jpeg-core.c +++ b/drivers/media/video/s5p-jpeg/jpeg-core.c @@ -824,10 +824,10 @@ static int s5p_jpeg_g_selection(struct file *file, void *priv, /* For JPEG blob active == default == bounds */ switch (s->target) { - case V4L2_SEL_TGT_CROP_ACTIVE: + case V4L2_SEL_TGT_CROP: case V4L2_SEL_TGT_CROP_BOUNDS: case V4L2_SEL_TGT_CROP_DEFAULT: - case V4L2_SEL_TGT_COMPOSE_ACTIVE: + case V4L2_SEL_TGT_COMPOSE: case V4L2_SEL_TGT_COMPOSE_DEFAULT: s->r.width = ctx->out_q.w; s->r.height = ctx->out_q.h; diff --git a/drivers/media/video/s5p-tv/mixer_video.c b/drivers/media/video/s5p-tv/mixer_video.c index 33fde2a763ec..6c74b05d1f95 100644 --- a/drivers/media/video/s5p-tv/mixer_video.c +++ b/drivers/media/video/s5p-tv/mixer_video.c @@ -367,7 +367,7 @@ static int mxr_g_selection(struct file *file, void *fh, return -EINVAL; switch (s->target) { - case V4L2_SEL_TGT_CROP_ACTIVE: + case V4L2_SEL_TGT_CROP: s->r.left = geo->src.x_offset; s->r.top = geo->src.y_offset; s->r.width = geo->src.width; @@ -380,7 +380,7 @@ static int mxr_g_selection(struct file *file, void *fh, s->r.width = geo->src.full_width; s->r.height = geo->src.full_height; break; - case V4L2_SEL_TGT_COMPOSE_ACTIVE: + case V4L2_SEL_TGT_COMPOSE: case V4L2_SEL_TGT_COMPOSE_PADDED: s->r.left = geo->dst.x_offset; s->r.top = geo->dst.y_offset; @@ -449,11 +449,11 @@ static int mxr_s_selection(struct file *file, void *fh, res.height = geo->dst.full_height; break; - case V4L2_SEL_TGT_CROP_ACTIVE: + case V4L2_SEL_TGT_CROP: target = &geo->src; stage = MXR_GEOMETRY_CROP; break; - case V4L2_SEL_TGT_COMPOSE_ACTIVE: + case V4L2_SEL_TGT_COMPOSE: case V4L2_SEL_TGT_COMPOSE_PADDED: target = &geo->dst; stage = MXR_GEOMETRY_COMPOSE; diff --git a/include/linux/videodev2.h b/include/linux/videodev2.h index a61edb353273..ac1ad33ba3e0 100644 --- a/include/linux/videodev2.h +++ b/include/linux/videodev2.h @@ -767,13 +767,13 @@ struct v4l2_crop { /* Selection targets */ /* Current cropping area */ -#define V4L2_SEL_TGT_CROP_ACTIVE 0x0000 +#define V4L2_SEL_TGT_CROP 0x0000 /* Default cropping area */ #define V4L2_SEL_TGT_CROP_DEFAULT 0x0001 /* Cropping bounds */ #define V4L2_SEL_TGT_CROP_BOUNDS 0x0002 /* Current composing area */ -#define V4L2_SEL_TGT_COMPOSE_ACTIVE 0x0100 +#define V4L2_SEL_TGT_COMPOSE 0x0100 /* Default composing area */ #define V4L2_SEL_TGT_COMPOSE_DEFAULT 0x0101 /* Composing bounds */ @@ -781,6 +781,10 @@ struct v4l2_crop { /* Current composing area plus all padding pixels */ #define V4L2_SEL_TGT_COMPOSE_PADDED 0x0103 +/* Backward compatibility definitions */ +#define V4L2_SEL_TGT_CROP_ACTIVE V4L2_SEL_TGT_CROP +#define V4L2_SEL_TGT_COMPOSE_ACTIVE V4L2_SEL_TGT_COMPOSE + /** * struct v4l2_selection - selection info * @type: buffer type (do not use *_MPLANE types) -- cgit v1.2.3 From 1ec0ed083988ae433305d7f4158fda8c3a1a23b9 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Thu, 17 May 2012 17:50:45 -0300 Subject: [media] v4l: Remove "_ACTUAL" from subdev selection API target definition names The string "_ACTUAL" does not say anything more about the target names. Drop it. V4L2 selection API was changed by "V4L: Remove "_ACTIVE" from the selection target name definitions" by Sylwester Nawrocki. This patch does the same for the V4L2 subdev API. Signed-off-by: Sakari Ailus Acked-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/dev-subdev.xml | 28 +++++++++++----------- .../media/v4l/vidioc-subdev-g-selection.xml | 12 +++++----- drivers/media/video/omap3isp/ispccdc.c | 4 ++-- drivers/media/video/omap3isp/isppreview.c | 4 ++-- drivers/media/video/omap3isp/ispresizer.c | 4 ++-- drivers/media/video/smiapp/smiapp-core.c | 22 ++++++++--------- drivers/media/video/v4l2-subdev.c | 4 ++-- include/linux/v4l2-subdev.h | 9 +++++-- 8 files changed, 46 insertions(+), 41 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index 4afcbbec5eda..e88d5ea8f826 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -289,9 +289,9 @@ &v4l2-rect; by the coordinates of the top left corner and the rectangle size. Both the coordinates and sizes are expressed in pixels. - As for pad formats, drivers store try and active - rectangles for the selection targets of ACTUAL type . + As for pad formats, drivers store try and active rectangles for + the selection targets . On sink pads, cropping is applied relative to the current pad format. The pad format represents the image size as @@ -308,7 +308,7 @@ Scaling support is optional. When supported by a subdev, the crop rectangle on the subdev's sink pad is scaled to the size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL - using V4L2_SUBDEV_SEL_COMPOSE_ACTUAL + using V4L2_SUBDEV_SEL_TGT_COMPOSE selection target on the same pad. If the subdev supports scaling but not composing, the top and left values are not used and must always be set to zero. @@ -333,22 +333,22 @@ Types of selection targets
- ACTUAL targets + Actual targets - ACTUAL targets reflect the actual hardware configuration - at any point of time. There is a BOUNDS target - corresponding to every ACTUAL. + Actual targets (without a postfix) reflect the actual + hardware configuration at any point of time. There is a BOUNDS + target corresponding to every actual target.
BOUNDS targets - BOUNDS targets is the smallest rectangle that contains - all valid ACTUAL rectangles. It may not be possible to set the - ACTUAL rectangle as large as the BOUNDS rectangle, however. - This may be because e.g. a sensor's pixel array is not - rectangular but cross-shaped or round. The maximum size may - also be smaller than the BOUNDS rectangle. + BOUNDS targets is the smallest rectangle that contains all + valid actual rectangles. It may not be possible to set the actual + rectangle as large as the BOUNDS rectangle, however. This may be + because e.g. a sensor's pixel array is not rectangular but + cross-shaped or round. The maximum size may also be smaller than the + BOUNDS rectangle.
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index 208e9f0da3f3..4c44808ab25c 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -72,10 +72,10 @@
Types of selection targets - There are two types of selection targets: actual and bounds. - The ACTUAL targets are the targets which configure the hardware. - The BOUNDS target will return a rectangle that contain all - possible ACTUAL rectangles. + There are two types of selection targets: actual and bounds. The + actual targets are the targets which configure the hardware. The BOUNDS + target will return a rectangle that contain all possible actual + rectangles.
@@ -93,7 +93,7 @@ &cs-def;
- V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL + V4L2_SUBDEV_SEL_TGT_CROP 0x0000 Actual crop. Defines the cropping performed by the processing step. @@ -104,7 +104,7 @@ Bounds of the crop rectangle. - V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL + V4L2_SUBDEV_SEL_TGT_COMPOSE 0x0100 Actual compose rectangle. Used to configure scaling on sink pads and composition on source pads. diff --git a/drivers/media/video/omap3isp/ispccdc.c b/drivers/media/video/omap3isp/ispccdc.c index 7e32331b60fb..f19774f8396a 100644 --- a/drivers/media/video/omap3isp/ispccdc.c +++ b/drivers/media/video/omap3isp/ispccdc.c @@ -2024,7 +2024,7 @@ static int ccdc_get_selection(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh, ccdc_try_crop(ccdc, format, &sel->r); break; - case V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_CROP: sel->r = *__ccdc_get_crop(ccdc, fh, sel->which); break; @@ -2052,7 +2052,7 @@ static int ccdc_set_selection(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh, struct isp_ccdc_device *ccdc = v4l2_get_subdevdata(sd); struct v4l2_mbus_framefmt *format; - if (sel->target != V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL || + if (sel->target != V4L2_SUBDEV_SEL_TGT_CROP || sel->pad != CCDC_PAD_SOURCE_OF) return -EINVAL; diff --git a/drivers/media/video/omap3isp/isppreview.c b/drivers/media/video/omap3isp/isppreview.c index 8a4935ecc655..1086f6a9ff76 100644 --- a/drivers/media/video/omap3isp/isppreview.c +++ b/drivers/media/video/omap3isp/isppreview.c @@ -1960,7 +1960,7 @@ static int preview_get_selection(struct v4l2_subdev *sd, preview_try_crop(prev, format, &sel->r); break; - case V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_CROP: sel->r = *__preview_get_crop(prev, fh, sel->which); break; @@ -1988,7 +1988,7 @@ static int preview_set_selection(struct v4l2_subdev *sd, struct isp_prev_device *prev = v4l2_get_subdevdata(sd); struct v4l2_mbus_framefmt *format; - if (sel->target != V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL || + if (sel->target != V4L2_SUBDEV_SEL_TGT_CROP || sel->pad != PREV_PAD_SINK) return -EINVAL; diff --git a/drivers/media/video/omap3isp/ispresizer.c b/drivers/media/video/omap3isp/ispresizer.c index 14041c9c8643..945665295571 100644 --- a/drivers/media/video/omap3isp/ispresizer.c +++ b/drivers/media/video/omap3isp/ispresizer.c @@ -1259,7 +1259,7 @@ static int resizer_get_selection(struct v4l2_subdev *sd, resizer_calc_ratios(res, &sel->r, format_source, &ratio); break; - case V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_CROP: sel->r = *__resizer_get_crop(res, fh, sel->which); resizer_calc_ratios(res, &sel->r, format_source, &ratio); break; @@ -1293,7 +1293,7 @@ static int resizer_set_selection(struct v4l2_subdev *sd, struct v4l2_mbus_framefmt *format_sink, *format_source; struct resizer_ratio ratio; - if (sel->target != V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL || + if (sel->target != V4L2_SUBDEV_SEL_TGT_CROP || sel->pad != RESZ_PAD_SINK) return -EINVAL; diff --git a/drivers/media/video/smiapp/smiapp-core.c b/drivers/media/video/smiapp/smiapp-core.c index e8c93c89265a..37622bb6c667 100644 --- a/drivers/media/video/smiapp/smiapp-core.c +++ b/drivers/media/video/smiapp/smiapp-core.c @@ -1630,7 +1630,7 @@ static void smiapp_propagate(struct v4l2_subdev *subdev, smiapp_get_crop_compose(subdev, fh, crops, &comp, which); switch (target) { - case V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_CROP: comp->width = crops[SMIAPP_PAD_SINK]->width; comp->height = crops[SMIAPP_PAD_SINK]->height; if (which == V4L2_SUBDEV_FORMAT_ACTIVE) { @@ -1646,7 +1646,7 @@ static void smiapp_propagate(struct v4l2_subdev *subdev, } } /* Fall through */ - case V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_COMPOSE: *crops[SMIAPP_PAD_SRC] = *comp; break; default: @@ -1722,7 +1722,7 @@ static int smiapp_set_format(struct v4l2_subdev *subdev, if (fmt->which == V4L2_SUBDEV_FORMAT_ACTIVE) ssd->sink_fmt = *crops[ssd->sink_pad]; smiapp_propagate(subdev, fh, fmt->which, - V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL); + V4L2_SUBDEV_SEL_TGT_CROP); mutex_unlock(&sensor->mutex); @@ -1957,7 +1957,7 @@ static int smiapp_set_compose(struct v4l2_subdev *subdev, *comp = sel->r; smiapp_propagate(subdev, fh, sel->which, - V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL); + V4L2_SUBDEV_SEL_TGT_COMPOSE); if (sel->which == V4L2_SUBDEV_FORMAT_ACTIVE) return smiapp_update_mode(sensor); @@ -1973,7 +1973,7 @@ static int __smiapp_sel_supported(struct v4l2_subdev *subdev, /* We only implement crop in three places. */ switch (sel->target) { - case V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_CROP: case V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS: if (ssd == sensor->pixel_array && sel->pad == SMIAPP_PA_PAD_SRC) @@ -1987,7 +1987,7 @@ static int __smiapp_sel_supported(struct v4l2_subdev *subdev, == SMIAPP_DIGITAL_CROP_CAPABILITY_INPUT_CROP) return 0; return -EINVAL; - case V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_COMPOSE: case V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS: if (sel->pad == ssd->source_pad) return -EINVAL; @@ -2050,7 +2050,7 @@ static int smiapp_set_crop(struct v4l2_subdev *subdev, if (ssd != sensor->pixel_array && sel->pad == SMIAPP_PAD_SINK) smiapp_propagate(subdev, fh, sel->which, - V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL); + V4L2_SUBDEV_SEL_TGT_CROP); return 0; } @@ -2096,11 +2096,11 @@ static int __smiapp_get_selection(struct v4l2_subdev *subdev, sel->r = *comp; } break; - case V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_CROP: case V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS: sel->r = *crops[sel->pad]; break; - case V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_COMPOSE: sel->r = *comp; break; } @@ -2147,10 +2147,10 @@ static int smiapp_set_selection(struct v4l2_subdev *subdev, sel->r.height); switch (sel->target) { - case V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_CROP: ret = smiapp_set_crop(subdev, fh, sel); break; - case V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL: + case V4L2_SUBDEV_SEL_TGT_COMPOSE: ret = smiapp_set_compose(subdev, fh, sel); break; default: diff --git a/drivers/media/video/v4l2-subdev.c b/drivers/media/video/v4l2-subdev.c index db6e859b93d4..cd86f0c3ec74 100644 --- a/drivers/media/video/v4l2-subdev.c +++ b/drivers/media/video/v4l2-subdev.c @@ -245,7 +245,7 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg) memset(&sel, 0, sizeof(sel)); sel.which = crop->which; sel.pad = crop->pad; - sel.target = V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL; + sel.target = V4L2_SUBDEV_SEL_TGT_CROP; rval = v4l2_subdev_call( sd, pad, get_selection, subdev_fh, &sel); @@ -274,7 +274,7 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg) memset(&sel, 0, sizeof(sel)); sel.which = crop->which; sel.pad = crop->pad; - sel.target = V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL; + sel.target = V4L2_SUBDEV_SEL_TGT_CROP; sel.r = crop->rect; rval = v4l2_subdev_call( diff --git a/include/linux/v4l2-subdev.h b/include/linux/v4l2-subdev.h index 812019ee1e06..3cbe6889fcb5 100644 --- a/include/linux/v4l2-subdev.h +++ b/include/linux/v4l2-subdev.h @@ -128,14 +128,19 @@ struct v4l2_subdev_frame_interval_enum { #define V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG (1 << 2) /* active cropping area */ -#define V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL 0x0000 +#define V4L2_SUBDEV_SEL_TGT_CROP 0x0000 /* cropping bounds */ #define V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS 0x0002 /* current composing area */ -#define V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL 0x0100 +#define V4L2_SUBDEV_SEL_TGT_COMPOSE 0x0100 /* composing bounds */ #define V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS 0x0102 +/* backward compatibility definitions */ +#define V4L2_SUBDEV_SEL_TGT_CROP_ACTUAL \ + V4L2_SUBDEV_SEL_TGT_CROP +#define V4L2_SUBDEV_SEL_TGT_COMPOSE_ACTUAL \ + V4L2_SUBDEV_SEL_TGT_COMPOSE /** * struct v4l2_subdev_selection - selection info -- cgit v1.2.3 From 64b9ce83a446277d3ffdb5e25e9aeb66442da2a9 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Fri, 1 Jun 2012 13:56:53 -0300 Subject: [media] v4l: Common documentation for selection targets Both V4L2 and V4L2 subdev interface have very similar selection APIs with differences foremost related to in-memory and media bus formats. However, the selection targets are the same for both. Most targets are and in the future will likely continue to be more the same than with any differences. Thus it makes sense to unify the documentation of the targets. Signed-off-by: Sakari Ailus Acked-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 9 ++- Documentation/DocBook/media/v4l/dev-subdev.xml | 12 +-- Documentation/DocBook/media/v4l/selection-api.xml | 6 +- .../DocBook/media/v4l/selections-common.xml | 92 ++++++++++++++++++++++ Documentation/DocBook/media/v4l/v4l2.xml | 5 ++ .../DocBook/media/v4l/vidioc-g-selection.xml | 54 ++----------- .../media/v4l/vidioc-subdev-g-selection.xml | 34 +------- 7 files changed, 119 insertions(+), 93 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/selections-common.xml (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index a8b374930405..97b895151bb0 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2377,10 +2377,11 @@ that used it. It was originally scheduled for removal in 2.6.35. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace. - Add selection API for extended control over cropping and -composing. Does not affect the compatibility of current drivers and -applications. See selection API for -details. + Add selection API for extended control over cropping + and composing. Does not affect the compatibility of current + drivers and applications. See selection API for + details. diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index e88d5ea8f826..afeb196adce5 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -276,7 +276,7 @@ -
+
Selections: cropping, scaling and composition Many sub-devices support cropping frames on their input or output @@ -289,9 +289,9 @@ &v4l2-rect; by the coordinates of the top left corner and the rectangle size. Both the coordinates and sizes are expressed in pixels. - As for pad formats, drivers store try and active rectangles for - the selection targets . + As for pad formats, drivers store try and active + rectangles for the selection targets . On sink pads, cropping is applied relative to the current pad format. The pad format represents the image size as @@ -308,7 +308,7 @@ Scaling support is optional. When supported by a subdev, the crop rectangle on the subdev's sink pad is scaled to the size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL - using V4L2_SUBDEV_SEL_TGT_COMPOSE + using V4L2_SEL_TGT_COMPOSE selection target on the same pad. If the subdev supports scaling but not composing, the top and left values are not used and must always be set to zero. @@ -362,7 +362,7 @@ performed by the user: the changes made will be propagated to any subsequent stages. If this behaviour is not desired, the user must set - V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG flag. This + V4L2_SEL_FLAG_KEEP_CONFIG flag. This flag causes no propagation of the changes are allowed in any circumstances. This may also cause the accessed rectangle to be adjusted by the driver, depending on the properties of the diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index ac013e50e0bd..24dec10259d2 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -53,11 +53,11 @@ cropping and composing rectangles have the same size. -For complete list of the available selection targets see table -
+ See for more + information. +
Configuration diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml new file mode 100644 index 000000000000..6728688d28df --- /dev/null +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -0,0 +1,92 @@ +
+ + Selection targets + + While the V4L2 selection + API and V4L2 subdev + selection APIs are very similar, there's one fundamental + difference between the two. On sub-device API, the selection + rectangle refers to the media bus format, and is bound to a + sub-device's pad. On the V4L2 interface the selection rectangles + refer to the in-memory pixel format. + + The precise meaning of the selection targets may thus be + affected on which of the two interfaces they are used. + +
+ Selection target definitions + + + + + + + &cs-def; + + + Target name + id + Definition + Valid for V4L2 + Valid for V4L2 subdev + + + + + V4L2_SEL_TGT_CROP + 0x0000 + Crop rectangle. Defines the cropped area. + Yes + Yes + + + V4L2_SEL_TGT_CROP_DEFAULT + 0x0001 + Suggested cropping rectangle that covers the "whole picture". + Yes + No + + + V4L2_SEL_TGT_CROP_BOUNDS + 0x0002 + Bounds of the crop rectangle. All valid crop + rectangles fit inside the crop bounds rectangle. + + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE + 0x0100 + Compose rectangle. Used to configure scaling + and composition. + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE_DEFAULT + 0x0101 + Suggested composition rectangle that covers the "whole picture". + Yes + No + + + V4L2_SEL_TGT_COMPOSE_BOUNDS + 0x0102 + Bounds of the compose rectangle. All valid compose + rectangles fit inside the compose bounds rectangle. + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE_PADDED + 0x0103 + The active area and all padding pixels that are inserted or + modified by hardware. + Yes + No + + + +
+ diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 008c2d73a484..36bafc48e03b 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -589,6 +589,11 @@ and discussions on the V4L mailing list. &sub-write; + + Common definitions for V4L2 and V4L2 subdev interfaces + &sub-selections-common; + + Video For Linux Two Header File &sub-videodev2-h; diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index 6376e57ff576..c6f83257ecee 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -67,7 +67,7 @@ Do not use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE setting the value of &v4l2-selection; target field to V4L2_SEL_TGT_CROP ( V4L2_SEL_TGT_COMPOSE ). Please refer to table or for additional +linkend="v4l2-selections-common" /> or for additional targets. The flags and reserved fields of &v4l2-selection; are ignored and they must be filled with zeros. The driver fills the rest of the structure or @@ -88,7 +88,7 @@ use multiplanar buffers. Use V4L2_BUF_TYPE_VIDEO_CAPTURE setting the value of &v4l2-selection; target to V4L2_SEL_TGT_CROP ( V4L2_SEL_TGT_COMPOSE ). Please refer to table or for additional +linkend="v4l2-selections-common" /> or for additional targets. The &v4l2-rect; r rectangle need to be set to the desired active area. Field &v4l2-selection; reserved is ignored and must be filled with zeros. The driver may adjust @@ -154,52 +154,8 @@ exist no rectangle that satisfies the constraints. - - - Selection targets. - - &cs-def; - - - V4L2_SEL_TGT_CROP - 0x0000 - The area that is currently cropped by hardware. - - - V4L2_SEL_TGT_CROP_DEFAULT - 0x0001 - Suggested cropping rectangle that covers the "whole picture". - - - V4L2_SEL_TGT_CROP_BOUNDS - 0x0002 - Limits for the cropping rectangle. - - - V4L2_SEL_TGT_COMPOSE - 0x0100 - The area to which data is composed by hardware. - - - V4L2_SEL_TGT_COMPOSE_DEFAULT - 0x0101 - Suggested composing rectangle that covers the "whole picture". - - - V4L2_SEL_TGT_COMPOSE_BOUNDS - 0x0102 - Limits for the composing rectangle. - - - V4L2_SEL_TGT_COMPOSE_PADDED - 0x0103 - The active area and all padding pixels that are inserted or - modified by hardware. - - - -
- + Selection targets are documented in . @@ -253,7 +209,7 @@ exist no rectangle that satisfies the constraints. __u32 target - Used to select between cropping + Used to select between cropping and composing rectangles. diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index 4c44808ab25c..ace147806e48 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -87,36 +87,8 @@ EINVAL. -
- V4L2 subdev selection targets - - &cs-def; - - - V4L2_SUBDEV_SEL_TGT_CROP - 0x0000 - Actual crop. Defines the cropping - performed by the processing step. - - - V4L2_SUBDEV_SEL_TGT_CROP_BOUNDS - 0x0002 - Bounds of the crop rectangle. - - - V4L2_SUBDEV_SEL_TGT_COMPOSE - 0x0100 - Actual compose rectangle. Used to configure scaling - on sink pads and composition on source pads. - - - V4L2_SUBDEV_SEL_TGT_COMPOSE_BOUNDS - 0x0102 - Bounds of the compose rectangle. - - - -
+ Selection targets are documented in . V4L2 subdev selection flags @@ -173,7 +145,7 @@ __u32targetTarget selection rectangle. See - .. + . __u32 -- cgit v1.2.3 From 9fe75aac380bb0399756a14d14f29346a020a647 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Wed, 13 Jun 2012 16:01:10 -0300 Subject: [media] v4l: Unify selection flags documentation As for the selection targets, the selection flags are now the same on V4L2 and V4L2 subdev interfaces. Also document them so. Signed-off-by: Sakari Ailus Acked-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/dev-subdev.xml | 6 +- Documentation/DocBook/media/v4l/selection-api.xml | 6 +- .../DocBook/media/v4l/selections-common.xml | 226 ++++++++++++++------- .../DocBook/media/v4l/vidioc-g-selection.xml | 27 +-- .../media/v4l/vidioc-subdev-g-selection.xml | 39 +--- 5 files changed, 159 insertions(+), 145 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index afeb196adce5..a3d9dd093268 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -323,10 +323,10 @@ The drivers should always use the closest possible rectangle the user requests on all selection targets, unless specifically told otherwise. - V4L2_SUBDEV_SEL_FLAG_SIZE_GE and - V4L2_SUBDEV_SEL_FLAG_SIZE_LE flags may be + V4L2_SEL_FLAG_GE and + V4L2_SEL_FLAG_LE flags may be used to round the image size either up or down. + linkend="v4l2-selection-flags" />
diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index 24dec10259d2..e7ed5077834d 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -55,7 +55,7 @@ cropping and composing rectangles have the same size.
- See for more + See for more information.
@@ -74,7 +74,7 @@ cropping/composing rectangles may have to be aligned, and both the source and the sink may have arbitrary upper and lower size limits. Therefore, as usual, drivers are expected to adjust the requested parameters and return the actual values selected. An application can control the rounding behaviour using constraint flags . +linkend="v4l2-selection-flags"> constraint flags .
@@ -117,7 +117,7 @@ the bounds rectangle. The composing rectangle must lie completely inside bounds rectangle. The driver must adjust the composing rectangle to fit to the bounding limits. Moreover, the driver can perform other adjustments according to hardware limitations. The application can control rounding behaviour using - constraint flags . + constraint flags . For capture devices the default composing rectangle is queried using V4L2_SEL_TGT_COMPOSE_DEFAULT . It is usually equal to the diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml index 6728688d28df..b6618709ee7a 100644 --- a/Documentation/DocBook/media/v4l/selections-common.xml +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -1,6 +1,6 @@
- Selection targets + Common selection definitions While the V4L2 selection API and V4L2 subdev @@ -10,83 +10,155 @@ sub-device's pad. On the V4L2 interface the selection rectangles refer to the in-memory pixel format. - The precise meaning of the selection targets may thus be - affected on which of the two interfaces they are used. + This section defines the common definitions of the + selection interfaces on the two APIs. -
- Selection target definitions - - - - - - - &cs-def; - - - Target name - id - Definition - Valid for V4L2 - Valid for V4L2 subdev - - - - - V4L2_SEL_TGT_CROP - 0x0000 - Crop rectangle. Defines the cropped area. - Yes - Yes - - - V4L2_SEL_TGT_CROP_DEFAULT - 0x0001 - Suggested cropping rectangle that covers the "whole picture". - Yes - No - - - V4L2_SEL_TGT_CROP_BOUNDS - 0x0002 - Bounds of the crop rectangle. All valid crop - rectangles fit inside the crop bounds rectangle. - - Yes - Yes - - - V4L2_SEL_TGT_COMPOSE - 0x0100 - Compose rectangle. Used to configure scaling - and composition. - Yes - Yes - - - V4L2_SEL_TGT_COMPOSE_DEFAULT - 0x0101 - Suggested composition rectangle that covers the "whole picture". - Yes - No - - - V4L2_SEL_TGT_COMPOSE_BOUNDS - 0x0102 - Bounds of the compose rectangle. All valid compose - rectangles fit inside the compose bounds rectangle. - Yes - Yes - - - V4L2_SEL_TGT_COMPOSE_PADDED - 0x0103 - The active area and all padding pixels that are inserted or +
+ + Selection targets + + The precise meaning of the selection targets may be + dependent on which of the two interfaces they are used. + +
+ Selection target definitions + + + + + + + &cs-def; + + + Target name + id + Definition + Valid for V4L2 + Valid for V4L2 subdev + + + + + V4L2_SEL_TGT_CROP + 0x0000 + Crop rectangle. Defines the cropped area. + Yes + Yes + + + V4L2_SEL_TGT_CROP_DEFAULT + 0x0001 + Suggested cropping rectangle that covers the "whole picture". + Yes + No + + + V4L2_SEL_TGT_CROP_BOUNDS + 0x0002 + Bounds of the crop rectangle. All valid crop + rectangles fit inside the crop bounds rectangle. + + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE + 0x0100 + Compose rectangle. Used to configure scaling + and composition. + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE_DEFAULT + 0x0101 + Suggested composition rectangle that covers the "whole picture". + Yes + No + + + V4L2_SEL_TGT_COMPOSE_BOUNDS + 0x0102 + Bounds of the compose rectangle. All valid compose + rectangles fit inside the compose bounds rectangle. + Yes + Yes + + + V4L2_SEL_TGT_COMPOSE_PADDED + 0x0103 + The active area and all padding pixels that are inserted or modified by hardware. - Yes - No + Yes + No + + + +
+ + + +
+ + Selection flags + + + Selection flag definitions + + + + + + + &cs-def; + + + Flag name + id + Definition + Valid for V4L2 + Valid for V4L2 subdev - - -
+ + + + V4L2_SEL_FLAG_GE + (1 << 0) + Suggest the driver it should choose greater or + equal rectangle (in size) than was requested. Albeit the + driver may choose a lesser size, it will only do so due to + hardware limitations. Without this flag (and + V4L2_SEL_FLAG_LE) the + behaviour is to choose the closest possible + rectangle. + Yes + Yes + + + V4L2_SEL_FLAG_LE + (1 << 1) + Suggest the driver it + should choose lesser or equal rectangle (in size) than was + requested. Albeit the driver may choose a greater size, it + will only do so due to hardware limitations. + Yes + Yes + + + V4L2_SEL_FLAG_KEEP_CONFIG + (1 << 2) + The configuration should not be propagated to any + further processing steps. If this flag is not given, the + configuration is propagated inside the subdevice to all + further processing steps. + No + Yes + + + + + +
+ diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index c6f83257ecee..f76d8a6d9b92 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -154,32 +154,9 @@ exist no rectangle that satisfies the constraints. - Selection targets are documented in Selection targets and flags are documented in . - - - Selection constraint flags - - &cs-def; - - - V4L2_SEL_FLAG_GE - 0x00000001 - Indicates that the adjusted rectangle must contain the original - &v4l2-selection; r rectangle. - - - V4L2_SEL_FLAG_LE - 0x00000002 - Indicates that the adjusted rectangle must be inside the original - &v4l2-rect; r rectangle. - - - -
- -
Size adjustments with constraint flags. @@ -216,7 +193,7 @@ exist no rectangle that satisfies the constraints. __u32 flags Flags controlling the selection rectangle adjustments, refer to - selection flags. + selection flags. &v4l2-rect; diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index ace147806e48..f33cc814a01d 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -87,44 +87,9 @@ EINVAL.
- Selection targets are documented in Selection targets and flags are documented in . - - V4L2 subdev selection flags - - &cs-def; - - - V4L2_SUBDEV_SEL_FLAG_SIZE_GE - (1 << 0) Suggest the driver it - should choose greater or equal rectangle (in size) than - was requested. Albeit the driver may choose a lesser size, - it will only do so due to hardware limitations. Without - this flag (and - V4L2_SUBDEV_SEL_FLAG_SIZE_LE) the - behaviour is to choose the closest possible - rectangle. - - - V4L2_SUBDEV_SEL_FLAG_SIZE_LE - (1 << 1) Suggest the driver it - should choose lesser or equal rectangle (in size) than was - requested. Albeit the driver may choose a greater size, it - will only do so due to hardware limitations. - - - V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG - (1 << 2) - The configuration should not be propagated to any - further processing steps. If this flag is not given, the - configuration is propagated inside the subdevice to all - further processing steps. - - - -
- struct <structname>v4l2_subdev_selection</structname> @@ -151,7 +116,7 @@ __u32 flags Flags. See - . + . &v4l2-rect; -- cgit v1.2.3 From 6889d5ced744cb8a5a96d359e8c3bc4e62bdc36b Mon Sep 17 00:00:00 2001 From: Sylwester Nawrocki Date: Mon, 25 Jun 2012 16:14:41 -0300 Subject: [media] Feature removal: V4L2 selections API target and flag definitions After unification of the V4L2 and V4L2 subdev selection targets and flags the old flags are no longer required. Thus they can be removed. However, as the API is present in a kernel release, this must go through the feature removal process. Signed-off-by: Sylwester Nawrocki Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/feature-removal-schedule.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'Documentation') diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 09701afc031a..b99803066b7b 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -558,3 +558,21 @@ Why: The V4L2_CID_VCENTER, V4L2_CID_HCENTER controls have been deprecated There are newer controls (V4L2_CID_PAN*, V4L2_CID_TILT*) that provide similar functionality. Who: Sylwester Nawrocki + +---------------------------- + +What: V4L2 selections API target rectangle and flags unification, the + following definitions will be removed: V4L2_SEL_TGT_CROP_ACTIVE, + V4L2_SEL_TGT_COMPOSE_ACTIVE, V4L2_SUBDEV_SEL_*, V4L2_SUBDEV_SEL_FLAG_* + in favor of common V4L2_SEL_TGT_* and V4L2_SEL_FLAG_* definitions. + For more details see include/linux/v4l2-common.h. +When: 3.8 +Why: The regular V4L2 selections and the subdev selection API originally + defined distinct names for the target rectangles and flags - V4L2_SEL_* + and V4L2_SUBDEV_SEL_*. Although, it turned out that the meaning of these + target rectangles is virtually identical and the APIs were consolidated + to use single set of names - V4L2_SEL_*. This didn't involve any ABI + changes. Alias definitions were created for the original ones to avoid + any instabilities in the user space interface. After few cycles these + backward compatibility definitions will be removed. +Who: Sylwester Nawrocki -- cgit v1.2.3 From 9a70d980d038e27828db92cef235fabfb618c77d Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Fri, 15 Jun 2012 10:22:25 -0300 Subject: [media] v4l: Correct conflicting V4L2 subdev selection API documentation The API reference documents that the KEEP_CONFIG flag tells the configuration should not be propagated by the driver whereas the interface documentation (dev-subdev.xml) prohibited any changes to the rest of the pipeline. Resolve the conflict by changing the API reference to disallow changes. Signed-off-by: Sakari Ailus Acked-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/selections-common.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml index b6618709ee7a..7502f784b8cc 100644 --- a/Documentation/DocBook/media/v4l/selections-common.xml +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -148,7 +148,7 @@ V4L2_SEL_FLAG_KEEP_CONFIG (1 << 2) - The configuration should not be propagated to any + The configuration must not be propagated to any further processing steps. If this flag is not given, the configuration is propagated inside the subdevice to all further processing steps. -- cgit v1.2.3