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/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index 765549ff8a7..7cf3116c2cc 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/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml index 69c178a4d20..40e58a42eb2 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 62a1aa200a3..95d5371c170 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 407dfceb71f..f4db44d0d95 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/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index 4101aeb5654..b91d25313b6 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/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index 7c49facecd2..1078e45f189 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 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 +++------ 3 files changed, 20 insertions(+), 20 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index ea42ef82494..a8b37493040 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 fd6aca2922b..1885cc0755c 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 9caa49af580..77ff5be0809 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 -- 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/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index a2474ecb574..5e73b1c8d09 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 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 +++++++------- 2 files changed, 20 insertions(+), 19 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index b299e477935..ac013e50e0b 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 bb04eff75f4..6376e57ff57 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. -- 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 +++++----- 2 files changed, 20 insertions(+), 20 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index 4afcbbec5ed..e88d5ea8f82 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 208e9f0da3f..4c44808ab25 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. -- 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/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index a8b37493040..97b895151bb 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 e88d5ea8f82..afeb196adce 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 ac013e50e0b..24dec10259d 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 00000000000..6728688d28d --- /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 008c2d73a48..36bafc48e03 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 6376e57ff57..c6f83257ece 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 4c44808ab25..ace147806e4 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/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index afeb196adce..a3d9dd09326 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 24dec10259d..e7ed5077834 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 6728688d28d..b6618709ee7 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 c6f83257ece..f76d8a6d9b9 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 ace147806e4..f33cc814a01 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 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/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml index b6618709ee7..7502f784b8c 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 From a2f8b84fed92d56c3891d03f090601c53766b118 Mon Sep 17 00:00:00 2001 From: Hans de Goede Date: Sun, 1 Jul 2012 11:26:13 -0300 Subject: [media] v4l2-ctrls: Teach v4l2-ctrls that V4L2_CID_AUTOBRIGHTNESS is a boolean And document V4L2_CID_AUTOBRIGHTNESS. Signed-off-by: Hans de Goede Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/controls.xml | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 43ca749fc5e..6c27f7b0aca 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -372,6 +372,11 @@ minimum value disables backlight compensation. Cr component, bits [15:8] as Cb component and bits [31:16] must be zero. + + V4L2_CID_AUTOBRIGHTNESS + boolean + Enable Automatic Brightness. + V4L2_CID_ROTATE integer -- cgit v1.2.3 From f0476a83d61a8004eb535a0b65721ca405421fe8 Mon Sep 17 00:00:00 2001 From: Sylwester Nawrocki Date: Thu, 26 Jul 2012 09:30:00 -0300 Subject: [media] V4L: Add capability flags for memory-to-memory devices This patch adds new V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE capability flags that are intended to be used for memory-to-memory (M2M) devices, instead of ORed V4L2_CAP_VIDEO_CAPTURE and V4L2_CAP_VIDEO_OUTPUT. V4L2_CAP_VIDEO_M2M flag is added at the drivers, CAPTURE and OUTPUT capability flags are left untouched and will be removed in future, after a transition period required for existing applications to be adapted to check only for V4L2_CAP_VIDEO_M2M. Signed-off-by: Sylwester Nawrocki Signed-off-by: Kyungmin Park Acked-by: Kamil Debski Acked-by: Andrzej Pietrasiewicz Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 9 +++++++++ Documentation/DocBook/media/v4l/vidioc-querycap.xml | 13 +++++++++++++ 2 files changed, 22 insertions(+) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 97b895151bb..4559a6f8a5f 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2471,6 +2471,15 @@ that used it. It was originally scheduled for removal in 2.6.35. +
+ V4L2 in Linux 3.6 + + + Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE capabilities. + + +
+
Relation of V4L2 to other Linux multimedia APIs diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml index 4643505cd4c..f33dd746b66 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml @@ -191,6 +191,19 @@ linkend="output">Video Output interface. multi-planar API through the Video Output interface. + + V4L2_CAP_VIDEO_M2M + 0x00004000 + The device supports the single-planar API through the + Video Memory-To-Memory interface. + + + V4L2_CAP_VIDEO_M2M_MPLANE + 0x00008000 + The device supports the + multi-planar API through the + Video Memory-To-Memory interface. + V4L2_CAP_VIDEO_OVERLAY 0x00000004 -- cgit v1.2.3 From 16d18b16ace670641de74e6fe8005029b4057559 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 11 Jul 2012 07:48:52 -0300 Subject: [media] Fix DV_TIMINGS_CAP documentation This patch fixes the DV_TIMINGS_CAP documentation: part of it was copy-and-paste from the ENUM_DV_TIMINGS documentation. Regards, Hans Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml index 6673ce58205..cd7720d404e 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml @@ -54,15 +54,9 @@ interface and may change in the future. - To query the available timings, applications initialize the -index field and zero the reserved array of &v4l2-dv-timings-cap; -and call the VIDIOC_DV_TIMINGS_CAP ioctl with a pointer to this -structure. Drivers fill the rest of the structure or return an -&EINVAL; when the index is out of bounds. To enumerate all supported DV timings, -applications shall begin at index zero, incrementing by one until the -driver returns EINVAL. Note that drivers may enumerate a -different set of DV timings after switching the video input or -output. + To query the capabilities of the DV receiver/transmitter applications can call +this ioctl and the driver will fill in the structure. Note that drivers may return +different values after switching the video input or output.
struct <structname>v4l2_bt_timings_cap</structname> @@ -115,7 +109,7 @@ output. __u32 reserved[16] - + Reserved for future extensions. Drivers must set the array to zero. -- cgit v1.2.3 From b67a39e4b6850c0346c0b809886632d4cd2fed7d Mon Sep 17 00:00:00 2001 From: Nicolas THERY Date: Thu, 12 Jul 2012 12:12:12 -0300 Subject: [media] v4l: DocBook: fix version number typo Signed-off-by: Nicolas Thery Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 4559a6f8a5f..c9c7d1ca8d6 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2460,7 +2460,7 @@ that used it. It was originally scheduled for removal in 2.6.35.
- V4L2 in Linux 3.5 + V4L2 in Linux 3.6 Replaced input in -- cgit v1.2.3 From 50121317c2035c017d62c8ec24f84b91ef8d4de2 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Thu, 5 Jul 2012 06:54:38 -0300 Subject: [media] v4l2 spec: add VIDIOC_ENUM_FREQ_BANDS documentation Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 12 ++ Documentation/DocBook/media/v4l/v4l2.xml | 6 + .../DocBook/media/v4l/vidioc-enum-freq-bands.xml | 179 +++++++++++++++++++++ .../DocBook/media/v4l/vidioc-g-frequency.xml | 7 +- Documentation/DocBook/media/v4l/vidioc-g-tuner.xml | 26 ++- 5 files changed, 221 insertions(+), 9 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index c9c7d1ca8d6..faa0fd14666 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2480,6 +2480,15 @@ that used it. It was originally scheduled for removal in 2.6.35.
+
+ V4L2 in Linux 3.6 + + + Added support for frequency band enumerations: &VIDIOC-ENUM-FREQ-BANDS;. + + +
+
Relation of V4L2 to other Linux multimedia APIs @@ -2609,6 +2618,9 @@ ioctls. V4L2_CID_AUTO_FOCUS_AREA control. + + Support for frequency band enumeration: &VIDIOC-ENUM-FREQ-BANDS; ioctl. +
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 36bafc48e03..eee6908c749 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -140,6 +140,11 @@ structs, ioctls) must be noted in more detail in the history chapter applications. --> + 3.6 + 2012-07-02 + hv + Added VIDIOC_ENUM_FREQ_BANDS. + 3.5 2012-05-07 sa, sn @@ -534,6 +539,7 @@ and discussions on the V4L mailing list. &sub-enum-fmt; &sub-enum-framesizes; &sub-enum-frameintervals; + &sub-enum-freq-bands; &sub-enuminput; &sub-enumoutput; &sub-enumstd; diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml b/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml new file mode 100644 index 00000000000..6541ba0175e --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml @@ -0,0 +1,179 @@ + + + ioctl VIDIOC_ENUM_FREQ_BANDS + &manvol; + + + + VIDIOC_ENUM_FREQ_BANDS + Enumerate supported frequency bands + + + + + + int ioctl + int fd + int request + struct v4l2_frequency_band +*argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_ENUM_FREQ_BANDS + + + + argp + + + + + + + + + Description + + + Experimental + This is an experimental + interface and may change in the future. + + + Enumerates the frequency bands that a tuner or modulator supports. +To do this applications initialize the tuner, +type and index fields, +and zero out the reserved array of a &v4l2-frequency-band; and +call the VIDIOC_ENUM_FREQ_BANDS ioctl with a pointer +to this structure. + + This ioctl is supported if the V4L2_TUNER_CAP_FREQ_BANDS capability + of the corresponding tuner/modulator is set. + +
+ struct <structname>v4l2_frequency_band</structname> + + &cs-str; + + + __u32 + tuner + The tuner or modulator index number. This is the +same value as in the &v4l2-input; tuner +field and the &v4l2-tuner; index field, or +the &v4l2-output; modulator field and the +&v4l2-modulator; index field. + + + __u32 + type + The tuner type. This is the same value as in the +&v4l2-tuner; type field. The type must be set +to V4L2_TUNER_RADIO for /dev/radioX +device nodes, and to V4L2_TUNER_ANALOG_TV +for all others. Set this field to V4L2_TUNER_RADIO for +modulators (currently only radio modulators are supported). +See + + + __u32 + index + Identifies the frequency band, set by the application. + + + __u32 + capability + The tuner/modulator capability flags for +this frequency band, see . The V4L2_TUNER_CAP_LOW +capability must be the same for all frequency bands of the selected tuner/modulator. +So either all bands have that capability set, or none of them have that capability. + + + __u32 + rangelow + The lowest tunable frequency in +units of 62.5 kHz, or if the capability +flag V4L2_TUNER_CAP_LOW is set, in units of 62.5 +Hz, for this frequency band. + + + __u32 + rangehigh + The highest tunable frequency in +units of 62.5 kHz, or if the capability +flag V4L2_TUNER_CAP_LOW is set, in units of 62.5 +Hz, for this frequency band. + + + __u32 + modulation + The supported modulation systems of this frequency band. + See . Note that currently only one + modulation system per frequency band is supported. More work will need to + be done if multiple modulation systems are possible. Contact the + linux-media mailing list (&v4l-ml;) if you need that functionality. + + + __u32 + reserved[9] + Reserved for future extensions. Applications and drivers + must set the array to zero. + + + +
+ + + Band Modulation Systems + + &cs-def; + + + V4L2_BAND_MODULATION_VSB + 0x02 + Vestigial Sideband modulation, used for analog TV. + + + V4L2_BAND_MODULATION_FM + 0x04 + Frequency Modulation, commonly used for analog radio. + + + V4L2_BAND_MODULATION_AM + 0x08 + Amplitude Modulation, commonly used for analog radio. + + + +
+ + + + &return-value; + + + + EINVAL + + The tuner or index +is out of bounds or the type field is wrong. + + + + + diff --git a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml index 40e58a42eb2..c7a1c462e72 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml @@ -98,11 +98,12 @@ the &v4l2-output; modulator field and the __u32 type The tuner type. This is the same value as in the -&v4l2-tuner; type field. See The type must be set +&v4l2-tuner; type field. The type must be set to V4L2_TUNER_RADIO for /dev/radioX device nodes, and to V4L2_TUNER_ANALOG_TV -for all others. The field is not applicable to modulators, &ie; ignored -by drivers. See +for all others. Set this field to V4L2_TUNER_RADIO for +modulators (currently only radio modulators are supported). +See __u32 diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index 95d5371c170..72039512790 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -119,10 +119,14 @@ field is not quite clear.--> . Audio flags indicate the ability 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, -V4L2_TUNER_CAP_STEREO and -V4L2_TUNER_CAP_RDS flags can be set. +the structure refers to a radio tuner the +V4L2_TUNER_CAP_LANG1, +V4L2_TUNER_CAP_LANG2 and +V4L2_TUNER_CAP_NORM flags can't be used. +If multiple frequency bands are supported, then +capability is the union of all +capability> fields of each &v4l2-frequency-band;. + __u32 @@ -130,7 +134,9 @@ the structure refers to a radio tuner only the The lowest tunable frequency in units of 62.5 kHz, or if the capability flag V4L2_TUNER_CAP_LOW is set, in units of 62.5 -Hz. +Hz. If multiple frequency bands are supported, then +rangelow is the lowest frequency +of all the frequency bands. __u32 @@ -138,7 +144,9 @@ Hz. The highest tunable frequency in units of 62.5 kHz, or if the capability flag V4L2_TUNER_CAP_LOW is set, in units of 62.5 -Hz. +Hz. If multiple frequency bands are supported, then +rangehigh is the highest frequency +of all the frequency bands. __u32 @@ -340,6 +348,12 @@ radio tuners. 0x0200 The RDS data is parsed by the hardware and set via controls. + + V4L2_TUNER_CAP_FREQ_BANDS + 0x0400 + The &VIDIOC-ENUM-FREQ-BANDS; ioctl can be used to enumerate + the available frequency bands. + -- cgit v1.2.3 From e0a9b1770bac048171961625875aaf15118a7ae9 Mon Sep 17 00:00:00 2001 From: Hans de Goede Date: Thu, 12 Jul 2012 16:55:45 -0300 Subject: [media] v4l2: Add rangelow and rangehigh fields to the v4l2_hw_freq_seek struct To allow apps to limit a hw-freq-seek to a specific band, for further info see the documentation this patch adds for these new fields. Signed-off-by: Hans de Goede Signed-off-by: Mauro Carvalho Chehab --- .../DocBook/media/v4l/vidioc-s-hw-freq-seek.xml | 50 ++++++++++++++++++---- 1 file changed, 42 insertions(+), 8 deletions(-) (limited to 'Documentation/DocBook/media/v4l') 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 f4db44d0d95..3dd1bec6d3c 100644 --- a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml +++ b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml @@ -52,11 +52,23 @@ Start a hardware frequency seek from the current frequency. To do this applications initialize the tuner, type, seek_upward, -spacing and -wrap_around fields, and zero out the -reserved array of a &v4l2-hw-freq-seek; and -call the VIDIOC_S_HW_FREQ_SEEK ioctl with a pointer -to this structure. +wrap_around, spacing, +rangelow and rangehigh +fields, and zero out the reserved array of a +&v4l2-hw-freq-seek; and call the VIDIOC_S_HW_FREQ_SEEK +ioctl with a pointer to this structure. + + The rangelow and +rangehigh fields can be set to a non-zero value to +tell the driver to search a specific band. If the &v4l2-tuner; +capability field has the +V4L2_TUNER_CAP_HWSEEK_PROG_LIM flag set, these values +must fall within one of the bands returned by &VIDIOC-ENUM-FREQ-BANDS;. If +the V4L2_TUNER_CAP_HWSEEK_PROG_LIM flag is not set, +then these values must exactly match those of one of the bands returned by +&VIDIOC-ENUM-FREQ-BANDS;. If the current frequency of the tuner does not fall +within the selected band it will be clamped to fit in the band before the +seek is started. If an error is returned, then the original frequency will be restored. @@ -102,7 +114,27 @@ field and the &v4l2-tuner; index field. __u32 - reserved[7] + rangelow + If non-zero, the lowest tunable frequency of the band to +search in units of 62.5 kHz, or if the &v4l2-tuner; +capability field has the +V4L2_TUNER_CAP_LOW flag set, in units of 62.5 Hz. +If rangelow is zero a reasonable default value +is used. + + + __u32 + rangehigh + If non-zero, the highest tunable frequency of the band to +search in units of 62.5 kHz, or if the &v4l2-tuner; +capability field has the +V4L2_TUNER_CAP_LOW flag set, in units of 62.5 Hz. +If rangehigh is zero a reasonable default value +is used. + + + __u32 + reserved[5] Reserved for future extensions. Applications must set the array to zero. @@ -119,8 +151,10 @@ field and the &v4l2-tuner; index field. EINVAL The tuner index is out of -bounds, the wrap_around value is not supported or the value in the type field is -wrong. +bounds, the wrap_around value is not supported or +one of the values in the type, +rangelow or rangehigh +fields is wrong. -- cgit v1.2.3 From 6992c0807517b5736c80983c4881d3f9ae3ab20f Mon Sep 17 00:00:00 2001 From: Nicolas THERY Date: Wed, 18 Jul 2012 11:41:36 -0300 Subject: [media] v4l: DocBook: VIDIOC_CREATE_BUFS: add hyperlink Signed-off-by: Nicolas Thery Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-create-bufs.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index 5e73b1c8d09..a8cda1acacd 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -64,7 +64,7 @@ different sizes. To allocate device buffers applications initialize relevant fields of the v4l2_create_buffers structure. They set the type field in the -v4l2_format structure, embedded in this +&v4l2-format; structure, embedded in this structure, to the respective stream or buffer type. count must be set to the number of required buffers. memory specifies the required I/O method. The @@ -114,7 +114,7 @@ information. /> - struct v4l2_format + &v4l2-format; format Filled in by the application, preserved by the driver. -- cgit v1.2.3 From 467548aa9fe91c35fc908a844129a788aec6a2d0 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 3 Aug 2012 11:16:29 -0300 Subject: [media] DocBook: Remove a spurious character Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-g-tuner.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index 72039512790..701138f1209 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -125,7 +125,7 @@ the structure refers to a radio tuner the V4L2_TUNER_CAP_NORM flags can't be used. If multiple frequency bands are supported, then capability is the union of all -capability> fields of each &v4l2-frequency-band;. +capability fields of each &v4l2-frequency-band;. -- cgit v1.2.3 From 7a44e3763d7ac90524961212ef0033c32403c3eb Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Thu, 9 Aug 2012 04:40:57 -0300 Subject: [media] Remove documentation chunk of non-existent V4L2_CID_AUTO_FOCUS_AREA Remove documentation chunk of non-existent V4L2_CID_AUTO_FOCUS_AREA control. It fixes following build error: Error: no ID for constraint linkend: v4l2-auto-focus-area. Signed-off-by: Sylwester Nawrocki Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 4 ---- 1 file changed, 4 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index faa0fd14666..843ec47ea6b 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2614,10 +2614,6 @@ ioctls. Sub-device selection API: &VIDIOC-SUBDEV-G-SELECTION; and &VIDIOC-SUBDEV-S-SELECTION; ioctls. - - - V4L2_CID_AUTO_FOCUS_AREA control. - Support for frequency band enumeration: &VIDIOC-ENUM-FREQ-BANDS; ioctl. -- cgit v1.2.3 From 571d19c39714bdea4fbffd6e03f9ff5646ac571b Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Thu, 9 Aug 2012 06:04:43 -0300 Subject: [media] DocBook: various version/copyright year updates - update 2011 to 2012 for copyrights - update V4L2 spec version to 3.6 - update the intro to also refer to part four: the Media Controller - fix an incorrect revision section - fix an incorrect 3.6 kernel changes section Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 12 ------------ Documentation/DocBook/media/v4l/v4l2.xml | 14 +++++++------- 2 files changed, 7 insertions(+), 19 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 843ec47ea6b..98e8d088b3a 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2468,21 +2468,9 @@ that used it. It was originally scheduled for removal in 2.6.35. reserved2 and removed V4L2_BUF_FLAG_INPUT. - - - -
- V4L2 in Linux 3.6 - Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE capabilities. - -
- -
- V4L2 in Linux 3.6 - Added support for frequency band enumerations: &VIDIOC-ENUM-FREQ-BANDS;. diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index eee6908c749..0292ed10688 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -145,9 +145,12 @@ applications. --> hv Added VIDIOC_ENUM_FREQ_BANDS. + + + 3.5 2012-05-07 - sa, sn + sa, sn, hv Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API. Improved the description of V4L2_CID_COLORFX control, added V4L2_CID_COLORFX_CBCR control. @@ -158,11 +161,8 @@ applications. --> V4L2_CID_3A_LOCK, V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. - - 2012-05-01 - hv - Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and - VIDIOC_DV_TIMINGS_CAP. + Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and + VIDIOC_DV_TIMINGS_CAP. @@ -472,7 +472,7 @@ and discussions on the V4L mailing list. Video for Linux Two API Specification - Revision 3.5 + Revision 3.6 &sub-common; -- cgit v1.2.3 From 34affc6a5c75ce6523d7282d56c51bb36c183da7 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Tue, 14 Aug 2012 06:10:02 -0300 Subject: [media] DocBook: update RDS references to the latest RDS standards Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/biblio.xml | 12 ++++++------ Documentation/DocBook/media/v4l/controls.xml | 6 +++--- Documentation/DocBook/media/v4l/dev-rds.xml | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index 1078e45f189..18b6fc9ff58 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -178,23 +178,23 @@ Signal - NTSC for Studio Applications" 1125-Line High-Definition Production" - - EN 50067 + + IEC 62106 - European Committee for Electrotechnical Standardization -(http://www.cenelec.eu) + International Electrotechnical Commission +(http://www.iec.ch) 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 + NRSC-4-B National Radio Systems Committee (http://www.nrscstandards.org) - NRSC-4: United States RBDS Standard + NRSC-4-B: United States RBDS Standard diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index b0964fb4e83..41cd801f0f0 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -3505,7 +3505,7 @@ This encodes up to 31 pre-defined programme types. 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, +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 @@ -3519,7 +3519,7 @@ with steps of 8 characters. The result is it must always contain a string with s 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 +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. @@ -3650,7 +3650,7 @@ manually or automatically if set to zero. Unit, range and step are driver-specif For more details about RDS specification, refer to - document, from CENELEC. + document, from CENELEC.
diff --git a/Documentation/DocBook/media/v4l/dev-rds.xml b/Documentation/DocBook/media/v4l/dev-rds.xml index 38883a419e6..be2f3373732 100644 --- a/Documentation/DocBook/media/v4l/dev-rds.xml +++ b/Documentation/DocBook/media/v4l/dev-rds.xml @@ -6,7 +6,7 @@ information, on an inaudible audio subcarrier of a radio program. This interface is aimed at devices capable of receiving and/or transmitting RDS information. - For more information see the core RDS standard + 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 -- cgit v1.2.3 From 071408b6dcc1cb29150699621e13b0ddb81e3cf1 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Tue, 14 Aug 2012 06:10:01 -0300 Subject: [media] DocBook validation fixes More validation fixes as reported by xmllint. There are still three xmllint errors after this remaining regarding SVG file support. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/controls.xml | 447 ++++++++++----------- Documentation/DocBook/media/v4l/dev-subdev.xml | 20 +- .../DocBook/media/v4l/pixfmt-srggb10dpcm8.xml | 3 +- Documentation/DocBook/media/v4l/selection-api.xml | 22 +- .../DocBook/media/v4l/vidioc-g-selection.xml | 9 +- Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 2 + .../media/v4l/vidioc-subdev-g-selection.xml | 8 +- 7 files changed, 255 insertions(+), 256 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 41cd801f0f0..93b9c6872e5 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -3717,232 +3717,231 @@ interface and may change in the future. use case involving camera or individually. -
+ + Flash Control IDs + + + + + + + + + + + ID + Type + Description + + + + + + V4L2_CID_FLASH_CLASS + class + + + The FLASH class descriptor. + + + V4L2_CID_FLASH_LED_MODE + menu + + + Defines the mode of the flash LED, + the high-power white LED attached to the flash controller. + Setting this control may not be possible in presence of + some faults. See V4L2_CID_FLASH_FAULT. + + + + + + V4L2_FLASH_LED_MODE_NONE + Off. + + + V4L2_FLASH_LED_MODE_FLASH + Flash mode. + + + V4L2_FLASH_LED_MODE_TORCH + Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY. + + + + + + V4L2_CID_FLASH_STROBE_SOURCE + menu + + Defines the source of the flash LED + strobe. + + + + + + V4L2_FLASH_STROBE_SOURCE_SOFTWARE + The flash strobe is triggered by using + the V4L2_CID_FLASH_STROBE control. + + + V4L2_FLASH_STROBE_SOURCE_EXTERNAL + The flash strobe is triggered by an + external source. Typically this is a sensor, + which makes it possible to synchronises the + flash strobe start to exposure start. + + + + + + V4L2_CID_FLASH_STROBE + button + + + Strobe flash. Valid when + V4L2_CID_FLASH_LED_MODE is set to + V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE + is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this + control may not be possible in presence of some faults. + See V4L2_CID_FLASH_FAULT. + + + V4L2_CID_FLASH_STROBE_STOP + button + + Stop flash strobe immediately. + + + V4L2_CID_FLASH_STROBE_STATUS + boolean + + + Strobe status: whether the flash + is strobing at the moment or not. This is a read-only + control. + + + V4L2_CID_FLASH_TIMEOUT + integer + + + Hardware timeout for flash. The + flash strobe is stopped after this period of time has + passed from the start of the strobe. + + + V4L2_CID_FLASH_INTENSITY + integer + + + Intensity of the flash strobe when + the flash LED is in flash mode + (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps + (mA) if possible. + + + V4L2_CID_FLASH_TORCH_INTENSITY + integer + + + Intensity of the flash LED in + torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be + milliamps (mA) if possible. Setting this control may not + be possible in presence of some faults. See + V4L2_CID_FLASH_FAULT. + + + V4L2_CID_FLASH_INDICATOR_INTENSITY + integer + + + Intensity of the indicator LED. + The indicator LED may be fully independent of the flash + LED. The unit should be microamps (uA) if possible. + + + V4L2_CID_FLASH_FAULT + bitmask + + + Faults related to the flash. The + faults tell about specific problems in the flash chip + itself or the LEDs attached to it. Faults may prevent + further use of some of the flash controls. In particular, + V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE + if the fault affects the flash LED. Exactly which faults + have such an effect is chip dependent. Reading the faults + resets the control and returns the chip to a usable state + if possible. + + + + + + V4L2_FLASH_FAULT_OVER_VOLTAGE + Flash controller voltage to the flash LED + has exceeded the limit specific to the flash + controller. + + + V4L2_FLASH_FAULT_TIMEOUT + The flash strobe was still on when + the timeout set by the user --- + V4L2_CID_FLASH_TIMEOUT control --- has expired. + Not all flash controllers may set this in all + such conditions. + + + V4L2_FLASH_FAULT_OVER_TEMPERATURE + The flash controller has overheated. + + + V4L2_FLASH_FAULT_SHORT_CIRCUIT + The short circuit protection of the flash + controller has been triggered. + + + V4L2_FLASH_FAULT_OVER_CURRENT + Current in the LED power supply has exceeded the limit + specific to the flash controller. + + + V4L2_FLASH_FAULT_INDICATOR + The flash controller has detected a short or open + circuit condition on the indicator LED. + + + + + + V4L2_CID_FLASH_CHARGE + boolean + + Enable or disable charging of the xenon + flash capacitor. + + + V4L2_CID_FLASH_READY + boolean + + + Is the flash ready to strobe? + Xenon flashes require their capacitors charged before + strobing. LED flashes often require a cooldown period + after strobe during which another strobe will not be + possible. This is a read-only control. + + + + +
+ - - - Flash Control IDs - - - - - - - - - - - ID - Type - Description - - - - - - V4L2_CID_FLASH_CLASS - class - - - The FLASH class descriptor. - - - V4L2_CID_FLASH_LED_MODE - menu - - - Defines the mode of the flash LED, - the high-power white LED attached to the flash controller. - Setting this control may not be possible in presence of - some faults. See V4L2_CID_FLASH_FAULT. - - - - - - V4L2_FLASH_LED_MODE_NONE - Off. - - - V4L2_FLASH_LED_MODE_FLASH - Flash mode. - - - V4L2_FLASH_LED_MODE_TORCH - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY. - - - - - - V4L2_CID_FLASH_STROBE_SOURCE - menu - - Defines the source of the flash LED - strobe. - - - - - - V4L2_FLASH_STROBE_SOURCE_SOFTWARE - The flash strobe is triggered by using - the V4L2_CID_FLASH_STROBE control. - - - V4L2_FLASH_STROBE_SOURCE_EXTERNAL - The flash strobe is triggered by an - external source. Typically this is a sensor, - which makes it possible to synchronises the - flash strobe start to exposure start. - - - - - - V4L2_CID_FLASH_STROBE - button - - - Strobe flash. Valid when - V4L2_CID_FLASH_LED_MODE is set to - V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE - is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this - control may not be possible in presence of some faults. - See V4L2_CID_FLASH_FAULT. - - - V4L2_CID_FLASH_STROBE_STOP - button - - Stop flash strobe immediately. - - - V4L2_CID_FLASH_STROBE_STATUS - boolean - - - Strobe status: whether the flash - is strobing at the moment or not. This is a read-only - control. - - - V4L2_CID_FLASH_TIMEOUT - integer - - - Hardware timeout for flash. The - flash strobe is stopped after this period of time has - passed from the start of the strobe. - - - V4L2_CID_FLASH_INTENSITY - integer - - - Intensity of the flash strobe when - the flash LED is in flash mode - (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps - (mA) if possible. - - - V4L2_CID_FLASH_TORCH_INTENSITY - integer - - - Intensity of the flash LED in - torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be - milliamps (mA) if possible. Setting this control may not - be possible in presence of some faults. See - V4L2_CID_FLASH_FAULT. - - - V4L2_CID_FLASH_INDICATOR_INTENSITY - integer - - - Intensity of the indicator LED. - The indicator LED may be fully independent of the flash - LED. The unit should be microamps (uA) if possible. - - - V4L2_CID_FLASH_FAULT - bitmask - - - Faults related to the flash. The - faults tell about specific problems in the flash chip - itself or the LEDs attached to it. Faults may prevent - further use of some of the flash controls. In particular, - V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE - if the fault affects the flash LED. Exactly which faults - have such an effect is chip dependent. Reading the faults - resets the control and returns the chip to a usable state - if possible. - - - - - - V4L2_FLASH_FAULT_OVER_VOLTAGE - Flash controller voltage to the flash LED - has exceeded the limit specific to the flash - controller. - - - V4L2_FLASH_FAULT_TIMEOUT - The flash strobe was still on when - the timeout set by the user --- - V4L2_CID_FLASH_TIMEOUT control --- has expired. - Not all flash controllers may set this in all - such conditions. - - - V4L2_FLASH_FAULT_OVER_TEMPERATURE - The flash controller has overheated. - - - V4L2_FLASH_FAULT_SHORT_CIRCUIT - The short circuit protection of the flash - controller has been triggered. - - - V4L2_FLASH_FAULT_OVER_CURRENT - Current in the LED power supply has exceeded the limit - specific to the flash controller. - - - V4L2_FLASH_FAULT_INDICATOR - The flash controller has detected a short or open - circuit condition on the indicator LED. - - - - - - V4L2_CID_FLASH_CHARGE - boolean - - Enable or disable charging of the xenon - flash capacitor. - - - V4L2_CID_FLASH_READY - boolean - - - Is the flash ready to strobe? - Xenon flashes require their capacitors charged before - strobing. LED flashes often require a cooldown period - after strobe during which another strobe will not be - possible. This is a read-only control. - - - - -
diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index a3d9dd09326..d15aaf83f56 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -374,29 +374,29 @@ rectangle --- if it is supported by the hardware. - Sink pad format. The user configures the sink pad + Sink pad format. The user configures the sink pad format. This format defines the parameters of the image the - entity receives through the pad for further processing. + entity receives through the pad for further processing. - Sink pad actual crop selection. The sink pad crop - defines the crop performed to the sink pad format. + Sink pad actual crop selection. The sink pad crop + defines the crop performed to the sink pad format. - Sink pad actual compose selection. The size of the + Sink pad actual compose selection. The size of the sink pad compose rectangle defines the scaling ratio compared to the size of the sink pad crop rectangle. The location of the compose rectangle specifies the location of the actual sink compose rectangle in the sink compose bounds - rectangle. + rectangle. - Source pad actual crop selection. Crop on the source + Source pad actual crop selection. Crop on the source pad defines crop performed to the image in the sink compose - bounds rectangle. + bounds rectangle. - Source pad format. The source pad format defines the + Source pad format. The source pad format defines the output pixel format of the subdev, as well as the other parameters with the exception of the image width and height. Width and height are defined by the size of the source pad - actual crop selection. + actual crop selection. Accessing any of the above rectangles not supported by the diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml index 8eace3e2e7d..2d3f0b1aefe 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml @@ -22,8 +22,7 @@ with 10 bits per colour compressed to 8 bits each, using DPCM compression. DPCM, differential pulse-code modulation, is lossy. Each colour component consumes 8 bits of memory. In other respects - this format is similar to . + this format is similar to . diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index e7ed5077834..4c238ce068b 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -40,6 +40,7 @@ cropping and composing rectangles have the same size.
Selection targets +
Cropping and composing targets @@ -52,12 +53,12 @@ cropping and composing rectangles have the same size.
+ + See for more + information.
- See for more - information. -
Configuration @@ -216,18 +217,17 @@ composing and cropping operations by setting the appropriate targets. The V4L2 API lacks any support for composing to and cropping from an image inside a memory buffer. The application could configure a capture device to fill only a part of an image by abusing V4L2 API. Cropping a smaller image from a larger -one is achieved by setting the field -&v4l2-pix-format;::bytesperline . Introducing an image offsets -could be done by modifying field &v4l2-buffer;::m:userptr - before calling VIDIOC_QBUF . Those +one is achieved by setting the field +&v4l2-pix-format;::bytesperline. Introducing an image offsets +could be done by modifying field &v4l2-buffer;::m_userptr +before calling VIDIOC_QBUF . Those operations should be avoided because they are not portable (endianness), and do not work for macroblock and Bayer formats and mmap buffers. The selection API deals with configuration of buffer cropping/composing in a clear, intuitive and portable way. Next, with the selection API the concepts of the padded target -and constraints flags are introduced. Finally, &v4l2-crop; - and &v4l2-cropcap; have no reserved -fields. Therefore there is no way to extend their functionality. The new - &v4l2-selection; provides a lot of place for future +and constraints flags are introduced. Finally, &v4l2-crop; and &v4l2-cropcap; +have no reserved fields. Therefore there is no way to extend their functionality. +The new &v4l2-selection; provides a lot of place for future extensions. Driver developers are encouraged to implement only selection API. The former cropping API would be simulated using the new one. diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index f76d8a6d9b9..b11ec75e21a 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -152,12 +152,10 @@ satisfactory parameters have been negotiated. If constraints flags have to be violated at then ERANGE is returned. The error indicates that there exist no rectangle that satisfies the constraints. - - Selection targets and flags are documented in . -
+
Size adjustments with constraint flags. @@ -170,9 +168,9 @@ exist no rectangle that satisfies the constraints.
-
+ - + struct <structname>v4l2_selection</structname> @@ -208,6 +206,7 @@ exist no rectangle that satisfies the constraints.
+ diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 77ff5be0809..6a821a65a5a 100644 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml @@ -155,6 +155,8 @@ or no buffers have been allocated yet, or the userptr or length are invalid. + + EIO VIDIOC_DQBUF failed due to an diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index f33cc814a01..1ba9e999af3 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -69,23 +69,22 @@ more information on how each selection target affects the image processing pipeline inside the subdevice. -
+ 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. -
+ -
+ Discovering supported features To discover which targets are supported, the user can perform VIDIOC_SUBDEV_G_SELECTION on them. Any unsupported target will return EINVAL. -
Selection targets and flags are documented in . @@ -132,6 +131,7 @@ + -- cgit v1.2.3 From 3a35c00b048ec368978cb497415c7a02f9200415 Mon Sep 17 00:00:00 2001 From: Antti Palosaari Date: Wed, 15 Aug 2012 20:28:40 -0300 Subject: [media] DocBook: update ioctl error codes ENOTTY is now returned for unimplemented ioctl by dvb-frontend. Old EOPNOTSUPP & ENOSYS could be still returned by some drivers as well as other "non standard" error codes. EAGAIN is returned in case of device is in state where it cannot perform requested operation. This is for example sleep and statistics are queried. Quick check for few demodulator drivers reveals there is a lot of different error codes used in such case currently, few to mention still: EOPNOTSUPP, ENOSYS, EAGAIN ... Lets try harmonize. Signed-off-by: Antti Palosaari Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/gen-errors.xml | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/gen-errors.xml b/Documentation/DocBook/media/v4l/gen-errors.xml index 5bbf3ce1973..737ecaaa335 100644 --- a/Documentation/DocBook/media/v4l/gen-errors.xml +++ b/Documentation/DocBook/media/v4l/gen-errors.xml @@ -6,6 +6,13 @@ &cs-str; + + EAGAIN + The ioctl can't be handled because the device is in state where + it can't perform it. This could happen for example in case where + device is sleeping and ioctl is performed to query statistics. + + EBADF The file descriptor is not a valid. @@ -50,11 +57,6 @@ that this request would overcommit the usb bandwidth reserved for periodic transfers (up to 80% of the USB bandwidth). - - ENOSYS or EOPNOTSUPP - Function not available for this device (dvb API only. Will likely - be replaced anytime soon by ENOTTY). - EPERM Permission denied. Can be returned if the device needs write -- cgit v1.2.3 From 1248c7cb66d734b60efed41be7c7b86909812c0e Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 10 Aug 2012 05:45:51 -0300 Subject: [media] V4L2 spec: document the new DV controls and ioctls Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/biblio.xml | 40 +++++++ Documentation/DocBook/media/v4l/controls.xml | 161 +++++++++++++++++++++++++++ Documentation/DocBook/media/v4l/v4l2.xml | 1 + 3 files changed, 202 insertions(+) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index 18b6fc9ff58..d2eb79e41a0 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -226,4 +226,44 @@ in the frequency range from 87,5 to 108,0 MHz VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT) + + EDID + + Video Electronics Standards Association +(http://www.vesa.org) + + VESA Enhanced Extended Display Identification Data Standard + Release A, Revision 2 + + + + HDCP + + Digital Content Protection LLC +(http://www.digital-cp.com) + + High-bandwidth Digital Content Protection System + Revision 1.3 + + + + HDMI + + HDMI Licensing LLC +(http://www.hdmi.org) + + High-Definition Multimedia Interface + Specification Version 1.4a + + + + DP + + Video Electronics Standards Association +(http://www.vesa.org) + + VESA DisplayPort Standard + Version 1, Revision 2 + + diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 93b9c6872e5..272a5f71850 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -4273,4 +4273,165 @@ interface and may change in the future.
+ +
+ Digital Video Control Reference + + + Experimental + + This is an experimental interface and may + change in the future. + + + + The Digital Video control class is intended to control receivers + and transmitters for VGA, + DVI + (Digital Visual Interface), HDMI () and DisplayPort (). + These controls are generally expected to be private to the receiver or transmitter + subdevice that implements them, so they are only exposed on the + /dev/v4l-subdev* device node. + + + Note that these devices can have multiple input or output pads which are + hooked up to e.g. HDMI connectors. Even though the subdevice will receive or + transmit video from/to only one of those pads, the other pads can still be + active when it comes to EDID (Extended Display Identification Data, + ) and HDCP (High-bandwidth Digital Content + Protection System, ) processing, allowing the device + to do the fairly slow EDID/HDCP handling in advance. This allows for quick + switching between connectors. + + These pads appear in several of the controls in this section as + bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad 1, + etc. The maximum value of the control is the set of valid pads. + + + Digital Video Control IDs + + + + + + + + + + + ID + Type + Description + + + + + + V4L2_CID_DV_CLASS + class + + + The Digital Video class descriptor. + + + V4L2_CID_DV_TX_HOTPLUG + bitmask + + + Many connectors have a hotplug pin which is high + if EDID information is available from the source. This control shows the + state of the hotplug pin as seen by the transmitter. + Each bit corresponds to an output pad on the transmitter. If an output pad + does not have an associated hotplug pin, then the bit for that pad will be 0. + This read-only control is applicable to DVI-D, HDMI and DisplayPort connectors. + + + + V4L2_CID_DV_TX_RXSENSE + bitmask + + + Rx Sense is the detection of pull-ups on the TMDS + clock lines. This normally means that the sink has left/entered standby (i.e. + the transmitter can sense that the receiver is ready to receive video). + Each bit corresponds to an output pad on the transmitter. If an output pad + does not have an associated Rx Sense, then the bit for that pad will be 0. + This read-only control is applicable to DVI-D and HDMI devices. + + + + V4L2_CID_DV_TX_EDID_PRESENT + bitmask + + + When the transmitter sees the hotplug signal from the + receiver it will attempt to read the EDID. If set, then the transmitter has read + at least the first block (= 128 bytes). + Each bit corresponds to an output pad on the transmitter. If an output pad + does not support EDIDs, then the bit for that pad will be 0. + This read-only control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. + + + + V4L2_CID_DV_TX_MODE + enum v4l2_dv_tx_mode + + + HDMI transmitters can transmit in DVI-D mode (just video) + or in HDMI mode (video + audio + auxiliary data). This control selects which mode + to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI. + This control is applicable to HDMI connectors. + + + + V4L2_CID_DV_TX_RGB_RANGE + enum v4l2_dv_rgb_range + + + Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO + follows the RGB quantization range specified in the standard for the video interface + (ie. for HDMI). V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the standard + to be compatible with sinks that have not implemented the standard correctly + (unfortunately quite common for HDMI and DVI-D). Full range allows all possible values to be + used whereas limited range sets the range to (16 << (N-8)) - (235 << (N-8)) + where N is the number of bits per component. + This control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. + + + + V4L2_CID_DV_RX_POWER_PRESENT + bitmask + + + Detects whether the receiver receives power from the source + (e.g. HDMI carries 5V on one of the pins). This is often used to power an eeprom + which contains EDID information, such that the source can read the EDID even if + the sink is in standby/power off. + Each bit corresponds to an input pad on the transmitter. If an input pad + cannot detect whether power is present, then the bit for that pad will be 0. + This read-only control is applicable to DVI-D, HDMI and DisplayPort connectors. + + + + V4L2_CID_DV_RX_RGB_RANGE + enum v4l2_dv_rgb_range + + + Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO + follows the RGB quantization range specified in the standard for the video interface + (ie. for HDMI). V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the standard + to be compatible with sources that have not implemented the standard correctly + (unfortunately quite common for HDMI and DVI-D). Full range allows all possible values to be + used whereas limited range sets the range to (16 << (N-8)) - (235 << (N-8)) + where N is the number of bits per component. + This control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. + + + + + +
+ +
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 0292ed10688..10ccde9d16d 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -581,6 +581,7 @@ and discussions on the V4L mailing list. &sub-subdev-enum-frame-size; &sub-subdev-enum-mbus-code; &sub-subdev-g-crop; + &sub-subdev-g-edid; &sub-subdev-g-fmt; &sub-subdev-g-frame-interval; &sub-subdev-g-selection; -- cgit v1.2.3 From 3c8139477bc55166fa4c125209d193bd9851af3c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 13 Sep 2012 17:06:34 -0300 Subject: [media] DocBook: Fix docbook compilation changeset 1248c7cb66d734b60efed41be7c7b86909812c0e broke html compilation: Documentation/DocBook/v4l2.xml:584: parser error : Entity 'sub-subdev-g-edid' not defined Documentation/DocBook/v4l2.xml:626: parser error : chunk is not well balanced Documentation/DocBook/media_api.xml:74: parser error : Failure to process entity sub-v4l2 Documentation/DocBook/media_api.xml:74: parser error : Entity 'sub-v4l2' not defined I suspect that one file was simply missed at the patch. Yet, keeping it broken is a very bad idea, so we should either remove the broken patch or to remove just the invalid include. Let's take the latter approach. Due to that, a warning is now produced: Error: no ID for constraint linkend: v4l2-subdev-edid. Cc: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/v4l2.xml | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 10ccde9d16d..0292ed10688 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -581,7 +581,6 @@ and discussions on the V4L mailing list. &sub-subdev-enum-frame-size; &sub-subdev-enum-mbus-code; &sub-subdev-g-crop; - &sub-subdev-g-edid; &sub-subdev-g-fmt; &sub-subdev-g-frame-interval; &sub-subdev-g-selection; -- cgit v1.2.3 From 355a4d01bd74bdd7b9dd9adeec683b2e3dd9549b Mon Sep 17 00:00:00 2001 From: Hans de Goede Date: Sat, 18 Aug 2012 12:32:19 -0300 Subject: [media] media-api-docs: Documented V4L2_TUNER_CAP_HWSEEK_PROG_LIM in G_TUNER docs Signed-off-by: Hans de Goede Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-g-tuner.xml | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index 701138f1209..6cc82010c73 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -354,6 +354,12 @@ radio tuners. The &VIDIOC-ENUM-FREQ-BANDS; ioctl can be used to enumerate the available frequency bands. + + V4L2_TUNER_CAP_HWSEEK_PROG_LIM + 0x0800 + The range to search when using the hardware seek functionality + is programmable, see &VIDIOC-S-HW-FREQ-SEEK; for details. + -- cgit v1.2.3 From 8ab023812b2b5e81bb1876a925541bceaf62538a Mon Sep 17 00:00:00 2001 From: Shaik Ameer Basha Date: Tue, 31 Jul 2012 10:44:02 -0300 Subject: [media] v4l: Add new YVU420 multi planar fourcc definition This patch adds new 'YM21' fourcc definition for multiplanar YCrCb pixel format - V4L2_PIX_FMT_YVU420M. Signed-off-by: Shaik Ameer Basha Signed-off-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml | 154 +++++++++++++++++++++ Documentation/DocBook/media/v4l/pixfmt.xml | 1 + 2 files changed, 155 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml b/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml new file mode 100644 index 00000000000..2330667907c --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml @@ -0,0 +1,154 @@ + + + V4L2_PIX_FMT_YVU420M ('YM21') + &manvol; + + + V4L2_PIX_FMT_YVU420M + Variation of V4L2_PIX_FMT_YVU420 + with planes non contiguous in memory. + + + + Description + + This is a multi-planar format, as opposed to a packed format. +The three components are separated into three sub-images or planes. + +The Y plane is first. The Y plane has one byte per pixel. The Cr data +constitutes the second plane which is half the width and half +the height of the Y plane (and of the image). Each Cr belongs to four +pixels, a two-by-two square of the image. For example, +Cr0 belongs to Y'00, +Y'01, Y'10, and +Y'11. The Cb data, just like the Cr plane, constitutes +the third plane. + + If the Y plane has pad bytes after each row, then the Cr +and Cb planes have half as many pad bytes after their rows. In other +words, two Cx rows (including padding) is exactly as long as one Y row +(including padding). + + V4L2_PIX_FMT_YVU420M is intended to be +used only in drivers and applications that support the multi-planar API, +described in . + + + <constant>V4L2_PIX_FMT_YVU420M</constant> 4 × 4 +pixel image + + + Byte Order. + Each cell is one byte. + + + + + + start0 + 0: + Y'00 + Y'01 + Y'02 + Y'03 + + + start0 + 4: + Y'10 + Y'11 + Y'12 + Y'13 + + + start0 + 8: + Y'20 + Y'21 + Y'22 + Y'23 + + + start0 + 12: + Y'30 + Y'31 + Y'32 + Y'33 + + + + start1 + 0: + Cr00 + Cr01 + + + start1 + 2: + Cr10 + Cr11 + + + + start2 + 0: + Cb00 + Cb01 + + + start2 + 2: + Cb10 + Cb11 + + + + + + + + + Color Sample Location. + + + + + + + 01 + 23 + + + 0 + YY + YY + + + + C + C + + + 1 + YY + YY + + + + + + 2 + YY + YY + + + + C + C + + + 3 + YY + YY + + + + + + + + + diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index e58934c9289..1ddbfabe319 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -708,6 +708,7 @@ information. &sub-y41p; &sub-yuv420; &sub-yuv420m; + &sub-yvu420m; &sub-yuv410; &sub-yuv422p; &sub-yuv411p; -- cgit v1.2.3 From 8fd207a1f7b65bee0a9b7948cb310d96fb11cc9e Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Sun, 2 Sep 2012 03:45:45 -0300 Subject: [media] v4l: Remove experimental tag from certain API elements Remove experimantal tag from the following API elements: V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY buffer type. V4L2_CAP_VIDEO_OUTPUT_OVERLAY capability flag. VIDIOC_ENUM_FRAMESIZES IOCTL. VIDIOC_ENUM_FRAMEINTERVALS IOCTL. VIDIOC_G_ENC_INDEX IOCTL. VIDIOC_ENCODER_CMD and VIDIOC_TRY_ENCODER_CMD IOCTLs. VIDIOC_DECODER_CMD and VIDIOC_TRY_DECODER_CMD IOCTLs. Signed-off-by: Sakari Ailus Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 23 ---------------------- Documentation/DocBook/media/v4l/dev-osd.xml | 7 ------- Documentation/DocBook/media/v4l/io.xml | 3 +-- .../DocBook/media/v4l/vidioc-decoder-cmd.xml | 7 ------- .../DocBook/media/v4l/vidioc-encoder-cmd.xml | 7 ------- .../DocBook/media/v4l/vidioc-enum-framesizes.xml | 7 ------- .../DocBook/media/v4l/vidioc-g-enc-index.xml | 7 ------- 7 files changed, 1 insertion(+), 60 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 98e8d088b3a..578135ec6b1 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2555,29 +2555,6 @@ and may change in the future. Video Output Overlay (OSD) Interface, . - - V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY, - &v4l2-buf-type;, . - - - V4L2_CAP_VIDEO_OUTPUT_OVERLAY, -&VIDIOC-QUERYCAP; ioctl, . - - - &VIDIOC-ENUM-FRAMESIZES; and -&VIDIOC-ENUM-FRAMEINTERVALS; ioctls. - - - &VIDIOC-G-ENC-INDEX; ioctl. - - - &VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; -ioctls. - - - &VIDIOC-DECODER-CMD; and &VIDIOC-TRY-DECODER-CMD; -ioctls. - &VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; ioctls. diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml index 479d9433869..dd91d6134e8 100644 --- a/Documentation/DocBook/media/v4l/dev-osd.xml +++ b/Documentation/DocBook/media/v4l/dev-osd.xml @@ -1,13 +1,6 @@ Video Output Overlay Interface Also known as On-Screen Display (OSD) - - Experimental - - This is an experimental -interface and may change in the future. - - Some video output devices can overlay a framebuffer image onto the outgoing video signal. Applications can set up such an overlay using this interface, which borrows structures and ioctls of the V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY 8 Buffer for video output overlay (OSD), see . Status: Experimental. + linkend="osd" />. V4L2_BUF_TYPE_PRIVATE diff --git a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml index 74b87f6e480..9215627b04c 100644 --- a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml @@ -49,13 +49,6 @@ Description - - Experimental - - This is an experimental -interface and may change in the future. - - These ioctls control an audio/video (usually MPEG-) decoder. VIDIOC_DECODER_CMD sends a command to the decoder, VIDIOC_TRY_DECODER_CMD can be used to diff --git a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml index f431b3ba79b..0619ca5d2d3 100644 --- a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml @@ -49,13 +49,6 @@ Description - - Experimental - - This is an experimental -interface and may change in the future. - - These ioctls control an audio/video (usually MPEG-) encoder. VIDIOC_ENCODER_CMD sends a command to the encoder, VIDIOC_TRY_ENCODER_CMD can be used to diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml b/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml index f77a13f486d..a78454b5abc 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml @@ -50,13 +50,6 @@ and pixel format and receives a frame width and height. Description - - Experimental - - This is an experimental -interface and may change in the future. - - This ioctl allows applications to enumerate all frame sizes (&ie; width and height in pixels) that the device supports for the given pixel format. diff --git a/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml b/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml index 2aef02c9044..be25029a16f 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml @@ -48,13 +48,6 @@ Description - - Experimental - - This is an experimental -interface and may change in the future. - - The VIDIOC_G_ENC_INDEX ioctl provides meta data about a compressed video stream the same or another application currently reads from the driver, which is useful for -- cgit v1.2.3 From 6bd4dd27f926519527b9c39709df13ad120d63f9 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 3 Sep 2012 09:21:59 -0300 Subject: [media] DocBook: improve STREAMON/OFF documentation Specify that STREAMON/OFF should return 0 if the stream is already started/stopped. The spec never specified what the correct behavior is. This ambiguity was resolved during the 2012 Media Workshop. Signed-off-by: Hans Verkuil Reviewed-by: Sylwester Nawrocki Acked-by: Laurent Pinchart Acked-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-streamon.xml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-streamon.xml b/Documentation/DocBook/media/v4l/vidioc-streamon.xml index 81cca456905..716ea15e54a 100644 --- a/Documentation/DocBook/media/v4l/vidioc-streamon.xml +++ b/Documentation/DocBook/media/v4l/vidioc-streamon.xml @@ -74,7 +74,12 @@ not transmitted yet. I/O returns to the same state as after calling stream type. This is the same as &v4l2-requestbuffers; type. - Note applications can be preempted for unknown periods right + If VIDIOC_STREAMON is called when streaming +is already in progress, or if VIDIOC_STREAMOFF is called +when streaming is already stopped, then the ioctl does nothing and 0 is +returned. + + Note that applications can be preempted for unknown periods right before or after the VIDIOC_STREAMON or VIDIOC_STREAMOFF calls, there is no notion of starting or stopping "now". Buffer timestamps can be used to -- cgit v1.2.3 From 93828d6438081649e81b8681df9bf6ad5d691650 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 3 Sep 2012 09:37:18 -0300 Subject: [media] DocBook: make the G/S/TRY_FMT specification more strict - S/TRY_FMT should always succeed, unless an invalid type field is passed in. - TRY_FMT should give the same result as S_FMT, all other things being equal. - ENUMFMT may return different formats for different inputs or outputs. This was decided during the 2012 Media Workshop. Signed-off-by: Hans Verkuil Reviewed-by: Sylwester Nawrocki Acked-by: Laurent Pinchart Acked-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml | 3 +++ Documentation/DocBook/media/v4l/vidioc-g-fmt.xml | 9 ++++++--- 2 files changed, 9 insertions(+), 3 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml index 81ebe48317f..0bd33242140 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml @@ -58,6 +58,9 @@ structure. Drivers fill the rest of the structure or return an incrementing by one until EINVAL is returned. + Note that after switching input or output the list of enumerated image +formats may be different. + struct <structname>v4l2_fmtdesc</structname> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml index 52acff193a6..b4b0e0a2854 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml @@ -81,7 +81,7 @@ the application calls the VIDIOC_S_FMT ioctl with a pointer to a v4l2_format structure the driver checks and adjusts the parameters against hardware abilities. Drivers -should not return an error code unless the input is ambiguous, this is +should not return an error code unless the type field is invalid, this is a mechanism to fathom device capabilities and to approach parameters acceptable for both the application and driver. On success the driver may program the hardware, allocate resources and generally prepare for @@ -107,6 +107,10 @@ disabling I/O or possibly time consuming hardware preparations. Although strongly recommended drivers are not required to implement this ioctl. + The format as returned by VIDIOC_TRY_FMT +must be identical to what VIDIOC_S_FMT returns for +the same input or output. +
struct <structname>v4l2_format</structname> @@ -187,8 +191,7 @@ capture and output devices. EINVAL The &v4l2-format; type -field is invalid, the requested buffer type not supported, or the -format is not supported with this buffer type. +field is invalid or the requested buffer type not supported. -- cgit v1.2.3 From cd56c8dd50fab57520f0cf80cee5de552c1680ed Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 14 Sep 2012 06:14:16 -0300 Subject: [media] DocBook: bus_info can no longer be empty During the 2012 Media Workshop it was decided that bus_info as returned by VIDIOC_QUERYCAP can no longer be empty. It should be a unique identifier, and empty strings are obviously not unique. Signed-off-by: Hans Verkuil Reviewed-by: Sylwester Nawrocki Reviewed-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-querycap.xml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml index f33dd746b66..4c70215ae03 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml @@ -90,11 +90,13 @@ ambiguities. __u8 bus_info[32] Location of the device in the system, a -NUL-terminated ASCII string. For example: "PCI Slot 4". This +NUL-terminated ASCII string. For example: "PCI:0000:05:06.0". This information is intended for users, to distinguish multiple -identical devices. If no such information is available the field may -simply count the devices controlled by the driver, or contain the -empty string (bus_info[0] = 0). +identical devices. If no such information is available the field must +simply count the devices controlled by the driver ("platform:vivi-000"). +The bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI Express boards, +"usb-" for USB devices, "I2C:" for i2c devices, "ISA:" for ISA devices, +"parport" for parallel port devices and "platform:" for platform devices. __u32 -- cgit v1.2.3 From 9495356f7ba958fa6b4fd7109caa292e4c233bd7 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 3 Sep 2012 10:09:23 -0300 Subject: [media] DocBook: deprecate V4L2_BUF_TYPE_PRIVATE As per decision taken during the 2012 Media Workshop. Signed-off-by: Hans Verkuil Acked-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 2 +- Documentation/DocBook/media/v4l/io.xml | 14 ++------------ Documentation/DocBook/media/v4l/vidioc-cropcap.xml | 6 ++---- Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml | 6 ++---- Documentation/DocBook/media/v4l/vidioc-g-crop.xml | 6 ++---- Documentation/DocBook/media/v4l/vidioc-g-fmt.xml | 4 +--- Documentation/DocBook/media/v4l/vidioc-g-parm.xml | 4 +--- Documentation/DocBook/media/v4l/vidioc-reqbufs.xml | 5 ++--- 8 files changed, 13 insertions(+), 34 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 578135ec6b1..c6ae4c9d0e0 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -1476,7 +1476,7 @@ follows. V4L2_BUF_TYPE_PRIVATE_BASE - V4L2_BUF_TYPE_PRIVATE + V4L2_BUF_TYPE_PRIVATE (but this is deprecated) diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 2512649b8e5..2dc39d81182 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -685,18 +685,14 @@ memory, set by the application. See for details. __u32 reserved2 - A place holder for future extensions and custom -(driver defined) buffer types -V4L2_BUF_TYPE_PRIVATE and higher. Applications + A place holder for future extensions. Applications should set this to 0. __u32 reserved - A place holder for future extensions and custom -(driver defined) buffer types -V4L2_BUF_TYPE_PRIVATE and higher. Applications + A place holder for future extensions. Applications should set this to 0. @@ -829,12 +825,6 @@ should set this to 0. Buffer for video output overlay (OSD), see . - - V4L2_BUF_TYPE_PRIVATE - 0x80 - This and higher values are reserved for custom -(driver defined) buffer types. -
diff --git a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml b/Documentation/DocBook/media/v4l/vidioc-cropcap.xml index f1bac2c6e97..4559c452a61 100644 --- a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-cropcap.xml @@ -70,10 +70,8 @@ output. Type of the data stream, set by the application. Only these types are valid here: V4L2_BUF_TYPE_VIDEO_CAPTURE, -V4L2_BUF_TYPE_VIDEO_OUTPUT, -V4L2_BUF_TYPE_VIDEO_OVERLAY, and custom (driver -defined) types with code V4L2_BUF_TYPE_PRIVATE -and higher. See . +V4L2_BUF_TYPE_VIDEO_OUTPUT and +V4L2_BUF_TYPE_VIDEO_OVERLAY. See . struct v4l2_rect diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml index 0bd33242140..f8dfeed34fc 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml @@ -81,10 +81,8 @@ Only these types are valid here: V4L2_BUF_TYPE_VIDEO_CAPTURE, V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE, V4L2_BUF_TYPE_VIDEO_OUTPUT, -V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE, -V4L2_BUF_TYPE_VIDEO_OVERLAY, and custom (driver -defined) types with code V4L2_BUF_TYPE_PRIVATE -and higher. See . +V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE and +V4L2_BUF_TYPE_VIDEO_OVERLAY. See . __u32 diff --git a/Documentation/DocBook/media/v4l/vidioc-g-crop.xml b/Documentation/DocBook/media/v4l/vidioc-g-crop.xml index c4ff3b1887f..75c6a93de3c 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-crop.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-crop.xml @@ -104,10 +104,8 @@ changed and VIDIOC_S_CROP returns the type Type of the data stream, set by the application. Only these types are valid here: V4L2_BUF_TYPE_VIDEO_CAPTURE, -V4L2_BUF_TYPE_VIDEO_OUTPUT, -V4L2_BUF_TYPE_VIDEO_OVERLAY, and custom (driver -defined) types with code V4L2_BUF_TYPE_PRIVATE -and higher. See . +V4L2_BUF_TYPE_VIDEO_OUTPUT and +V4L2_BUF_TYPE_VIDEO_OVERLAY. See . &v4l2-rect; diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml index b4b0e0a2854..ee8f56e1bac 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml @@ -174,9 +174,7 @@ capture and output devices. __u8 raw_data[200] - Place holder for future extensions and custom -(driver defined) formats with type -V4L2_BUF_TYPE_PRIVATE and higher. + Place holder for future extensions. diff --git a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml b/Documentation/DocBook/media/v4l/vidioc-g-parm.xml index f83d2cdd118..9058224d1bb 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-parm.xml @@ -108,9 +108,7 @@ devices. __u8 raw_data[200] - A place holder for future extensions and custom -(driver defined) buffer types V4L2_BUF_TYPE_PRIVATE and -higher. + A place holder for future extensions. diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml index d7c95057bc5..2b50ef2007f 100644 --- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml @@ -109,9 +109,8 @@ as the &v4l2-format; type field. See __u32 reserved[2] - A place holder for future extensions and custom -(driver defined) buffer types V4L2_BUF_TYPE_PRIVATE and -higher. This array should be zeroed by applications. + A place holder for future extensions. This array should +be zeroed by applications. -- cgit v1.2.3 From 663dc7f3a02712e22ef81f4c7b7b1caecceb8e4f Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 14 Sep 2012 06:44:20 -0300 Subject: [media] DocBook: document when to return ENODATA ENODATA should be returned if the API used for getting, changing, querying or enumerating the current video timings is not supported by the current input or output. This was decided during the 2012 Media Workshop. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml | 6 ++++++ Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml | 6 ++++++ Documentation/DocBook/media/v4l/vidioc-enumstd.xml | 6 ++++++ Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml | 9 ++++++--- Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml | 13 +++++++++---- Documentation/DocBook/media/v4l/vidioc-g-std.xml | 10 +++++++++- Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml | 9 +++++++++ Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml | 6 ++++++ Documentation/DocBook/media/v4l/vidioc-querystd.xml | 8 ++++++++ 9 files changed, 65 insertions(+), 8 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml index 509f0012d2a..fced5fb0dbf 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml @@ -229,6 +229,12 @@ intended for the user. is out of bounds. + + ENODATA + + Digital video presets are not supported for this input or output. + + diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml index 24c3bf4fd29..b3e17c1dfaf 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml @@ -106,6 +106,12 @@ application. is out of bounds. + + ENODATA + + Digital video presets are not supported for this input or output. + + diff --git a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml index 3a5fc5405f9..8065099401d 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml @@ -378,6 +378,12 @@ system) is out of bounds. + + ENODATA + + Standard video timings are not supported for this input or output. + + diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml index 61be9fa3803..b9ea37634f6 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml @@ -77,6 +77,12 @@ If the preset is not supported, it returns an &EINVAL; VIDIOC_S_DV_PRESET,VIDIOC_S_DV_PRESET parameter was unsuitable. + + ENODATA + + Digital video presets are not supported for this input or output. + + EBUSY @@ -104,7 +110,4 @@ If the preset is not supported, it returns an &EINVAL; - - &return-value; - diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml index eda1a2991bb..feaa18072e8 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml @@ -56,7 +56,9 @@ a pointer to the &v4l2-dv-timings; structure as argument. If the ioctl is not su or the timing values are not correct, the driver returns &EINVAL;. The linux/v4l2-dv-timings.h header can be used to get the timings of the formats in the and -standards. +standards. If the current input or output does not support DV timings (e.g. if +&VIDIOC-ENUMINPUT; does not set the V4L2_IN_CAP_CUSTOM_TIMINGS flag), then +&ENODATA; is returned. @@ -70,6 +72,12 @@ standards. VIDIOC_S_DV_TIMINGS parameter was unsuitable. + + ENODATA + + Digital video timings are not supported for this input or output. + + EBUSY @@ -320,7 +328,4 @@ detected or used depends on the hardware. - - &return-value; - diff --git a/Documentation/DocBook/media/v4l/vidioc-g-std.xml b/Documentation/DocBook/media/v4l/vidioc-g-std.xml index 99ff1a01622..4a898417de2 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-std.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-std.xml @@ -72,7 +72,9 @@ flags, being a write-only ioctl it does not return the actual new standard as the current input does not support the requested standard the driver returns an &EINVAL;. When the standard set is ambiguous drivers may return EINVAL or choose any of the requested -standards. +standards. If the current input or output does not support standard video timings (e.g. if +&VIDIOC-ENUMINPUT; does not set the V4L2_IN_CAP_STD flag), then +&ENODATA; is returned. @@ -85,6 +87,12 @@ standards. The VIDIOC_S_STD parameter was unsuitable. + + ENODATA + + Standard video timings are not supported for this input or output. + + diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml index 1bc8aeb3ff1..68b49d09e24 100644 --- a/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml +++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml @@ -65,5 +65,14 @@ returned. &return-value; + + + + ENODATA + + Digital video presets are not supported for this input or output. + + + diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml index 44935a0ffcf..e185f149e0a 100644 --- a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml @@ -77,6 +77,12 @@ capabilities in order to give more precise feedback to the user. &return-value; + + ENODATA + + Digital video timings are not supported for this input or output. + + ENOLINK diff --git a/Documentation/DocBook/media/v4l/vidioc-querystd.xml b/Documentation/DocBook/media/v4l/vidioc-querystd.xml index 4b79c7c04ed..fe80a183d95 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querystd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querystd.xml @@ -62,5 +62,13 @@ current video input or output. &return-value; + + + ENODATA + + Standard video timings are not supported for this input or output. + + + -- cgit v1.2.3 From 1c4f3c987f44a6653ac49f93d8cbd3adb539be10 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 3 Sep 2012 10:38:41 -0300 Subject: [media] Rename V4L2_(IN|OUT)_CAP_CUSTOM_TIMINGS The 'custom' timings are no longer just for custom timings, but also for standard CEA/VESA timings. So rename to V4L2_IN/OUT_CAP_DV_TIMINGS. The old define is still kept for backwards compatibility. This decision was taken during the 2012 Media Workshop. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-enuminput.xml | 2 +- Documentation/DocBook/media/v4l/vidioc-enumoutput.xml | 2 +- Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml index 46d5a044a53..3c9a81305ad 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml @@ -283,7 +283,7 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. This input supports setting DV presets by using VIDIOC_S_DV_PRESET. - V4L2_IN_CAP_CUSTOM_TIMINGS + V4L2_IN_CAP_DV_TIMINGS 0x00000002 This input supports setting video timings by using VIDIOC_S_DV_TIMINGS. diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml index 428020000ef..f4ab0798545 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml @@ -168,7 +168,7 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. This output supports setting DV presets by using VIDIOC_S_DV_PRESET. - V4L2_OUT_CAP_CUSTOM_TIMINGS + V4L2_OUT_CAP_DV_TIMINGS 0x00000002 This output supports setting video timings by using VIDIOC_S_DV_TIMINGS. diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml index feaa18072e8..72369707bd7 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml @@ -57,7 +57,7 @@ or the timing values are not correct, the driver returns &EINVAL;. The linux/v4l2-dv-timings.h header can be used to get the timings of the formats in the and standards. If the current input or output does not support DV timings (e.g. if -&VIDIOC-ENUMINPUT; does not set the V4L2_IN_CAP_CUSTOM_TIMINGS flag), then +&VIDIOC-ENUMINPUT; does not set the V4L2_IN_CAP_DV_TIMINGS flag), then &ENODATA; is returned. -- cgit v1.2.3 From d7a11e1f18e1b6772af0e7670baa83ce8c3b2674 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 14 Sep 2012 07:39:55 -0300 Subject: [media] DocBook: fix awkward language and fix the documented return value The Video Standard section contains some awkward language. It also wasn't updated when the error code for unimplemented ioctls changed from EINVAL to ENOTTY. [mchehab@redhat.com: remove a misplaced footnote tag] Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/common.xml | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index b91d25313b6..73c6847436c 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -564,7 +564,7 @@ automatically. To query and select the standard used by the current video input or output applications call the &VIDIOC-G-STD; and &VIDIOC-S-STD; ioctl, respectively. The received -standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), not an index into the standard enumeration. +standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), not an index into the standard enumeration. An alternative to the current scheme is to use pointers to indices as arguments of VIDIOC_G_STD and VIDIOC_S_STD, the &v4l2-input; and @@ -588,30 +588,28 @@ switch to a standard by &v4l2-std-id;. Drivers must implement all video standard ioctls when the device has one or more video inputs or outputs. - Special rules apply to USB cameras where the notion of video -standards makes little sense. More generally any capture device, -output devices accordingly, which is + Special rules apply to devices such as USB cameras where the notion of video +standards makes little sense. More generally for any capture or output device +which is: incapable of capturing fields or frames at the nominal rate of the video standard, or - where timestamps refer -to the instant the field or frame was received by the driver, not the -capture time, or - - - where sequence numbers -refer to the frames received by the driver, not the captured -frames. + that does not support the video standard formats at all. Here the driver shall set the std field of &v4l2-input; and &v4l2-output; -to zero, the VIDIOC_G_STD, +to zero and the VIDIOC_G_STD, VIDIOC_S_STD, VIDIOC_QUERYSTD and VIDIOC_ENUMSTD ioctls shall return the -&EINVAL;. +&ENOTTY;. + See for a rationale. + Applications can make use of the and + flags to determine whether the video standard ioctls +are available for the device. +&ENOTTY;. See for a rationale. Probably even USB cameras follow some well known video standard. It might have been better to explicitly indicate elsewhere if a device cannot live @@ -626,9 +624,9 @@ up to normal expectations, instead of this exception. &v4l2-standard; standard; if (-1 == ioctl (fd, &VIDIOC-G-STD;, &std_id)) { - /* Note when VIDIOC_ENUMSTD always returns EINVAL this + /* Note when VIDIOC_ENUMSTD always returns ENOTTY this is no video device or it falls under the USB exception, - and VIDIOC_G_STD returning EINVAL is no error. */ + and VIDIOC_G_STD returning ENOTTY is no error. */ perror ("VIDIOC_G_STD"); exit (EXIT_FAILURE); -- cgit v1.2.3 From 0b1f8149a5e7ee71f36af75bb516eb8219158f2d Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Tue, 4 Sep 2012 07:07:54 -0300 Subject: [media] DocBook: clarify that sequence is also set for output devices It was not entirely obvious that the sequence count should also be set for output devices. Also made it more explicit that this sequence counter counts frames, not fields. Signed-off-by: Hans Verkuil Reviewed-by: Sylwester Nawrocki Acked-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/io.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 2dc39d81182..97f785add84 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -613,8 +613,8 @@ field is independent of the timestamp and __u32 sequence - Set by the driver, counting the frames in the -sequence. + Set by the driver, counting the frames (not fields!) in +sequence. This field is set for both input and output devices. In Date: Fri, 14 Sep 2012 07:40:43 -0300 Subject: [media] DocBook: Mark CROPCAP as optional instead of as compulsory While the documentation says that VIDIOC_CROPCAP is compulsory for all video capture and output devices, in practice VIDIOC_CROPCAP is only implemented for devices that can do cropping and/or scaling. Update the documentation to no longer require VIDIOC_CROPCAP if the driver does not support cropping or scaling or non-square pixels. Signed-off-by: Hans Verkuil Reviewed-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-cropcap.xml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml b/Documentation/DocBook/media/v4l/vidioc-cropcap.xml index 4559c452a61..bf7cc979fdf 100644 --- a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-cropcap.xml @@ -59,6 +59,9 @@ constant except when switching the video standard. Remember this switch can occur implicit when switching the video input or output. + This ioctl must be implemented for video capture or output devices that +support cropping and/or scaling and/or have non-square pixels, and for overlay devices. + struct <structname>v4l2_cropcap</structname> @@ -70,7 +73,9 @@ output. Type of the data stream, set by the application. Only these types are valid here: V4L2_BUF_TYPE_VIDEO_CAPTURE, -V4L2_BUF_TYPE_VIDEO_OUTPUT and +V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE, +V4L2_BUF_TYPE_VIDEO_OUTPUT, +V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE and V4L2_BUF_TYPE_VIDEO_OVERLAY. See . @@ -154,8 +159,7 @@ on 22 Oct 2002 subject "Re:[V4L][patches!] Re:v4l2/kernel-2.5" --> EINVAL The &v4l2-cropcap; type is -invalid. This is not permitted for video capture, output and overlay devices, -which must support VIDIOC_CROPCAP. +invalid. -- cgit v1.2.3 From 7c287e91ff3d77e1538aca08a79e8f782e05d4bf Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 26 Sep 2012 05:24:18 -0300 Subject: [media] Docbook: add missing vidioc-subdev-g-edid.xml Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/v4l2.xml | 1 + .../DocBook/media/v4l/vidioc-subdev-g-edid.xml | 152 +++++++++++++++++++++ 2 files changed, 153 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/vidioc-subdev-g-edid.xml (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 0292ed10688..10ccde9d16d 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -581,6 +581,7 @@ and discussions on the V4L mailing list. &sub-subdev-enum-frame-size; &sub-subdev-enum-mbus-code; &sub-subdev-g-crop; + &sub-subdev-g-edid; &sub-subdev-g-fmt; &sub-subdev-g-frame-interval; &sub-subdev-g-selection; diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-edid.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-edid.xml new file mode 100644 index 00000000000..bbd18f0e6ed --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-edid.xml @@ -0,0 +1,152 @@ + + + ioctl VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID + &manvol; + + + + VIDIOC_SUBDEV_G_EDID + VIDIOC_SUBDEV_S_EDID + Get or set the EDID of a video receiver/transmitter + + + + + + int ioctl + int fd + int request + struct v4l2_subdev_edid *argp + + + + + int ioctl + int fd + int request + const struct v4l2_subdev_edid *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID + + + + argp + + + + + + + + + Description + These ioctls can be used to get or set an EDID associated with an input pad + from a receiver or an output pad of a transmitter subdevice. + + To get the EDID data the application has to fill in the pad, + start_block, blocks and edid + fields and call VIDIOC_SUBDEV_G_EDID. The current EDID from block + start_block and of size blocks + will be placed in the memory edid points to. The edid + pointer must point to memory at least blocks * 128 bytes + large (the size of one block is 128 bytes). + + If there are fewer blocks than specified, then the driver will set blocks + to the actual number of blocks. If there are no EDID blocks available at all, then the error code + ENODATA is set. + + If blocks have to be retrieved from the sink, then this call will block until they + have been read. + + To set the EDID blocks of a receiver the application has to fill in the pad, + blocks and edid fields and set + start_block to 0. It is not possible to set part of an EDID, + it is always all or nothing. Setting the EDID data is only valid for receivers as it makes + no sense for a transmitter. + + The driver assumes that the full EDID is passed in. If there are more EDID blocks than + the hardware can handle then the EDID is not written, but instead the error code E2BIG is set + and blocks is set to the maximum that the hardware supports. + If start_block is any + value other than 0 then the error code EINVAL is set. + + To disable an EDID you set blocks to 0. Depending on the + hardware this will drive the hotplug pin low and/or block the source from reading the EDID + data in some way. In any case, the end result is the same: the EDID is no longer available. + + +
+ struct <structname>v4l2_subdev_edid</structname> + + &cs-str; + + + __u32 + pad + Pad for which to get/set the EDID blocks. + + + __u32 + start_block + Read the EDID from starting with this block. Must be 0 when setting + the EDID. + + + __u32 + blocks + The number of blocks to get or set. Must be less or equal to 256 (the + maximum number of blocks as defined by the standard). When you set the EDID and + blocks is 0, then the EDID is disabled or erased. + + + __u8 * + edid + Pointer to memory that contains the EDID. The minimum size is + blocks * 128. + + + __u32 + reserved[5] + Reserved for future extensions. Applications and drivers must + set the array to zero. + + + +
+ + + + &return-value; + + + + ENODATA + + The EDID data is not available. + + + + E2BIG + + The EDID data you provided is more than the hardware can handle. + + + + + -- cgit v1.2.3 From 6473262e80709e65b7dc71549b8b8e41c604809a Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 21 Sep 2012 08:32:49 -0300 Subject: [media] DocBook: EAGAIN == EWOULDBLOCK Merge the two entries since they are one and the same error. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/gen-errors.xml | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/gen-errors.xml b/Documentation/DocBook/media/v4l/gen-errors.xml index 737ecaaa335..7e29a4e1f69 100644 --- a/Documentation/DocBook/media/v4l/gen-errors.xml +++ b/Documentation/DocBook/media/v4l/gen-errors.xml @@ -7,10 +7,12 @@ - EAGAIN + EAGAIN (aka EWOULDBLOCK) The ioctl can't be handled because the device is in state where it can't perform it. This could happen for example in case where device is sleeping and ioctl is performed to query statistics. + It is also returned when the ioctl would need to wait + for an event, but the device was opened in non-blocking mode. @@ -63,11 +65,6 @@ permission, or some special capabilities is needed (e. g. root) - - EWOULDBLOCK - Operation would block. Used when the ioctl would need to wait - for an event, but the device was opened in non-blocking mode. - -- cgit v1.2.3 From f9611240b96fd18359531e939b09969fee556221 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 21 Sep 2012 08:33:38 -0300 Subject: [media] DocBook: in non-blocking mode return EAGAIN in hwseek VIDIOC_S_HW_FREQ_SEEK should return EAGAIN when called in non-blocking mode. This might change in the future if we add support for this in the future, but right now this is not supported. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'Documentation/DocBook/media/v4l') 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 3dd1bec6d3c..5b379e75219 100644 --- a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml +++ b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml @@ -75,6 +75,9 @@ seek is started. This ioctl is supported if the V4L2_CAP_HW_FREQ_SEEK capability is set. + If this ioctl is called from a non-blocking filehandle, then &EAGAIN; is + returned and no seek takes place. + struct <structname>v4l2_hw_freq_seek</structname> @@ -157,6 +160,13 @@ one of the values in the type, fields is wrong. + + EAGAIN + + Attempted to call VIDIOC_S_HW_FREQ_SEEK + with the filehandle in non-blocking mode. + + ENODATA -- cgit v1.2.3 From d2642485d694027ad8c918844cee0e547cc11bcb Mon Sep 17 00:00:00 2001 From: Sylwester Nawrocki Date: Thu, 16 Feb 2012 14:23:54 -0300 Subject: [media] V4L: Add V4L2_MBUS_FMT_S5C_UYVY_JPEG_1X8 media bus format This patch adds media bus pixel code for the interleaved JPEG/UYVY image format used by S5C73MX Samsung cameras. This interleaved image data is transferred on MIPI-CSI2 bus as User Defined Byte-based Data. It also defines an experimental vendor and device specific media bus formats section and adds related DocBook documentation. Signed-off-by: Sylwester Nawrocki Signed-off-by: Kyungmin Park Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 4 ++ Documentation/DocBook/media/v4l/subdev-formats.xml | 44 ++++++++++++++++++++++ 2 files changed, 48 insertions(+) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index c6ae4c9d0e0..4fdf6b562d1 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2582,6 +2582,10 @@ ioctls. Support for frequency band enumeration: &VIDIOC-ENUM-FREQ-BANDS; ioctl. + + Vendor and device specific media bus pixel formats. + . + diff --git a/Documentation/DocBook/media/v4l/subdev-formats.xml b/Documentation/DocBook/media/v4l/subdev-formats.xml index 49c532ebbbb..a0a936455fa 100644 --- a/Documentation/DocBook/media/v4l/subdev-formats.xml +++ b/Documentation/DocBook/media/v4l/subdev-formats.xml @@ -2565,5 +2565,49 @@
+ +
+ Vendor and Device Specific Formats + + + Experimental + This is an experimental +interface and may change in the future. + + + This section lists complex data formats that are either vendor or + device specific. + + + The following table lists the existing vendor and device specific + formats. + + + Vendor and device specific formats + + + + + + + Identifier + Code + Comments + + + + + V4L2_MBUS_FMT_S5C_UYVY_JPEG_1X8 + 0x5001 + + Interleaved raw UYVY and JPEG image format with embedded + meta-data used by Samsung S3C73MX camera sensors. + + + + +
+
+ -- cgit v1.2.3 From c3010097a79fc741d27b07e068598fd9468ca41f Mon Sep 17 00:00:00 2001 From: Sylwester Nawrocki Date: Wed, 3 Oct 2012 07:44:53 -0300 Subject: [media] V4L: Add V4L2_PIX_FMT_S5C_UYVY_JPG fourcc definition This patch adds definition of the Samsung S5C73M3 camera specific image format. V4L2_PIX_FMT_S5C_UYVY_JPG is a two-planar format, the first plane contains interleaved UYVY and JPEG data followed by meta-data. The second plane contains additional meta-data needed for extracting JPEG and UYVY data stream from the first plane. Signed-off-by: Sylwester Nawrocki Signed-off-by: Kyungmin Park Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/pixfmt.xml | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index 1ddbfabe319..fce143726fd 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -996,6 +996,34 @@ the other bits are set to 0. Old 6-bit greyscale format. Only the most significant 6 bits of each byte are used, the other bits are set to 0. + + V4L2_PIX_FMT_S5C_UYVY_JPG + 'S5CI' + Two-planar format used by Samsung S5C73MX cameras. The +first plane contains interleaved JPEG and UYVY image data, followed by meta data +in form of an array of offsets to the UYVY data blocks. The actual pointer array +follows immediately the interleaved JPEG/UYVY data, the number of entries in +this array equals the height of the UYVY image. Each entry is a 4-byte unsigned +integer in big endian order and it's an offset to a single pixel line of the +UYVY image. The first plane can start either with JPEG or UYVY data chunk. The +size of a single UYVY block equals the UYVY image's width multiplied by 2. The +size of a JPEG chunk depends on the image and can vary with each line. +The second plane, at an offset of 4084 bytes, contains a 4-byte offset to +the pointer array in the first plane. This offset is followed by a 4-byte value +indicating size of the pointer array. All numbers in the second plane are also +in big endian order. Remaining data in the second plane is undefined. The +information in the second plane allows to easily find location of the pointer +array, which can be different for each frame. The size of the pointer array is +constant for given UYVY image height. +In order to extract UYVY and JPEG frames an application can initially set +a data pointer to the start of first plane and then add an offset from the first +entry of the pointers table. Such a pointer indicates start of an UYVY image +pixel line. Whole UYVY line can be copied to a separate buffer. These steps +should be repeated for each line, i.e. the number of entries in the pointer +array. Anything what's in between the UYVY lines is JPEG data and should be +concatenated to form the JPEG stream. + + -- cgit v1.2.3 From 5ebef0fbe0f72fa911088800c5d0bc7a872c35de Mon Sep 17 00:00:00 2001 From: "Lad, Prabhakar" Date: Mon, 1 Oct 2012 08:17:36 -0300 Subject: [media] media: v4l2-ctrls: add control for test pattern add V4L2_CID_TEST_PATTERN of type menu, which determines the internal test pattern selected by the device. Signed-off-by: Lad, Prabhakar Signed-off-by: Manjunath Hadli Acked-by: Sakari Ailus Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/controls.xml | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 272a5f71850..a84a08ca51d 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -4267,6 +4267,16 @@ interface and may change in the future. pixels / second. + + V4L2_CID_TEST_PATTERN + menu + + + Some capture/display/sensor devices have + the capability to generate test pattern images. These hardware + specific test patterns can be used to test if a device is working + properly. + -- cgit v1.2.3 From e3b1b4e732e18befcfa428bac1c487f681fbc36a Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 19 Sep 2012 11:14:39 -0300 Subject: [media] DocBook: various updates w.r.t. v4l2_buffer and multiplanar Clarify the behavior of v4l2_buffer in the multiplanar case, including fixing a false statement: you can't set m.planes to NULL when calling DQBUF. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/io.xml | 6 ++++-- Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 3 +-- Documentation/DocBook/media/v4l/vidioc-querybuf.xml | 11 +++++++---- 3 files changed, 12 insertions(+), 8 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 97f785add84..b5d1cbdc558 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -677,8 +677,10 @@ memory, set by the application. See for details. length Size of the buffer (not the payload) in bytes for the - single-planar API. For the multi-planar API should contain the - number of elements in the planes array. + single-planar API. For the multi-planar API the application sets + this to the number of elements in the planes + array. The driver will fill in the actual number of valid elements in + that array. diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 6a821a65a5a..2d37abefce1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml @@ -121,8 +121,7 @@ remaining fields or returns an error code. The driver may also set field. It indicates a non-critical (recoverable) streaming error. In such case the application may continue as normal, but should be aware that data in the dequeued buffer might be corrupted. When using the multi-planar API, the -planes array does not have to be passed; the m.planes -member must be set to NULL in that case. +planes array must be passed in as well. By default VIDIOC_DQBUF blocks when no buffer is in the outgoing queue. When the diff --git a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml b/Documentation/DocBook/media/v4l/vidioc-querybuf.xml index 6e414d7b6df..a597155c052 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querybuf.xml @@ -48,8 +48,8 @@ Description - This ioctl is part of the memory -mapping I/O method. It can be used to query the status of a + This ioctl is part of the streaming + I/O method. It can be used to query the status of a buffer at any time after buffers have been allocated with the &VIDIOC-REQBUFS; ioctl. @@ -71,6 +71,7 @@ the structure. In the flags field the V4L2_BUF_FLAG_MAPPED, +V4L2_BUF_FLAG_PREPARED, V4L2_BUF_FLAG_QUEUED and V4L2_BUF_FLAG_DONE flags will be valid. The memory field will be set to the current @@ -79,8 +80,10 @@ contains the offset of the buffer from the start of the device memory, the length field its size. For the multi-planar API, fields m.mem_offset and length in the m.planes -array elements will be used instead. The driver may or may not set the remaining -fields and flags, they are meaningless in this context. +array elements will be used instead and the length +field of &v4l2-buffer; is set to the number of filled-in array elements. +The driver may or may not set the remaining fields and flags, they are +meaningless in this context. The v4l2_buffer structure is specified in . -- cgit v1.2.3 From 4d08f670e63200cc092724de8c95f81df606b1a5 Mon Sep 17 00:00:00 2001 From: Arun Kumar K Date: Wed, 3 Oct 2012 22:19:05 -0300 Subject: [media] v4l: Add fourcc definitions for new formats Add the following new fourcc definitions, for multiplanar YCbCr: V4L2_PIX_FMT_NV21M, V4L2_PIX_FMT_NV12MT_16X16 and compressed formats: V4L2_PIX_FMT_H264_MVC, V4L2_PIX_FMT_VP8. Signed-off-by: Jeongtae Park Signed-off-by: Naveen Krishna Chatradhi Signed-off-by: Arun Kumar K Acked-by: Kamil Debski Signed-off-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/pixfmt-nv12m.xml | 17 ++++++++++++----- Documentation/DocBook/media/v4l/pixfmt.xml | 10 ++++++++++ 2 files changed, 22 insertions(+), 5 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml index 5274c24d11e..a990b34d911 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml @@ -1,11 +1,13 @@ - + - V4L2_PIX_FMT_NV12M ('NM12') + V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16 &manvol; - V4L2_PIX_FMT_NV12M - Variation of V4L2_PIX_FMT_NV12 with planes + V4L2_PIX_FMT_NV12M + V4L2_PIX_FMT_NV21M + V4L2_PIX_FMT_NV12MT_16X16 + Variation of V4L2_PIX_FMT_NV12 and V4L2_PIX_FMT_NV21 with planes non contiguous in memory. @@ -22,7 +24,12 @@ The CbCr plane is the same width, in bytes, as the Y plane (and of the image), but is half as tall in pixels. Each CbCr pair belongs to four pixels. For example, Cb0/Cr0 belongs to Y'00, Y'01, -Y'10, Y'11. +Y'10, Y'11. +V4L2_PIX_FMT_NV12MT_16X16 is the tiled version of +V4L2_PIX_FMT_NV12M with 16x16 macroblock tiles. Here pixels +are arranged in 16x16 2D tiles and tiles are arranged in linear order in memory. +V4L2_PIX_FMT_NV21M is the same as V4L2_PIX_FMT_NV12M +except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte. V4L2_PIX_FMT_NV12M is intended to be used only in drivers and applications that support the multi-planar API, diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index fce143726fd..bf94f417592 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -758,6 +758,11 @@ extended control V4L2_CID_MPEG_STREAM_TYPE, see 'AVC1' H264 video elementary stream without start codes. + + V4L2_PIX_FMT_H264_MVC + 'MVC' + H264 MVC video elementary stream. + V4L2_PIX_FMT_H263 'H263' @@ -793,6 +798,11 @@ extended control V4L2_CID_MPEG_STREAM_TYPE, see 'VC1L' VC1, SMPTE 421M Annex L compliant stream. + + V4L2_PIX_FMT_VP8 + 'VP8' + VP8 video elementary stream. + -- cgit v1.2.3 From 2e81dde94316dfaa19f0b6f9d4131ef7eaf124a3 Mon Sep 17 00:00:00 2001 From: Arun Kumar K Date: Wed, 3 Oct 2012 22:19:06 -0300 Subject: [media] v4l: Add control definitions for new H264 encoder features New controls are added for supporting H264 encoding features like: - MVC frame packing, - flexible macroblock ordering, - arbitrary slice ordering, - hierarchical coding. Signed-off-by: Jeongtae Park Signed-off-by: Naveen Krishna Chatradhi Signed-off-by: Arun Kumar K Acked-by: Kamil Debski Signed-off-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/controls.xml | 268 ++++++++++++++++++++++++++- 1 file changed, 267 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index a84a08ca51d..7fe5be1d3bb 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -1586,7 +1586,6 @@ frame counter of the frame that is currently displayed (decoded). This value is the decoder is started. - V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE  @@ -2269,6 +2268,14 @@ encoder or editing process may produce.". Applicable to the MPEG1, MPEG2, MPEG4 encoders. + + + V4L2_CID_MPEG_VIDEO_VBV_DELAY  + integer + Sets the initial delay in milliseconds for +VBV buffer control. + + V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE  @@ -2334,6 +2341,265 @@ Applicable to the MPEG4 decoder. vop_time_increment value for MPEG4. Applicable to the MPEG4 encoder. + + + V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING  + boolean + + Enable generation of frame packing supplemental enhancement information in the encoded bitstream. +The frame packing SEI message contains the arrangement of L and R planes for 3D viewing. Applicable to the H264 encoder. + + + + + V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0  + boolean + + Sets current frame as frame0 in frame packing SEI. +Applicable to the H264 encoder. + + + + + V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE  + enum v4l2_mpeg_video_h264_sei_fp_arrangement_type + + Frame packing arrangement type for H264 SEI. +Applicable to the H264 encoder. +Possible values are: + + + + + + V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD  + Pixels are alternatively from L and R. + + + V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN  + L and R are interlaced by column. + + + V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW  + L and R are interlaced by row. + + + V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE  + L is on the left, R on the right. + + + V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM  + L is on top, R on bottom. + + + V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL  + One view per frame. + + + + + + + + V4L2_CID_MPEG_VIDEO_H264_FMO  + boolean + + Enables flexible macroblock ordering in the encoded bitstream. It is a technique +used for restructuring the ordering of macroblocks in pictures. Applicable to the H264 encoder. + + + + + V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE  + enum v4l2_mpeg_video_h264_fmo_map_type + + When using FMO, the map type divides the image in different scan patterns of macroblocks. +Applicable to the H264 encoder. +Possible values are: + + + + + + V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES  + Slices are interleaved one after other with macroblocks in run length order. + + + V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES  + Scatters the macroblocks based on a mathematical function known to both encoder and decoder. + + + V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER  + Macroblocks arranged in rectangular areas or regions of interest. + + + V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT  + Slice groups grow in a cyclic way from centre to outwards. + + + V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN  + Slice groups grow in raster scan pattern from left to right. + + + V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN  + Slice groups grow in wipe scan pattern from top to bottom. + + + V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT  + User defined map type. + + + + + + + + V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP  + integer + + Number of slice groups in FMO. +Applicable to the H264 encoder. + + + + + V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION  + enum v4l2_mpeg_video_h264_fmo_change_dir + + Specifies a direction of the slice group change for raster and wipe maps. +Applicable to the H264 encoder. +Possible values are: + + + + + + V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT  + Raster scan or wipe right. + + + V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT  + Reverse raster scan or wipe left. + + + + + + + + V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE  + integer + + Specifies the size of the first slice group for raster and wipe map. +Applicable to the H264 encoder. + + + + + V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH  + integer + + Specifies the number of consecutive macroblocks for the interleaved map. +Applicable to the H264 encoder. + + + + + V4L2_CID_MPEG_VIDEO_H264_ASO  + boolean + + Enables arbitrary slice ordering in encoded bitstream. +Applicable to the H264 encoder. + + + + + V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER  + integer + Specifies the slice order in ASO. Applicable to the H264 encoder. +The supplied 32-bit integer is interpreted as follows (bit +0 = least significant bit): + + + + + + Bit 0:15 + Slice ID + + + Bit 16:32 + Slice position or order + + + + + + + + V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING  + boolean + + Enables H264 hierarchical coding. +Applicable to the H264 encoder. + + + + + V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE  + enum v4l2_mpeg_video_h264_hierarchical_coding_type + + Specifies the hierarchical coding type. +Applicable to the H264 encoder. +Possible values are: + + + + + + V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B  + Hierarchical B coding. + + + V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P  + Hierarchical P coding. + + + + + + + + V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER  + integer + + Specifies the number of hierarchical coding layers. +Applicable to the H264 encoder. + + + + + V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP  + integer + Specifies a user defined QP for each layer. Applicable to the H264 encoder. +The supplied 32-bit integer is interpreted as follows (bit +0 = least significant bit): + + + + + + Bit 0:15 + QP value + + + Bit 16:32 + Layer number + + + + + -- cgit v1.2.3 From e7d993550167ef810b6658fc7b0a73517c2ed957 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Sun, 21 Oct 2012 15:30:02 -0300 Subject: [media] v4l: Correct definition of v4l2_buffer.flags related to cache management V4L2_BUF_FLAG_NO_CACHE_INVALIDATE and V4L2_BUF_FLAG_NO_CACHE_CLEAN were define incorrectly in the documentation. Fix this by changing the documentation to match reality. Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/io.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index b5d1cbdc558..7e2f3d7d78a 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -923,7 +923,7 @@ application. Drivers set or clear this flag when the V4L2_BUF_FLAG_NO_CACHE_INVALIDATE - 0x0400 + 0x0800 Caches do not have to be invalidated for this buffer. Typically applications shall use this flag if the data captured in the buffer is not going to be touched by the CPU, instead the buffer will, probably, be @@ -932,7 +932,7 @@ passed on to a DMA-capable hardware unit for further processing or output. V4L2_BUF_FLAG_NO_CACHE_CLEAN - 0x0800 + 0x1000 Caches do not have to be cleaned for this buffer. Typically applications shall use this flag for output buffers if the data in this buffer has not been created by the CPU but by some DMA-capable unit, -- cgit v1.2.3 From 4b9c1cb641c466cd3b366132017da3c8ab9d540c Mon Sep 17 00:00:00 2001 From: Tomasz Stanislawski Date: Thu, 14 Jun 2012 10:37:36 -0300 Subject: [media] Documentation: media: description of DMABUF importing in V4L2 This patch adds description and usage examples for importing DMABUF file descriptor in V4L2. Signed-off-by: Tomasz Stanislawski Signed-off-by: Kyungmin Park Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 4 + Documentation/DocBook/media/v4l/io.xml | 181 ++++++++++++++++++++- .../DocBook/media/v4l/vidioc-create-bufs.xml | 16 +- Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 17 ++ Documentation/DocBook/media/v4l/vidioc-reqbufs.xml | 47 +++--- 5 files changed, 235 insertions(+), 30 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 4fdf6b562d1..50eb63024eb 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2586,6 +2586,10 @@ ioctls. Vendor and device specific media bus pixel formats. . + + Importing DMABUF file descriptors as a new IO method described + in . + diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 7e2f3d7d78a..be0fad7e120 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -331,7 +331,7 @@ application until one or more buffers can be dequeued. By default outgoing queue. When the O_NONBLOCK flag was given to the &func-open; function, VIDIOC_DQBUF returns immediately with an &EAGAIN; when no buffer is available. The -&func-select; or &func-poll; function are always available. +&func-select; or &func-poll; functions are always available. To start and stop capturing or output applications call the &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note @@ -472,6 +472,162 @@ rest should be evident. +
+ Streaming I/O (DMA buffer importing) + + + Experimental + This is an experimental + interface and may change in the future. + + +The DMABUF framework provides a generic method for sharing buffers +between multiple devices. Device drivers that support DMABUF can export a DMA +buffer to userspace as a file descriptor (known as the exporter role), import a +DMA buffer from userspace using a file descriptor previously exported for a +different or the same device (known as the importer role), or both. This +section describes the DMABUF importer role API in V4L2. + +Input and output devices support the streaming I/O method when the +V4L2_CAP_STREAMING flag in the +capabilities field of &v4l2-capability; returned by +the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through +DMABUF file descriptors is supported is determined by calling the +&VIDIOC-REQBUFS; ioctl with the memory type set to +V4L2_MEMORY_DMABUF. + + This I/O method is dedicated to sharing DMA buffers between different +devices, which may be V4L devices or other video-related devices (e.g. DRM). +Buffers (planes) are allocated by a driver on behalf of an application. Next, +these buffers are exported to the application as file descriptors using an API +which is specific for an allocator driver. Only such file descriptor are +exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or +in &v4l2-plane; in the multi-planar API case). The driver must be switched +into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer +type. + + + Initiating streaming I/O with DMABUF file descriptors + + +&v4l2-requestbuffers; reqbuf; + +memset(&reqbuf, 0, sizeof (reqbuf)); +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; +reqbuf.memory = V4L2_MEMORY_DMABUF; +reqbuf.count = 1; + +if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { + if (errno == EINVAL) + printf("Video capturing or DMABUF streaming is not supported\n"); + else + perror("VIDIOC_REQBUFS"); + + exit(EXIT_FAILURE); +} + + + + The buffer (plane) file descriptor is passed on the fly with the +&VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be +associated with a different DMABUF descriptor. Although buffers are commonly +cycled, applications can pass a different DMABUF descriptor at each +VIDIOC_QBUF call. + + + Queueing DMABUF using single plane API + + +int buffer_queue(int v4lfd, int index, int dmafd) +{ + &v4l2-buffer; buf; + + memset(&buf, 0, sizeof buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_DMABUF; + buf.index = index; + buf.m.fd = dmafd; + + if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { + perror("VIDIOC_QBUF"); + return -1; + } + + return 0; +} + + + + + Queueing DMABUF using multi plane API + + +int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes) +{ + &v4l2-buffer; buf; + &v4l2-plane; planes[VIDEO_MAX_PLANES]; + int i; + + memset(&buf, 0, sizeof buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; + buf.memory = V4L2_MEMORY_DMABUF; + buf.index = index; + buf.m.planes = planes; + buf.length = n_planes; + + memset(&planes, 0, sizeof planes); + + for (i = 0; i < n_planes; ++i) + buf.m.planes[i].m.fd = dmafd[i]; + + if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { + perror("VIDIOC_QBUF"); + return -1; + } + + return 0; +} + + + + Captured or displayed buffers are dequeued with the +&VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any +time between the completion of the DMA and this ioctl. The memory is +also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or +when the device is closed. + + For capturing applications it is customary to enqueue a +number of empty buffers, to start capturing and enter the read loop. +Here the application waits until a filled buffer can be dequeued, and +re-enqueues the buffer when the data is no longer needed. Output +applications fill and enqueue buffers, when enough buffers are stacked +up output is started. In the write loop, when the application +runs out of free buffers it must wait until an empty buffer can be +dequeued and reused. Two methods exist to suspend execution of the +application until one or more buffers can be dequeued. By default +VIDIOC_DQBUF blocks when no buffer is in the +outgoing queue. When the O_NONBLOCK flag was +given to the &func-open; function, VIDIOC_DQBUF +returns immediately with an &EAGAIN; when no buffer is available. The +&func-select; and &func-poll; functions are always available. + + To start and stop capturing or displaying applications call the +&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that +VIDIOC_STREAMOFF removes all buffers from both queues and +unlocks all buffers as a side effect. Since there is no notion of doing +anything "now" on a multitasking system, if an application needs to synchronize +with another event it should examine the &v4l2-buffer; +timestamp of captured buffers, or set the field +before enqueuing buffers for output. + + Drivers implementing DMABUF importing I/O must support the +VIDIOC_REQBUFS, VIDIOC_QBUF, +VIDIOC_DQBUF, VIDIOC_STREAMON and +VIDIOC_STREAMOFF ioctls, and the +select() and poll() functions. + +
+
Asynchronous I/O @@ -672,6 +828,14 @@ memory, set by the application. See for details. in the length field of this v4l2_buffer structure. + + + int + fd + For the single-plane API and when +memory is V4L2_MEMORY_DMABUF this +is the file descriptor associated with a DMABUF buffer. + __u32 length @@ -743,6 +907,15 @@ should set this to 0. pointer to the memory allocated for this plane by an application. + + + int + fd + When the memory type in the containing &v4l2-buffer; is + V4L2_MEMORY_DMABUF, this is a file + descriptor associated with a DMABUF buffer, similar to the + fd field in &v4l2-buffer;. + __u32 data_offset @@ -964,6 +1137,12 @@ pointer I/O. 3 [to do] + + V4L2_MEMORY_DMABUF + 4 + The buffer is used for DMA shared +buffer I/O. + diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index a8cda1acacd..cd994367243 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -6,7 +6,8 @@ VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer I/O + Create buffers for Memory Mapped or User Pointer or DMA Buffer + I/O @@ -55,11 +56,11 @@ This ioctl is used to create buffers for memory -mapped or user pointer -I/O. It can be used as an alternative or in addition to the -VIDIOC_REQBUFS ioctl, when a tighter control over buffers -is required. This ioctl can be called multiple times to create buffers of -different sizes. +mapped or user pointer or DMA buffer I/O. It can be used as an alternative or in +addition to the VIDIOC_REQBUFS ioctl, when a tighter +control over buffers is required. This ioctl can be called multiple times to +create buffers of different sizes. To allocate device buffers applications initialize relevant fields of the v4l2_create_buffers structure. They set the @@ -109,7 +110,8 @@ information. __u32 memory Applications set this field to -V4L2_MEMORY_MMAP or +V4L2_MEMORY_MMAP, +V4L2_MEMORY_DMABUF or V4L2_MEMORY_USERPTR. See diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 2d37abefce1..3504a7f2f38 100644 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml @@ -109,6 +109,23 @@ they cannot be swapped out to disk. Buffers remain locked until dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or until the device is closed. + To enqueue a DMABUF buffer applications +set the memory field to +V4L2_MEMORY_DMABUF and the m.fd +field to a file descriptor associated with a DMABUF buffer. When the +multi-planar API is used the m.fd fields of the +passed array of &v4l2-plane; have to be used instead. When +VIDIOC_QBUF is called with a pointer to this structure the +driver sets the V4L2_BUF_FLAG_QUEUED flag and clears the +V4L2_BUF_FLAG_MAPPED and +V4L2_BUF_FLAG_DONE flags in the +flags field, or it returns an error code. This +ioctl locks the buffer. Locking a buffer means passing it to a driver for a +hardware access (usually DMA). If an application accesses (reads/writes) a +locked buffer then the result is undefined. Buffers remain locked until +dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or +until the device is closed. + Applications call the VIDIOC_DQBUF ioctl to dequeue a filled (capturing) or displayed (output) buffer from the driver's outgoing queue. They just set the diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml index 2b50ef2007f..78a06a9a5ec 100644 --- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml @@ -48,28 +48,30 @@ Description - This ioctl is used to initiate memory -mapped or user pointer -I/O. Memory mapped buffers are located in device memory and must be -allocated with this ioctl before they can be mapped into the -application's address space. User buffers are allocated by -applications themselves, and this ioctl is merely used to switch the -driver into user pointer I/O mode and to setup some internal structures. +This ioctl is used to initiate memory mapped, +user pointer or DMABUF based I/O. Memory mapped buffers are located in +device memory and must be allocated with this ioctl before they can be mapped +into the application's address space. User buffers are allocated by +applications themselves, and this ioctl is merely used to switch the driver +into user pointer I/O mode and to setup some internal structures. +Similarly, DMABUF buffers are allocated by applications through a device +driver, and this ioctl only configures the driver into DMABUF I/O mode without +performing any direct allocation. - To allocate device buffers applications initialize all -fields of the v4l2_requestbuffers structure. -They set the type field to the respective -stream or buffer type, the count field to -the desired number of buffers, memory -must be set to the requested I/O method and the reserved array -must be zeroed. When the ioctl -is called with a pointer to this structure the driver will attempt to allocate -the requested number of buffers and it stores the actual number -allocated in the count field. It can be -smaller than the number requested, even zero, when the driver runs out -of free memory. A larger number is also possible when the driver requires -more buffers to function correctly. For example video output requires at least two buffers, -one displayed and one filled by the application. + To allocate device buffers applications initialize all fields of the +v4l2_requestbuffers structure. They set the +type field to the respective stream or buffer type, +the count field to the desired number of buffers, +memory must be set to the requested I/O method and +the reserved array must be zeroed. When the ioctl is +called with a pointer to this structure the driver will attempt to allocate the +requested number of buffers and it stores the actual number allocated in the +count field. It can be smaller than the number +requested, even zero, when the driver runs out of free memory. A larger number +is also possible when the driver requires more buffers to function correctly. +For example video output requires at least two buffers, one displayed and one +filled by the application. When the I/O method is not supported the ioctl returns an &EINVAL;. @@ -102,7 +104,8 @@ as the &v4l2-format; type field. See __u32 memory Applications set this field to -V4L2_MEMORY_MMAP or +V4L2_MEMORY_MMAP, +V4L2_MEMORY_DMABUF or V4L2_MEMORY_USERPTR. See . -- cgit v1.2.3 From 19b6ef51640fb35666884c7b577b1a24a4be8e34 Mon Sep 17 00:00:00 2001 From: Tomasz Stanislawski Date: Thu, 14 Jun 2012 11:32:22 -0300 Subject: [media] Documentation: media: description of DMABUF exporting in V4L2 This patch adds description and usage examples for exporting DMABUF file descriptor in V4L2. Signed-off-by: Tomasz Stanislawski Signed-off-by: Kyungmin Park Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 3 + Documentation/DocBook/media/v4l/io.xml | 3 + Documentation/DocBook/media/v4l/v4l2.xml | 1 + Documentation/DocBook/media/v4l/vidioc-expbuf.xml | 212 ++++++++++++++++++++++ 4 files changed, 219 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/vidioc-expbuf.xml (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 50eb63024eb..3dd9e78815d 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2590,6 +2590,9 @@ ioctls. Importing DMABUF file descriptors as a new IO method described in . + + Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl. +
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index be0fad7e120..388a3403265 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -488,6 +488,9 @@ DMA buffer from userspace using a file descriptor previously exported for a different or the same device (known as the importer role), or both. This section describes the DMABUF importer role API in V4L2. + Refer to DMABUF exporting for +details about exporting V4L2 buffers as DMABUF file descriptors. + Input and output devices support the streaming I/O method when the V4L2_CAP_STREAMING flag in the capabilities field of &v4l2-capability; returned by diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 10ccde9d16d..4d110b1ad3e 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -543,6 +543,7 @@ and discussions on the V4L mailing list. &sub-enuminput; &sub-enumoutput; &sub-enumstd; + &sub-expbuf; &sub-g-audio; &sub-g-audioout; &sub-g-crop; diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml new file mode 100644 index 00000000000..72dfbd20a80 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml @@ -0,0 +1,212 @@ + + + + ioctl VIDIOC_EXPBUF + &manvol; + + + + VIDIOC_EXPBUF + Export a buffer as a DMABUF file descriptor. + + + + + + int ioctl + int fd + int request + struct v4l2_exportbuffer *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_EXPBUF + + + + argp + + + + + + + + + Description + + + Experimental + This is an experimental + interface and may change in the future. + + +This ioctl is an extension to the memory +mapping I/O method, therefore it is available only for +V4L2_MEMORY_MMAP buffers. It can be used to export a +buffer as a DMABUF file at any time after buffers have been allocated with the +&VIDIOC-REQBUFS; ioctl. + + To export a buffer, applications fill &v4l2-exportbuffer;. The + type field is set to the same buffer type as was +previously used with &v4l2-requestbuffers; type . +Applications must also set the index field. Valid +index numbers range from zero to the number of buffers allocated with +&VIDIOC-REQBUFS; (&v4l2-requestbuffers; count ) +minus one. For the multi-planar API, applications set the plane + field to the index of the plane to be exported. Valid planes +range from zero to the maximal number of valid planes for the currently active +format. For the single-planar API, applications must set plane + to zero. Additional flags may be posted in the +flags field. Refer to a manual for open() for details. +Currently only O_CLOEXEC is supported. All other fields must be set to zero. +In the case of multi-planar API, every plane is exported separately using +multiple VIDIOC_EXPBUF calls. + + After calling VIDIOC_EXPBUF the fd + field will be set by a driver. This is a DMABUF file +descriptor. The application may pass it to other DMABUF-aware devices. Refer to +DMABUF importing for details about importing +DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it +is no longer used to allow the associated memory to be reclaimed. + + + +
+ Examples + + + Exporting a buffer. + +int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd) +{ + &v4l2-exportbuffer; expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { + perror("VIDIOC_EXPBUF"); + return -1; + } + + *dmafd = expbuf.fd; + + return 0; +} + + + + + Exporting a buffer using the multi-planar API. + +int buffer_export_mp(int v4lfd, &v4l2-buf-type; bt, int index, + int dmafd[], int n_planes) +{ + int i; + + for (i = 0; i < n_planes; ++i) { + &v4l2-exportbuffer; expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + expbuf.plane = i; + if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { + perror("VIDIOC_EXPBUF"); + while (i) + close(dmafd[--i]); + return -1; + } + dmafd[i] = expbuf.fd; + } + + return 0; +} + + +
+ + + + + struct <structname>v4l2_exportbuffer</structname> + + &cs-str; + + + __u32 + type + Type of the buffer, same as &v4l2-format; +type or &v4l2-requestbuffers; +type, set by the application. See + + + __u32 + index + Number of the buffer, set by the application. This field is +only used for memory mapping I/O and can range from +zero to the number of buffers allocated with the &VIDIOC-REQBUFS; and/or +&VIDIOC-CREATE-BUFS; ioctls. + + + __u32 + plane + Index of the plane to be exported when using the +multi-planar API. Otherwise this value must be set to zero. + + + __u32 + flags + Flags for the newly created file, currently only +O_CLOEXEC is supported, refer to the manual of open() for more +details. + + + __s32 + fd + The DMABUF file descriptor associated with a buffer. Set by + the driver. + + + __u32 + reserved[11] + Reserved field for future use. Must be set to zero. + + + +
+ + + + + &return-value; + + + EINVAL + + A queue is not in MMAP mode or DMABUF exporting is not +supported or flags or type + or index or plane + fields are invalid. + + + + + + -- cgit v1.2.3 From 63a29f744fe1c19742039ce7526663a98f172f7e Mon Sep 17 00:00:00 2001 From: Greg Kroah-Hartman Date: Fri, 21 Dec 2012 15:15:02 -0800 Subject: Documentation: remove __dev* attributes. CONFIG_HOTPLUG is going away as an option. As a result, the __dev* markings need to be removed. This change removes the use of __devinit, __devexit_p, __devinitdata, __devinitconst, and __devexit from the kernel documentation. Based on patches originally written by Bill Pemberton, but redone by me in order to handle some of the coding style issues better, by hand. Cc: Bill Pemberton Signed-off-by: Greg Kroah-Hartman --- Documentation/DocBook/media/v4l/driver.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/DocBook/media/v4l') diff --git a/Documentation/DocBook/media/v4l/driver.xml b/Documentation/DocBook/media/v4l/driver.xml index eacafe312cd..7c6638baced 100644 --- a/Documentation/DocBook/media/v4l/driver.xml +++ b/Documentation/DocBook/media/v4l/driver.xml @@ -116,7 +116,7 @@ my_suspend (struct pci_dev * pci_dev, return 0; /* a negative value on error, 0 on success. */ } -static void __devexit +static void my_remove (struct pci_dev * pci_dev) { my_device *my = pci_get_drvdata (pci_dev); @@ -124,7 +124,7 @@ my_remove (struct pci_dev * pci_dev) /* Describe me. */ } -static int __devinit +static int my_probe (struct pci_dev * pci_dev, const struct pci_device_id * pci_id) { @@ -157,7 +157,7 @@ my_pci_driver = { .id_table = my_pci_device_ids, .probe = my_probe, - .remove = __devexit_p (my_remove), + .remove = my_remove, /* Power management functions. */ .suspend = my_suspend, -- cgit v1.2.3