|
| 1 | +<refentry id="vidioc-create-bufs"> |
| 2 | + <refmeta> |
| 3 | + <refentrytitle>ioctl VIDIOC_CREATE_BUFS</refentrytitle> |
| 4 | + &manvol; |
| 5 | + </refmeta> |
| 6 | + |
| 7 | + <refnamediv> |
| 8 | + <refname>VIDIOC_CREATE_BUFS</refname> |
| 9 | + <refpurpose>Create buffers for Memory Mapped 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_create_buffers *<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_CREATE_BUFS</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 create buffers for <link linkend="mmap">memory |
| 52 | +mapped</link> or <link linkend="userp">user pointer</link> |
| 53 | +I/O. It can be used as an alternative or in addition to the |
| 54 | +<constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter control over buffers |
| 55 | +is required. This ioctl can be called multiple times to create buffers of |
| 56 | +different sizes.</para> |
| 57 | + |
| 58 | + <para>To allocate device buffers applications initialize relevant fields of |
| 59 | +the <structname>v4l2_create_buffers</structname> structure. They set the |
| 60 | +<structfield>type</structfield> field in the |
| 61 | +<structname>v4l2_format</structname> structure, embedded in this |
| 62 | +structure, to the respective stream or buffer type. |
| 63 | +<structfield>count</structfield> must be set to the number of required buffers. |
| 64 | +<structfield>memory</structfield> specifies the required I/O method. The |
| 65 | +<structfield>format</structfield> field shall typically be filled in using |
| 66 | +either the <constant>VIDIOC_TRY_FMT</constant> or |
| 67 | +<constant>VIDIOC_G_FMT</constant> ioctl(). Additionally, applications can adjust |
| 68 | +<structfield>sizeimage</structfield> fields to fit their specific needs. The |
| 69 | +<structfield>reserved</structfield> array must be zeroed.</para> |
| 70 | + |
| 71 | + <para>When the ioctl is called with a pointer to this structure the driver |
| 72 | +will attempt to allocate up to the requested number of buffers and store the |
| 73 | +actual number allocated and the starting index in the |
| 74 | +<structfield>count</structfield> and the <structfield>index</structfield> fields |
| 75 | +respectively. On return <structfield>count</structfield> can be smaller than |
| 76 | +the number requested. The driver may also increase buffer sizes if required, |
| 77 | +however, it will not update <structfield>sizeimage</structfield> field values. |
| 78 | +The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that |
| 79 | +information.</para> |
| 80 | + |
| 81 | + <table pgwide="1" frame="none" id="v4l2-create-buffers"> |
| 82 | + <title>struct <structname>v4l2_create_buffers</structname></title> |
| 83 | + <tgroup cols="3"> |
| 84 | + &cs-str; |
| 85 | + <tbody valign="top"> |
| 86 | + <row> |
| 87 | + <entry>__u32</entry> |
| 88 | + <entry><structfield>index</structfield></entry> |
| 89 | + <entry>The starting buffer index, returned by the driver.</entry> |
| 90 | + </row> |
| 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>&v4l2-memory;</entry> |
| 98 | + <entry><structfield>memory</structfield></entry> |
| 99 | + <entry>Applications set this field to |
| 100 | +<constant>V4L2_MEMORY_MMAP</constant> or |
| 101 | +<constant>V4L2_MEMORY_USERPTR</constant>.</entry> |
| 102 | + </row> |
| 103 | + <row> |
| 104 | + <entry>&v4l2-format;</entry> |
| 105 | + <entry><structfield>format</structfield></entry> |
| 106 | + <entry>Filled in by the application, preserved by the driver.</entry> |
| 107 | + </row> |
| 108 | + <row> |
| 109 | + <entry>__u32</entry> |
| 110 | + <entry><structfield>reserved</structfield>[8]</entry> |
| 111 | + <entry>A place holder for future extensions.</entry> |
| 112 | + </row> |
| 113 | + </tbody> |
| 114 | + </tgroup> |
| 115 | + </table> |
| 116 | + </refsect1> |
| 117 | + |
| 118 | + <refsect1> |
| 119 | + &return-value; |
| 120 | + |
| 121 | + <variablelist> |
| 122 | + <varlistentry> |
| 123 | + <term><errorcode>ENOMEM</errorcode></term> |
| 124 | + <listitem> |
| 125 | + <para>No memory to allocate buffers for <link linkend="mmap">memory |
| 126 | +mapped</link> I/O.</para> |
| 127 | + </listitem> |
| 128 | + </varlistentry> |
| 129 | + <varlistentry> |
| 130 | + <term><errorcode>EINVAL</errorcode></term> |
| 131 | + <listitem> |
| 132 | + <para>The buffer type (<structfield>type</structfield> field) or the |
| 133 | +requested I/O method (<structfield>memory</structfield>) is not |
| 134 | +supported.</para> |
| 135 | + </listitem> |
| 136 | + </varlistentry> |
| 137 | + </variablelist> |
| 138 | + </refsect1> |
| 139 | +</refentry> |
0 commit comments