[media] Documentation: media: Clarify the VIDIOC_CREATE_BUFS format requirements
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> Signed-off-by: Mauro Carvalho Chehab <m.chehab@samsung.com>
This commit is contained in:
parent
5c7b25b90d
commit
c09aada7ac
|
@ -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>
|
||||
|
|
Loading…
Reference in a new issue