diff options
Diffstat (limited to 'Documentation/DocBook/v4l/vidioc-reqbufs.xml')
| -rw-r--r-- | Documentation/DocBook/v4l/vidioc-reqbufs.xml | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/v4l/vidioc-reqbufs.xml new file mode 100644 index 000000000000..bab38084454f --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-reqbufs.xml @@ -0,0 +1,160 @@ +<refentry id="vidioc-reqbufs"> + <refmeta> + <refentrytitle>ioctl VIDIOC_REQBUFS</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_REQBUFS</refname> + <refpurpose>Initiate Memory Mapping 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_requestbuffers *<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_REQBUFS</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 initiate <link linkend="mmap">memory +mapped</link> or <link linkend="userp">user pointer</link> +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.</para> + + <para>To allocate device buffers applications initialize three +fields of a <structname>v4l2_requestbuffers</structname> structure. +They set the <structfield>type</structfield> field to the respective +stream or buffer type, the <structfield>count</structfield> field to +the desired number of buffers, and <structfield>memory</structfield> +must be set to <constant>V4L2_MEMORY_MMAP</constant>. When the ioctl +is called with a pointer to this structure the driver attempts to +allocate the requested number of buffers and stores the actual number +allocated in the <structfield>count</structfield> field. It can be +smaller than the number requested, even zero, when the driver runs out +of free memory. A larger number is possible when the driver requires +more buffers to function correctly.<footnote> + <para>For example video output requires at least two buffers, +one displayed and one filled by the application.</para> + </footnote> When memory mapping I/O is not supported the ioctl +returns an &EINVAL;.</para> + + <para>Applications can call <constant>VIDIOC_REQBUFS</constant> +again to change the number of buffers, however this cannot succeed +when any buffers are still mapped. A <structfield>count</structfield> +value of zero frees all buffers, after aborting or finishing any DMA +in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no +reason why munmap()ping one or even all buffers must imply +streamoff.--></para> + + <para>To negotiate user pointer I/O, applications initialize only +the <structfield>type</structfield> field and set +<structfield>memory</structfield> to +<constant>V4L2_MEMORY_USERPTR</constant>. When the ioctl is called +with a pointer to this structure the driver prepares for user pointer +I/O, when this I/O method is not supported the ioctl returns an +&EINVAL;.</para> + + <table pgwide="1" frame="none" id="v4l2-requestbuffers"> + <title>struct <structname>v4l2_requestbuffers</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>count</structfield></entry> + <entry>The number of buffers requested or granted. This +field is only used when <structfield>memory</structfield> is set to +<constant>V4L2_MEMORY_MMAP</constant>.</entry> + </row> + <row> + <entry>&v4l2-buf-type;</entry> + <entry><structfield>type</structfield></entry> + <entry>Type of the stream or buffers, this is the same +as the &v4l2-format; <structfield>type</structfield> field. See <xref + linkend="v4l2-buf-type" /> for valid values.</entry> + </row> + <row> + <entry>&v4l2-memory;</entry> + <entry><structfield>memory</structfield></entry> + <entry>Applications set this field to +<constant>V4L2_MEMORY_MMAP</constant> or +<constant>V4L2_MEMORY_USERPTR</constant>.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[2]</entry> + <entry>A place holder for future extensions and custom +(driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and +higher.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> + <listitem> + <para>The driver supports multiple opens and I/O is already +in progress, or reallocation of buffers was attempted although one or +more are still mapped.</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> + +<!-- +Local Variables: +mode: sgml +sgml-parent-document: "v4l2.sgml" +indent-tabs-mode: nil +End: +--> |