diff mbox

[v6,02/10] Documentation: media: Clarify the VIDIOC_CREATE_BUFS format requirements

Message ID 1375725209-2674-3-git-send-email-laurent.pinchart+renesas@ideasonboard.com (mailing list archive)
State New, archived
Headers show

Commit Message

Laurent Pinchart Aug. 5, 2013, 5:53 p.m. UTC
The VIDIOC_CREATE_BUFS ioctl takes a format argument that must contain a
valid format supported by the driver. Clarify the documentation.

Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
---
 .../DocBook/media/v4l/vidioc-create-bufs.xml       | 41 ++++++++++++++--------
 1 file changed, 26 insertions(+), 15 deletions(-)

Comments

Hans Verkuil Aug. 6, 2013, 10:36 a.m. UTC | #1
On Mon 5 August 2013 19:53:21 Laurent Pinchart wrote:
> The VIDIOC_CREATE_BUFS ioctl takes a format argument that must contain a
> valid format supported by the driver. Clarify the documentation.
> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>

Regards,

	Hans

> ---
>  .../DocBook/media/v4l/vidioc-create-bufs.xml       | 41 ++++++++++++++--------
>  1 file changed, 26 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
> index cd99436..9b700a5 100644
> --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
> +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
> @@ -62,18 +62,29 @@ addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter
>  control over buffers is required. This ioctl can be called multiple times to
>  create buffers of different sizes.</para>
>  
> -    <para>To allocate device buffers applications initialize relevant fields of
> -the <structname>v4l2_create_buffers</structname> structure. They set the
> -<structfield>type</structfield> field in the
> -&v4l2-format; structure, embedded in this
> -structure, to the respective stream or buffer type.
> -<structfield>count</structfield> must be set to the number of required buffers.
> -<structfield>memory</structfield> specifies the required I/O method. The
> -<structfield>format</structfield> field shall typically be filled in using
> -either the <constant>VIDIOC_TRY_FMT</constant> or
> -<constant>VIDIOC_G_FMT</constant> ioctl(). Additionally, applications can adjust
> -<structfield>sizeimage</structfield> fields to fit their specific needs. The
> -<structfield>reserved</structfield> array must be zeroed.</para>
> +    <para>To allocate the device buffers applications must initialize the
> +relevant fields of the <structname>v4l2_create_buffers</structname> structure.
> +The <structfield>count</structfield> field must be set to the number of
> +requested buffers, the <structfield>memory</structfield> field specifies the
> +requested I/O method and the <structfield>reserved</structfield> array must be
> +zeroed.</para>
> +
> +    <para>The <structfield>format</structfield> field specifies the image format
> +that the buffers must be able to handle. The application has to fill in this
> +&v4l2-format;. Usually this will be done using the
> +<constant>VIDIOC_TRY_FMT</constant> or <constant>VIDIOC_G_FMT</constant> ioctl()
> +to ensure that the requested format is supported by the driver. Unsupported
> +formats will result in an error.</para>
> +
> +    <para>The buffers created by this ioctl will have as minimum size the size
> +defined by the <structfield>format.pix.sizeimage</structfield> field. If the
> +<structfield>format.pix.sizeimage</structfield> field is less than the minimum
> +required for the given format, then <structfield>sizeimage</structfield> will be
> +increased by the driver to that minimum to allocate the buffers. If it is
> +larger, then the value will be used as-is. The same applies to the
> +<structfield>sizeimage</structfield> field of the
> +<structname>v4l2_plane_pix_format</structname> structure in the case of
> +multiplanar formats.</para>
>  
>      <para>When the ioctl is called with a pointer to this structure the driver
>  will attempt to allocate up to the requested number of buffers and store the
> @@ -144,9 +155,9 @@ mapped</link> I/O.</para>
>        <varlistentry>
>  	<term><errorcode>EINVAL</errorcode></term>
>  	<listitem>
> -	  <para>The buffer type (<structfield>type</structfield> field) or the
> -requested I/O method (<structfield>memory</structfield>) is not
> -supported.</para>
> +	  <para>The buffer type (<structfield>format.type</structfield> field),
> +requested I/O method (<structfield>memory</structfield>) or format
> +(<structfield>format</structfield> field) is not valid.</para>
>  	</listitem>
>        </varlistentry>
>      </variablelist>
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
diff mbox

Patch

diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
index cd99436..9b700a5 100644
--- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
@@ -62,18 +62,29 @@  addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter
 control over buffers is required. This ioctl can be called multiple times to
 create buffers of different sizes.</para>
 
-    <para>To allocate device buffers applications initialize relevant fields of
-the <structname>v4l2_create_buffers</structname> structure. They set the
-<structfield>type</structfield> field in the
-&v4l2-format; structure, embedded in this
-structure, to the respective stream or buffer type.
-<structfield>count</structfield> must be set to the number of required buffers.
-<structfield>memory</structfield> specifies the required I/O method. The
-<structfield>format</structfield> field shall typically be filled in using
-either the <constant>VIDIOC_TRY_FMT</constant> or
-<constant>VIDIOC_G_FMT</constant> ioctl(). Additionally, applications can adjust
-<structfield>sizeimage</structfield> fields to fit their specific needs. The
-<structfield>reserved</structfield> array must be zeroed.</para>
+    <para>To allocate the device buffers applications must initialize the
+relevant fields of the <structname>v4l2_create_buffers</structname> structure.
+The <structfield>count</structfield> field must be set to the number of
+requested buffers, the <structfield>memory</structfield> field specifies the
+requested I/O method and the <structfield>reserved</structfield> array must be
+zeroed.</para>
+
+    <para>The <structfield>format</structfield> field specifies the image format
+that the buffers must be able to handle. The application has to fill in this
+&v4l2-format;. Usually this will be done using the
+<constant>VIDIOC_TRY_FMT</constant> or <constant>VIDIOC_G_FMT</constant> ioctl()
+to ensure that the requested format is supported by the driver. Unsupported
+formats will result in an error.</para>
+
+    <para>The buffers created by this ioctl will have as minimum size the size
+defined by the <structfield>format.pix.sizeimage</structfield> field. If the
+<structfield>format.pix.sizeimage</structfield> field is less than the minimum
+required for the given format, then <structfield>sizeimage</structfield> will be
+increased by the driver to that minimum to allocate the buffers. If it is
+larger, then the value will be used as-is. The same applies to the
+<structfield>sizeimage</structfield> field of the
+<structname>v4l2_plane_pix_format</structname> structure in the case of
+multiplanar formats.</para>
 
     <para>When the ioctl is called with a pointer to this structure the driver
 will attempt to allocate up to the requested number of buffers and store the
@@ -144,9 +155,9 @@  mapped</link> I/O.</para>
       <varlistentry>
 	<term><errorcode>EINVAL</errorcode></term>
 	<listitem>
-	  <para>The buffer type (<structfield>type</structfield> field) or the
-requested I/O method (<structfield>memory</structfield>) is not
-supported.</para>
+	  <para>The buffer type (<structfield>format.type</structfield> field),
+requested I/O method (<structfield>memory</structfield>) or format
+(<structfield>format</structfield> field) is not valid.</para>
 	</listitem>
       </varlistentry>
     </variablelist>