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 >V4L2 mmap()</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_STREAMON, VIDIOC_STREAMOFF"
     17 HREF="r13817.htm"><LINK
     18 REL="NEXT"
     19 TITLE="V4L2 munmap()"
     20 HREF="r14037.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="r13817.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="r14037.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="FUNC-MMAP"
     74 ></A
     75 >V4L2 mmap()</H1
     76 ><DIV
     77 CLASS="REFNAMEDIV"
     78 ><A
     79 NAME="AEN13893"
     80 ></A
     81 ><H2
     82 >Name</H2
     83 >v4l2-mmap&nbsp;--&nbsp;Map device memory into application address space</DIV
     84 ><DIV
     85 CLASS="REFSYNOPSISDIV"
     86 ><A
     87 NAME="AEN13896"
     88 ></A
     89 ><H2
     90 >Synopsis</H2
     91 ><DIV
     92 CLASS="FUNCSYNOPSIS"
     93 ><P
     94 ></P
     95 ><A
     96 NAME="AEN13897"
     97 ></A
     98 ><PRE
     99 CLASS="FUNCSYNOPSISINFO"
    100 >#include &lt;unistd.h&gt;
    101 #include &lt;sys/mman.h&gt;</PRE
    102 ><P
    103 ><CODE
    104 ><CODE
    105 CLASS="FUNCDEF"
    106 >void *mmap</CODE
    107 >(void *start, size_t length, int prot, int flags, int fd, off_t offset);</CODE
    108 ></P
    109 ><P
    110 ></P
    111 ></DIV
    112 ></DIV
    113 ><DIV
    114 CLASS="REFSECT1"
    115 ><A
    116 NAME="AEN13914"
    117 ></A
    118 ><H2
    119 >Arguments</H2
    120 ><P
    121 ></P
    122 ><DIV
    123 CLASS="VARIABLELIST"
    124 ><DL
    125 ><DT
    126 ><CODE
    127 CLASS="PARAMETER"
    128 >start</CODE
    129 ></DT
    130 ><DD
    131 ><P
    132 >Map the buffer to this address in the
    133 application's address space. When the <CODE
    134 CLASS="CONSTANT"
    135 >MAP_FIXED</CODE
    136 >
    137 flag is specified, <CODE
    138 CLASS="PARAMETER"
    139 >start</CODE
    140 > must be a multiple of the
    141 pagesize and mmap will fail when the specified address
    142 cannot be used. Use of this option is discouraged; applications should
    143 just specify a <CODE
    144 CLASS="CONSTANT"
    145 >NULL</CODE
    146 > pointer here.</P
    147 ></DD
    148 ><DT
    149 ><CODE
    150 CLASS="PARAMETER"
    151 >length</CODE
    152 ></DT
    153 ><DD
    154 ><P
    155 >Length of the memory area to map. This must be the
    156 same value as returned by the driver in the struct&nbsp;<A
    157 HREF="x5953.htm#V4L2-BUFFER"
    158 >v4l2_buffer</A
    159 >
    160 <CODE
    161 CLASS="STRUCTFIELD"
    162 >length</CODE
    163 > field.</P
    164 ></DD
    165 ><DT
    166 ><CODE
    167 CLASS="PARAMETER"
    168 >prot</CODE
    169 ></DT
    170 ><DD
    171 ><P
    172 >The <CODE
    173 CLASS="PARAMETER"
    174 >prot</CODE
    175 > argument describes the
    176 desired memory protection. Regardless of the device type and the
    177 direction of data exchange it should be set to
    178 <CODE
    179 CLASS="CONSTANT"
    180 >PROT_READ</CODE
    181 > | <CODE
    182 CLASS="CONSTANT"
    183 >PROT_WRITE</CODE
    184 >,
    185 permitting read and write access to image buffers. Drivers should
    186 support at least this combination of flags. Note the Linux
    187 <TT
    188 CLASS="FILENAME"
    189 >video-buf</TT
    190 > kernel module, which is used by the
    191 bttv, saa7134, saa7146, cx88 and vivi driver supports only
    192 <CODE
    193 CLASS="CONSTANT"
    194 >PROT_READ</CODE
    195 > | <CODE
    196 CLASS="CONSTANT"
    197 >PROT_WRITE</CODE
    198 >. When
    199 the driver does not support the desired protection the
    200 <CODE
    201 CLASS="FUNCTION"
    202 >mmap()</CODE
    203 > function fails.</P
    204 ><P
    205 >Note device memory accesses (e.&nbsp;g. the memory on a
    206 graphics card with video capturing hardware) may incur a performance
    207 penalty compared to main memory accesses, or reads may be
    208 significantly slower than writes or vice versa. Other I/O methods may
    209 be more efficient in this case.</P
    210 ></DD
    211 ><DT
    212 ><CODE
    213 CLASS="PARAMETER"
    214 >flags</CODE
    215 ></DT
    216 ><DD
    217 ><P
    218 >The <CODE
    219 CLASS="PARAMETER"
    220 >flags</CODE
    221 > parameter
    222 specifies the type of the mapped object, mapping options and whether
    223 modifications made to the mapped copy of the page are private to the
    224 process or are to be shared with other references.</P
    225 ><P
    226 ><CODE
    227 CLASS="CONSTANT"
    228 >MAP_FIXED</CODE
    229 > requests that the
    230 driver selects no other address than the one specified. If the
    231 specified address cannot be used, <CODE
    232 CLASS="FUNCTION"
    233 >mmap()</CODE
    234 > will fail. If
    235 <CODE
    236 CLASS="CONSTANT"
    237 >MAP_FIXED</CODE
    238 > is specified,
    239 <CODE
    240 CLASS="PARAMETER"
    241 >start</CODE
    242 > must be a multiple of the pagesize. Use
    243 of this option is discouraged.</P
    244 ><P
    245 >One of the <CODE
    246 CLASS="CONSTANT"
    247 >MAP_SHARED</CODE
    248 > or
    249 <CODE
    250 CLASS="CONSTANT"
    251 >MAP_PRIVATE</CODE
    252 > flags must be set.
    253 <CODE
    254 CLASS="CONSTANT"
    255 >MAP_SHARED</CODE
    256 > allows applications to share the
    257 mapped memory with other (e.&nbsp;g. child-) processes. Note the Linux
    258 <TT
    259 CLASS="FILENAME"
    260 >video-buf</TT
    261 > module which is used by the bttv,
    262 saa7134, saa7146, cx88 and vivi driver supports only
    263 <CODE
    264 CLASS="CONSTANT"
    265 >MAP_SHARED</CODE
    266 >. <CODE
    267 CLASS="CONSTANT"
    268 >MAP_PRIVATE</CODE
    269 >
    270 requests copy-on-write semantics. V4L2 applications should not set the
    271 <CODE
    272 CLASS="CONSTANT"
    273 >MAP_PRIVATE</CODE
    274 >, <CODE
    275 CLASS="CONSTANT"
    276 >MAP_DENYWRITE</CODE
    277 >,
    278 <CODE
    279 CLASS="CONSTANT"
    280 >MAP_EXECUTABLE</CODE
    281 > or <CODE
    282 CLASS="CONSTANT"
    283 >MAP_ANON</CODE
    284 >
    285 flag.</P
    286 ></DD
    287 ><DT
    288 ><CODE
    289 CLASS="PARAMETER"
    290 >fd</CODE
    291 ></DT
    292 ><DD
    293 ><P
    294 >File descriptor returned by <A
    295 HREF="r14090.htm"
    296 ><CODE
    297 CLASS="FUNCTION"
    298 >open()</CODE
    299 ></A
    300 >.</P
    301 ></DD
    302 ><DT
    303 ><CODE
    304 CLASS="PARAMETER"
    305 >offset</CODE
    306 ></DT
    307 ><DD
    308 ><P
    309 >Offset of the buffer in device memory. This must be the
    310 same value as returned by the driver in the struct&nbsp;<A
    311 HREF="x5953.htm#V4L2-BUFFER"
    312 >v4l2_buffer</A
    313 >
    314 <CODE
    315 CLASS="STRUCTFIELD"
    316 >m</CODE
    317 > union <CODE
    318 CLASS="STRUCTFIELD"
    319 >offset</CODE
    320 > field.</P
    321 ></DD
    322 ></DL
    323 ></DIV
    324 ></DIV
    325 ><DIV
    326 CLASS="REFSECT1"
    327 ><A
    328 NAME="AEN13982"
    329 ></A
    330 ><H2
    331 >Description</H2
    332 ><P
    333 >The <CODE
    334 CLASS="FUNCTION"
    335 >mmap()</CODE
    336 > function asks to map
    337 <CODE
    338 CLASS="PARAMETER"
    339 >length</CODE
    340 > bytes starting at
    341 <CODE
    342 CLASS="PARAMETER"
    343 >offset</CODE
    344 > in the memory of the device specified by
    345 <CODE
    346 CLASS="PARAMETER"
    347 >fd</CODE
    348 > into the application address space,
    349 preferably at address <CODE
    350 CLASS="PARAMETER"
    351 >start</CODE
    352 >. This latter
    353 address is a hint only, and is usually specified as 0.</P
    354 ><P
    355 >Suitable length and offset parameters are queried with the
    356 <A
    357 HREF="r13022.htm"
    358 ><CODE
    359 CLASS="CONSTANT"
    360 >VIDIOC_QUERYBUF</CODE
    361 ></A
    362 > ioctl. Buffers must be allocated with the
    363 <A
    364 HREF="r13696.htm"
    365 ><CODE
    366 CLASS="CONSTANT"
    367 >VIDIOC_REQBUFS</CODE
    368 ></A
    369 > ioctl before they can be queried.</P
    370 ><P
    371 >To unmap buffers the <A
    372 HREF="r14037.htm"
    373 ><CODE
    374 CLASS="FUNCTION"
    375 >munmap()</CODE
    376 ></A
    377 > function is used.</P
    378 ></DIV
    379 ><DIV
    380 CLASS="REFSECT1"
    381 ><A
    382 NAME="AEN13998"
    383 ></A
    384 ><H2
    385 >Return Value</H2
    386 ><P
    387 >On success <CODE
    388 CLASS="FUNCTION"
    389 >mmap()</CODE
    390 > returns a pointer to
    391 the mapped buffer. On error <CODE
    392 CLASS="CONSTANT"
    393 >MAP_FAILED</CODE
    394 > (-1) is
    395 returned, and the <CODE
    396 CLASS="VARNAME"
    397 >errno</CODE
    398 > variable is set
    399 appropriately. Possible error codes are:</P
    400 ><P
    401 ></P
    402 ><DIV
    403 CLASS="VARIABLELIST"
    404 ><DL
    405 ><DT
    406 ><SPAN
    407 CLASS="ERRORCODE"
    408 >EBADF</SPAN
    409 ></DT
    410 ><DD
    411 ><P
    412 ><CODE
    413 CLASS="PARAMETER"
    414 >fd</CODE
    415 > is not a valid file
    416 descriptor.</P
    417 ></DD
    418 ><DT
    419 ><SPAN
    420 CLASS="ERRORCODE"
    421 >EACCES</SPAN
    422 ></DT
    423 ><DD
    424 ><P
    425 ><CODE
    426 CLASS="PARAMETER"
    427 >fd</CODE
    428 > is
    429 not open for reading and writing.</P
    430 ></DD
    431 ><DT
    432 ><SPAN
    433 CLASS="ERRORCODE"
    434 >EINVAL</SPAN
    435 ></DT
    436 ><DD
    437 ><P
    438 >The <CODE
    439 CLASS="PARAMETER"
    440 >start</CODE
    441 > or
    442 <CODE
    443 CLASS="PARAMETER"
    444 >length</CODE
    445 > or <CODE
    446 CLASS="PARAMETER"
    447 >offset</CODE
    448 > are not
    449 suitable. (E.&nbsp;g. they are too large, or not aligned on a
    450 <CODE
    451 CLASS="CONSTANT"
    452 >PAGESIZE</CODE
    453 > boundary.)</P
    454 ><P
    455 >The <CODE
    456 CLASS="PARAMETER"
    457 >flags</CODE
    458 > or
    459 <CODE
    460 CLASS="PARAMETER"
    461 >prot</CODE
    462 > value is not supported.</P
    463 ><P
    464 >No buffers have been allocated with the
    465 <A
    466 HREF="r13696.htm"
    467 ><CODE
    468 CLASS="CONSTANT"
    469 >VIDIOC_REQBUFS</CODE
    470 ></A
    471 > ioctl.</P
    472 ></DD
    473 ><DT
    474 ><SPAN
    475 CLASS="ERRORCODE"
    476 >ENOMEM</SPAN
    477 ></DT
    478 ><DD
    479 ><P
    480 >Not enough physical or virtual memory was available to
    481 complete the request.</P
    482 ></DD
    483 ></DL
    484 ></DIV
    485 ></DIV
    486 ><DIV
    487 CLASS="NAVFOOTER"
    488 ><HR
    489 ALIGN="LEFT"
    490 WIDTH="100%"><TABLE
    491 SUMMARY="Footer navigation table"
    492 WIDTH="100%"
    493 BORDER="0"
    494 CELLPADDING="0"
    495 CELLSPACING="0"
    496 ><TR
    497 ><TD
    498 WIDTH="33%"
    499 ALIGN="left"
    500 VALIGN="top"
    501 ><A
    502 HREF="r13817.htm"
    503 ACCESSKEY="P"
    504 >Prev</A
    505 ></TD
    506 ><TD
    507 WIDTH="34%"
    508 ALIGN="center"
    509 VALIGN="top"
    510 ><A
    511 HREF="book1.htm"
    512 ACCESSKEY="H"
    513 >Home</A
    514 ></TD
    515 ><TD
    516 WIDTH="33%"
    517 ALIGN="right"
    518 VALIGN="top"
    519 ><A
    520 HREF="r14037.htm"
    521 ACCESSKEY="N"
    522 >Next</A
    523 ></TD
    524 ></TR
    525 ><TR
    526 ><TD
    527 WIDTH="33%"
    528 ALIGN="left"
    529 VALIGN="top"
    530 >ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</TD
    531 ><TD
    532 WIDTH="34%"
    533 ALIGN="center"
    534 VALIGN="top"
    535 ><A
    536 HREF="r7624.htm"
    537 ACCESSKEY="U"
    538 >Up</A
    539 ></TD
    540 ><TD
    541 WIDTH="33%"
    542 ALIGN="right"
    543 VALIGN="top"
    544 >V4L2 munmap()</TD
    545 ></TR
    546 ></TABLE
    547 ></DIV
    548 ></BODY
    549 ></HTML
    550 >
    551