Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.
1 <refentry id="vidioc-reqbufs"> 2 <refmeta> 3 <refentrytitle>ioctl VIDIOC_REQBUFS</refentrytitle> 4 &manvol; 5 </refmeta> 6 7 <refnamediv> 8 <refname>VIDIOC_REQBUFS</refname> 9 <refpurpose>Initiate Memory Mapping or User Pointer I/O</refpurpose> 10 </refnamediv> 11 12 <refsynopsisdiv> 13 <funcsynopsis> 14 <funcprototype> 15 <funcdef>int <function>ioctl</function></funcdef> 16 <paramdef>int <parameter>fd</parameter></paramdef> 17 <paramdef>int <parameter>request</parameter></paramdef> 18 <paramdef>struct v4l2_requestbuffers *<parameter>argp</parameter></paramdef> 19 </funcprototype> 20 </funcsynopsis> 21 </refsynopsisdiv> 22 23 <refsect1> 24 <title>Arguments</title> 25 26 <variablelist> 27 <varlistentry> 28 <term><parameter>fd</parameter></term> 29 <listitem> 30 <para>&fd;</para> 31 </listitem> 32 </varlistentry> 33 <varlistentry> 34 <term><parameter>request</parameter></term> 35 <listitem> 36 <para>VIDIOC_REQBUFS</para> 37 </listitem> 38 </varlistentry> 39 <varlistentry> 40 <term><parameter>argp</parameter></term> 41 <listitem> 42 <para></para> 43 </listitem> 44 </varlistentry> 45 </variablelist> 46 </refsect1> 47 48 <refsect1> 49 <title>Description</title> 50 51 <para>This ioctl is used to initiate <link linkend="mmap">memory mapped</link>, 52 <link linkend="userp">user pointer</link> or <link 53 linkend="dmabuf">DMABUF</link> based I/O. Memory mapped buffers are located in 54 device memory and must be allocated with this ioctl before they can be mapped 55 into the application's address space. User buffers are allocated by 56 applications themselves, and this ioctl is merely used to switch the driver 57 into user pointer I/O mode and to setup some internal structures. 58 Similarly, DMABUF buffers are allocated by applications through a device 59 driver, and this ioctl only configures the driver into DMABUF I/O mode without 60 performing any direct allocation.</para> 61 62 <para>To allocate device buffers applications initialize all fields of the 63 <structname>v4l2_requestbuffers</structname> structure. They set the 64 <structfield>type</structfield> field to the respective stream or buffer type, 65 the <structfield>count</structfield> field to the desired number of buffers, 66 <structfield>memory</structfield> must be set to the requested I/O method and 67 the <structfield>reserved</structfield> array must be zeroed. When the ioctl is 68 called with a pointer to this structure the driver will attempt to allocate the 69 requested number of buffers and it stores the actual number allocated in the 70 <structfield>count</structfield> field. It can be smaller than the number 71 requested, even zero, when the driver runs out of free memory. A larger number 72 is also possible when the driver requires more buffers to function correctly. 73 For example video output requires at least two buffers, one displayed and one 74 filled by the application.</para> 75 <para>When the I/O method is not supported the ioctl 76 returns an &EINVAL;.</para> 77 78 <para>Applications can call <constant>VIDIOC_REQBUFS</constant> 79 again to change the number of buffers, however this cannot succeed 80 when any buffers are still mapped. A <structfield>count</structfield> 81 value of zero frees all buffers, after aborting or finishing any DMA 82 in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no 83 reason why munmap()ping one or even all buffers must imply 84 streamoff.--></para> 85 86 <table pgwide="1" frame="none" id="v4l2-requestbuffers"> 87 <title>struct <structname>v4l2_requestbuffers</structname></title> 88 <tgroup cols="3"> 89 &cs-str; 90 <tbody valign="top"> 91 <row> 92 <entry>__u32</entry> 93 <entry><structfield>count</structfield></entry> 94 <entry>The number of buffers requested or granted.</entry> 95 </row> 96 <row> 97 <entry>__u32</entry> 98 <entry><structfield>type</structfield></entry> 99 <entry>Type of the stream or buffers, this is the same 100 as the &v4l2-format; <structfield>type</structfield> field. See <xref 101 linkend="v4l2-buf-type" /> for valid values.</entry> 102 </row> 103 <row> 104 <entry>__u32</entry> 105 <entry><structfield>memory</structfield></entry> 106 <entry>Applications set this field to 107 <constant>V4L2_MEMORY_MMAP</constant>, 108 <constant>V4L2_MEMORY_DMABUF</constant> or 109 <constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory" 110 />.</entry> 111 </row> 112 <row> 113 <entry>__u32</entry> 114 <entry><structfield>reserved</structfield>[2]</entry> 115 <entry>A place holder for future extensions. Drivers and applications 116 must set the array to zero.</entry> 117 </row> 118 </tbody> 119 </tgroup> 120 </table> 121 </refsect1> 122 123 <refsect1> 124 &return-value; 125 126 <variablelist> 127 <varlistentry> 128 <term><errorcode>EINVAL</errorcode></term> 129 <listitem> 130 <para>The buffer type (<structfield>type</structfield> field) or the 131 requested I/O method (<structfield>memory</structfield>) is not 132 supported.</para> 133 </listitem> 134 </varlistentry> 135 </variablelist> 136 </refsect1> 137 </refentry>
