1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> 2<HTML 3><HEAD 4><TITLE 5>ioctl VIDIOC_REQBUFS</TITLE 6><META 7NAME="GENERATOR" 8CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK 9REL="HOME" 10TITLE="Video for Linux Two API Specification" 11HREF="book1.htm"><LINK 12REL="UP" 13TITLE="Function Reference" 14HREF="r7624.htm"><LINK 15REL="PREVIOUS" 16TITLE="ioctl VIDIOC_QUERYSTD" 17HREF="r13641.htm"><LINK 18REL="NEXT" 19TITLE="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF" 20HREF="r13817.htm"></HEAD 21><BODY 22CLASS="REFENTRY" 23BGCOLOR="#FFFFFF" 24TEXT="#000000" 25LINK="#0000FF" 26VLINK="#840084" 27ALINK="#0000FF" 28><DIV 29CLASS="NAVHEADER" 30><TABLE 31SUMMARY="Header navigation table" 32WIDTH="100%" 33BORDER="0" 34CELLPADDING="0" 35CELLSPACING="0" 36><TR 37><TH 38COLSPAN="3" 39ALIGN="center" 40>Video for Linux Two API Specification: Revision 0.24</TH 41></TR 42><TR 43><TD 44WIDTH="10%" 45ALIGN="left" 46VALIGN="bottom" 47><A 48HREF="r13641.htm" 49ACCESSKEY="P" 50>Prev</A 51></TD 52><TD 53WIDTH="80%" 54ALIGN="center" 55VALIGN="bottom" 56></TD 57><TD 58WIDTH="10%" 59ALIGN="right" 60VALIGN="bottom" 61><A 62HREF="r13817.htm" 63ACCESSKEY="N" 64>Next</A 65></TD 66></TR 67></TABLE 68><HR 69ALIGN="LEFT" 70WIDTH="100%"></DIV 71><H1 72><A 73NAME="VIDIOC-REQBUFS" 74></A 75>ioctl VIDIOC_REQBUFS</H1 76><DIV 77CLASS="REFNAMEDIV" 78><A 79NAME="AEN13700" 80></A 81><H2 82>Name</H2 83>VIDIOC_REQBUFS -- Initiate Memory Mapping or User Pointer I/O</DIV 84><DIV 85CLASS="REFSYNOPSISDIV" 86><A 87NAME="AEN13703" 88></A 89><H2 90>Synopsis</H2 91><DIV 92CLASS="FUNCSYNOPSIS" 93><P 94></P 95><A 96NAME="AEN13704" 97></A 98><P 99><CODE 100><CODE 101CLASS="FUNCDEF" 102>int ioctl</CODE 103>(int fd, int request, struct v4l2_requestbuffers *argp);</CODE 104></P 105><P 106></P 107></DIV 108></DIV 109><DIV 110CLASS="REFSECT1" 111><A 112NAME="AEN13714" 113></A 114><H2 115>Arguments</H2 116><P 117></P 118><DIV 119CLASS="VARIABLELIST" 120><DL 121><DT 122><CODE 123CLASS="PARAMETER" 124>fd</CODE 125></DT 126><DD 127><P 128>File descriptor returned by <A 129HREF="r14090.htm" 130><CODE 131CLASS="FUNCTION" 132>open()</CODE 133></A 134>.</P 135></DD 136><DT 137><CODE 138CLASS="PARAMETER" 139>request</CODE 140></DT 141><DD 142><P 143>VIDIOC_REQBUFS</P 144></DD 145><DT 146><CODE 147CLASS="PARAMETER" 148>argp</CODE 149></DT 150><DD 151><P 152></P 153></DD 154></DL 155></DIV 156></DIV 157><DIV 158CLASS="REFSECT1" 159><A 160NAME="AEN13734" 161></A 162><H2 163>Description</H2 164><P 165>This ioctl is used to initiate <A 166HREF="x5791.htm" 167>memory 168mapped</A 169> or <A 170HREF="x5884.htm" 171>user pointer</A 172> 173I/O. Memory mapped buffers are located in device memory and must be 174allocated with this ioctl before they can be mapped into the 175application's address space. User buffers are allocated by 176applications themselves, and this ioctl is merely used to switch the 177driver into user pointer I/O mode.</P 178><P 179>To allocate device buffers applications initialize three 180fields of a <CODE 181CLASS="STRUCTNAME" 182>v4l2_requestbuffers</CODE 183> structure. 184They set the <CODE 185CLASS="STRUCTFIELD" 186>type</CODE 187> field to the respective 188stream or buffer type, the <CODE 189CLASS="STRUCTFIELD" 190>count</CODE 191> field to 192the desired number of buffers, and <CODE 193CLASS="STRUCTFIELD" 194>memory</CODE 195> 196must be set to <CODE 197CLASS="CONSTANT" 198>V4L2_MEMORY_MMAP</CODE 199>. When the ioctl 200is called with a pointer to this structure the driver attempts to 201allocate the requested number of buffers and stores the actual number 202allocated in the <CODE 203CLASS="STRUCTFIELD" 204>count</CODE 205> field. It can be 206smaller than the number requested, even zero, when the driver runs out 207of free memory. A larger number is possible when the driver requires 208more buffers to function correctly.<A 209NAME="AEN13746" 210HREF="r13696.htm#FTN.AEN13746" 211><SPAN 212CLASS="footnote" 213>[1]</SPAN 214></A 215> When memory mapping I/O is not supported the ioctl 216returns an <SPAN 217CLASS="ERRORCODE" 218>EINVAL</SPAN 219> error code.</P 220><P 221>Applications can call <CODE 222CLASS="CONSTANT" 223>VIDIOC_REQBUFS</CODE 224> 225again to change the number of buffers, however this cannot succeed 226when any buffers are still mapped. A <CODE 227CLASS="STRUCTFIELD" 228>count</CODE 229> 230value of zero frees all buffers, after aborting or finishing any DMA 231in progress, an implicit <A 232HREF="r13817.htm" 233><CODE 234CLASS="CONSTANT" 235>VIDIOC_STREAMOFF</CODE 236></A 237>. </P 238><P 239>To negotiate user pointer I/O, applications initialize only 240the <CODE 241CLASS="STRUCTFIELD" 242>type</CODE 243> field and set 244<CODE 245CLASS="STRUCTFIELD" 246>memory</CODE 247> to 248<CODE 249CLASS="CONSTANT" 250>V4L2_MEMORY_USERPTR</CODE 251>. When the ioctl is called 252with a pointer to this structure the driver prepares for user pointer 253I/O, when this I/O method is not supported the ioctl returns an 254<SPAN 255CLASS="ERRORCODE" 256>EINVAL</SPAN 257> error code.</P 258><DIV 259CLASS="TABLE" 260><A 261NAME="V4L2-REQUESTBUFFERS" 262></A 263><P 264><B 265>Table 1. struct <CODE 266CLASS="STRUCTNAME" 267>v4l2_requestbuffers</CODE 268></B 269></P 270><TABLE 271BORDER="0" 272FRAME="void" 273WIDTH="100%" 274CLASS="CALSTABLE" 275><COL 276WIDTH="25%" 277TITLE="C1"><COL 278WIDTH="25%" 279TITLE="C2"><COL 280WIDTH="50%" 281TITLE="C3"><TBODY 282VALIGN="TOP" 283><TR 284><TD 285>__u32</TD 286><TD 287><CODE 288CLASS="STRUCTFIELD" 289>count</CODE 290></TD 291><TD 292>The number of buffers requested or granted. This 293field is only used when <CODE 294CLASS="STRUCTFIELD" 295>memory</CODE 296> is set to 297<CODE 298CLASS="CONSTANT" 299>V4L2_MEMORY_MMAP</CODE 300>.</TD 301></TR 302><TR 303><TD 304>enum <A 305HREF="x5953.htm#V4L2-BUF-TYPE" 306>v4l2_buf_type</A 307></TD 308><TD 309><CODE 310CLASS="STRUCTFIELD" 311>type</CODE 312></TD 313><TD 314>Type of the stream or buffers, this is the same 315as the struct <A 316HREF="r10944.htm#V4L2-FORMAT" 317>v4l2_format</A 318> <CODE 319CLASS="STRUCTFIELD" 320>type</CODE 321> field. See <A 322HREF="x5953.htm#V4L2-BUF-TYPE" 323>Table 3-2</A 324> for valid values.</TD 325></TR 326><TR 327><TD 328>enum <A 329HREF="x5953.htm#V4L2-MEMORY" 330>v4l2_memory</A 331></TD 332><TD 333><CODE 334CLASS="STRUCTFIELD" 335>memory</CODE 336></TD 337><TD 338>Applications set this field to 339<CODE 340CLASS="CONSTANT" 341>V4L2_MEMORY_MMAP</CODE 342> or 343<CODE 344CLASS="CONSTANT" 345>V4L2_MEMORY_USERPTR</CODE 346>.</TD 347></TR 348><TR 349><TD 350>__u32</TD 351><TD 352><CODE 353CLASS="STRUCTFIELD" 354>reserved</CODE 355>[2]</TD 356><TD 357>A place holder for future extensions and custom 358(driver defined) buffer types <CODE 359CLASS="CONSTANT" 360>V4L2_BUF_TYPE_PRIVATE</CODE 361> and 362higher.</TD 363></TR 364></TBODY 365></TABLE 366></DIV 367></DIV 368><DIV 369CLASS="REFSECT1" 370><A 371NAME="AEN13798" 372></A 373><H2 374>Return Value</H2 375><P 376>On success <SPAN 377CLASS="RETURNVALUE" 378>0</SPAN 379> is returned, on error <SPAN 380CLASS="RETURNVALUE" 381>-1</SPAN 382> and the <CODE 383CLASS="VARNAME" 384>errno</CODE 385> variable is set appropriately:</P 386><P 387></P 388><DIV 389CLASS="VARIABLELIST" 390><DL 391><DT 392><SPAN 393CLASS="ERRORCODE" 394>EBUSY</SPAN 395></DT 396><DD 397><P 398>The driver supports multiple opens and I/O is already 399in progress, or reallocation of buffers was attempted although one or 400more are still mapped.</P 401></DD 402><DT 403><SPAN 404CLASS="ERRORCODE" 405>EINVAL</SPAN 406></DT 407><DD 408><P 409>The buffer type (<CODE 410CLASS="STRUCTFIELD" 411>type</CODE 412> field) or the 413requested I/O method (<CODE 414CLASS="STRUCTFIELD" 415>memory</CODE 416>) is not 417supported.</P 418></DD 419></DL 420></DIV 421></DIV 422><H2 423CLASS="FOOTNOTES" 424>Notes</H2 425><TABLE 426BORDER="0" 427CLASS="FOOTNOTES" 428WIDTH="100%" 429><TR 430><TD 431ALIGN="LEFT" 432VALIGN="TOP" 433WIDTH="5%" 434><A 435NAME="FTN.AEN13746" 436HREF="r13696.htm#AEN13746" 437><SPAN 438CLASS="footnote" 439>[1]</SPAN 440></A 441></TD 442><TD 443ALIGN="LEFT" 444VALIGN="TOP" 445WIDTH="95%" 446><P 447>For example video output requires at least two buffers, 448one displayed and one filled by the application.</P 449></TD 450></TR 451></TABLE 452><DIV 453CLASS="NAVFOOTER" 454><HR 455ALIGN="LEFT" 456WIDTH="100%"><TABLE 457SUMMARY="Footer navigation table" 458WIDTH="100%" 459BORDER="0" 460CELLPADDING="0" 461CELLSPACING="0" 462><TR 463><TD 464WIDTH="33%" 465ALIGN="left" 466VALIGN="top" 467><A 468HREF="r13641.htm" 469ACCESSKEY="P" 470>Prev</A 471></TD 472><TD 473WIDTH="34%" 474ALIGN="center" 475VALIGN="top" 476><A 477HREF="book1.htm" 478ACCESSKEY="H" 479>Home</A 480></TD 481><TD 482WIDTH="33%" 483ALIGN="right" 484VALIGN="top" 485><A 486HREF="r13817.htm" 487ACCESSKEY="N" 488>Next</A 489></TD 490></TR 491><TR 492><TD 493WIDTH="33%" 494ALIGN="left" 495VALIGN="top" 496>ioctl VIDIOC_QUERYSTD</TD 497><TD 498WIDTH="34%" 499ALIGN="center" 500VALIGN="top" 501><A 502HREF="r7624.htm" 503ACCESSKEY="U" 504>Up</A 505></TD 506><TD 507WIDTH="33%" 508ALIGN="right" 509VALIGN="top" 510>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</TD 511></TR 512></TABLE 513></DIV 514></BODY 515></HTML 516> 517