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