doc/spec/r13696.htm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>ioctl VIDIOC_REQBUFS</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Video for Linux Two API Specification"
HREF="book1.htm"><LINK
REL="UP"
TITLE="Function Reference"
HREF="r7624.htm"><LINK
REL="PREVIOUS"
TITLE="ioctl VIDIOC_QUERYSTD"
HREF="r13641.htm"><LINK
REL="NEXT"
TITLE="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"
HREF="r13817.htm"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Video for Linux Two API Specification: Revision 0.24</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="r13641.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="r13817.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="VIDIOC-REQBUFS"
></A
>ioctl VIDIOC_REQBUFS</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN13700"
></A
><H2
>Name</H2
>VIDIOC_REQBUFS&nbsp;--&nbsp;Initiate Memory Mapping or User Pointer I/O</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN13703"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN13704"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_requestbuffers *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN13714"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="PARAMETER"
>fd</CODE
></DT
><DD
><P
>File descriptor returned by <A
HREF="r14090.htm"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><CODE
CLASS="PARAMETER"
>request</CODE
></DT
><DD
><P
>VIDIOC_REQBUFS</P
></DD
><DT
><CODE
CLASS="PARAMETER"
>argp</CODE
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN13734"
></A
><H2
>Description</H2
><P
>This ioctl is used to initiate <A
HREF="x5791.htm"
>memory
mapped</A
> or <A
HREF="x5884.htm"
>user pointer</A
>
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.</P
><P
>To allocate device buffers applications initialize three
fields of a <CODE
CLASS="STRUCTNAME"
>v4l2_requestbuffers</CODE
> structure.
They set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field to the respective
stream or buffer type, the <CODE
CLASS="STRUCTFIELD"
>count</CODE
> field to
the desired number of buffers, and <CODE
CLASS="STRUCTFIELD"
>memory</CODE
>
must be set to <CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
>. 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 <CODE
CLASS="STRUCTFIELD"
>count</CODE
> 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.<A
NAME="AEN13746"
HREF="r13696.htm#FTN.AEN13746"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
> When memory mapping I/O is not supported the ioctl
returns an <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><P
>Applications can call <CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
>
again to change the number of buffers, however this cannot succeed
when any buffers are still mapped. A <CODE
CLASS="STRUCTFIELD"
>count</CODE
>
value of zero frees all buffers, after aborting or finishing any DMA
in progress, an implicit <A
HREF="r13817.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
></A
>. </P
><P
>To negotiate user pointer I/O, applications initialize only
the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field and set
<CODE
CLASS="STRUCTFIELD"
>memory</CODE
> to
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_USERPTR</CODE
>. 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
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-REQUESTBUFFERS"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_requestbuffers</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
VALIGN="TOP"
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>count</CODE
></TD
><TD
>The number of buffers requested or granted. This
field is only used when <CODE
CLASS="STRUCTFIELD"
>memory</CODE
> is set to
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
>.</TD
></TR
><TR
><TD
>enum&nbsp;<A
HREF="x5953.htm#V4L2-BUF-TYPE"
>v4l2_buf_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Type of the stream or buffers, this is the same
as the struct&nbsp;<A
HREF="r10944.htm#V4L2-FORMAT"
>v4l2_format</A
> <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field. See <A
HREF="x5953.htm#V4L2-BUF-TYPE"
>Table 3-2</A
> for valid values.</TD
></TR
><TR
><TD
>enum&nbsp;<A
HREF="x5953.htm#V4L2-MEMORY"
>v4l2_memory</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>memory</CODE
></TD
><TD
>Applications set this field to
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_MEMORY_USERPTR</CODE
>.</TD
></TR
><TR
><TD
>__u32</TD
><TD
><CODE
CLASS="STRUCTFIELD"
>reserved</CODE
>[2]</TD
><TD
>A place holder for future extensions and custom
(driver defined) buffer types <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
> and
higher.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN13798"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and the <CODE
CLASS="VARNAME"
>errno</CODE
> variable is set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EBUSY</SPAN
></DT
><DD
><P
>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.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The buffer type (<CODE
CLASS="STRUCTFIELD"
>type</CODE
> field) or the
requested I/O method (<CODE
CLASS="STRUCTFIELD"
>memory</CODE
>) is not
supported.</P
></DD
></DL
></DIV
></DIV
><H2
CLASS="FOOTNOTES"
>Notes</H2
><TABLE
BORDER="0"
CLASS="FOOTNOTES"
WIDTH="100%"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN13746"
HREF="r13696.htm#AEN13746"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>For example video output requires at least two buffers,
one displayed and one filled by the application.</P
></TD
></TR
></TABLE
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="r13641.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.htm"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="r13817.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>ioctl VIDIOC_QUERYSTD</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="r7624.htm"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>