mirror of
https://github.com/AuxXxilium/linux_dsm_epyc7002.git
synced 2024-12-28 11:18:45 +07:00
6016af82ea
V4L2 uses the enum type in IOCTL arguments in IOCTLs that were defined until the use of enum was considered less than ideal. Recently Rémi Denis-Courmont brought up the issue by proposing a patch to convert the enums to unsigned: <URL:http://www.spinics.net/lists/linux-media/msg46167.html> This sparked a long discussion where another solution to the issue was proposed: two sets of IOCTL structures, one with __u32 and the other with enums, and conversion code between the two: <URL:http://www.spinics.net/lists/linux-media/msg47168.html> Both approaches implement a complete solution that resolves the problem. The first one is simple but requires assuming enums and __u32 are the same in size (so we won't break the ABI) while the second one is more complex and less clean but does not require making that assumption. The issue boils down to whether enums are fundamentally different from __u32 or not, and can the former be substituted by the latter. During the discussion it was concluded that the __u32 has the same size as enums on all archs Linux is supported: it has not been shown that replacing those enums in IOCTL arguments would break neither source or binary compatibility. If no such reason is found, just replacing the enums with __u32s is the way to go. This is what this patch does. This patch is slightly different from Remi's first RFC (link above): it uses __u32 instead of unsigned and also changes the arguments of VIDIOC_G_PRIORITY and VIDIOC_S_PRIORITY. Signed-off-by: Rémi Denis-Courmont <remi@remlab.net> Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi> Acked-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
142 lines
4.7 KiB
XML
142 lines
4.7 KiB
XML
<refentry id="vidioc-create-bufs">
|
|
<refmeta>
|
|
<refentrytitle>ioctl VIDIOC_CREATE_BUFS</refentrytitle>
|
|
&manvol;
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>VIDIOC_CREATE_BUFS</refname>
|
|
<refpurpose>Create buffers for Memory Mapped or User Pointer I/O</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ioctl</function></funcdef>
|
|
<paramdef>int <parameter>fd</parameter></paramdef>
|
|
<paramdef>int <parameter>request</parameter></paramdef>
|
|
<paramdef>struct v4l2_create_buffers *<parameter>argp</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>fd</parameter></term>
|
|
<listitem>
|
|
<para>&fd;</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>request</parameter></term>
|
|
<listitem>
|
|
<para>VIDIOC_CREATE_BUFS</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>argp</parameter></term>
|
|
<listitem>
|
|
<para></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>This ioctl is used to create buffers for <link linkend="mmap">memory
|
|
mapped</link> or <link linkend="userp">user pointer</link>
|
|
I/O. It can be used as an alternative or in 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
|
|
<structname>v4l2_format</structname> 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>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
|
|
actual number allocated and the starting index in the
|
|
<structfield>count</structfield> and the <structfield>index</structfield> fields
|
|
respectively. On return <structfield>count</structfield> can be smaller than
|
|
the number requested. The driver may also increase buffer sizes if required,
|
|
however, it will not update <structfield>sizeimage</structfield> field values.
|
|
The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that
|
|
information.</para>
|
|
|
|
<table pgwide="1" frame="none" id="v4l2-create-buffers">
|
|
<title>struct <structname>v4l2_create_buffers</structname></title>
|
|
<tgroup cols="3">
|
|
&cs-str;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>index</structfield></entry>
|
|
<entry>The starting buffer index, returned by the driver.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>count</structfield></entry>
|
|
<entry>The number of buffers requested or granted.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>memory</structfield></entry>
|
|
<entry>Applications set this field to
|
|
<constant>V4L2_MEMORY_MMAP</constant> or
|
|
<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
|
|
/></entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>format</structfield></entry>
|
|
<entry>Filled in by the application, preserved by the driver.
|
|
See <xref linkend="v4l2-format" />.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>reserved</structfield>[8]</entry>
|
|
<entry>A place holder for future extensions.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
&return-value;
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><errorcode>ENOMEM</errorcode></term>
|
|
<listitem>
|
|
<para>No memory to allocate buffers for <link linkend="mmap">memory
|
|
mapped</link> I/O.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
</refentry>
|