| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _func-mmap: |
| 5 |
|
| 6 |
*********** |
| 7 |
V4L2 mmap() |
| 8 |
*********** |
| 9 |
|
| 10 |
Name |
| 11 |
==== |
| 12 |
|
| 13 |
v4l2-mmap - Map device memory into application address space |
| 14 |
|
| 15 |
Synopsis |
| 16 |
======== |
| 17 |
|
| 18 |
.. code-block:: c |
| 19 |
|
| 20 |
#include <unistd.h> |
| 21 |
#include <sys/mman.h> |
| 22 |
|
| 23 |
.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) |
| 24 |
|
| 25 |
Arguments |
| 26 |
========= |
| 27 |
|
| 28 |
``start`` |
| 29 |
Map the buffer to this address in the application's address space. |
| 30 |
When the ``MAP_FIXED`` flag is specified, ``start`` must be a |
| 31 |
multiple of the pagesize and mmap will fail when the specified |
| 32 |
address cannot be used. Use of this option is discouraged; |
| 33 |
applications should just specify a ``NULL`` pointer here. |
| 34 |
|
| 35 |
``length`` |
| 36 |
Length of the memory area to map. This must be the same value as |
| 37 |
returned by the driver in the struct |
| 38 |
:c:type:`v4l2_buffer` ``length`` field for the |
| 39 |
single-planar API, and the same value as returned by the driver in |
| 40 |
the struct :c:type:`v4l2_plane` ``length`` field for |
| 41 |
the multi-planar API. |
| 42 |
|
| 43 |
``prot`` |
| 44 |
The ``prot`` argument describes the desired memory protection. |
| 45 |
Regardless of the device type and the direction of data exchange it |
| 46 |
should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read |
| 47 |
and write access to image buffers. Drivers should support at least |
| 48 |
this combination of flags. |
| 49 |
|
| 50 |
.. note:: |
| 51 |
|
| 52 |
#. The Linux ``videobuf`` kernel module, which is used by some |
| 53 |
drivers supports only ``PROT_READ`` | ``PROT_WRITE``. When the |
| 54 |
driver does not support the desired protection, the |
| 55 |
:c:func:`mmap()` function fails. |
| 56 |
|
| 57 |
#. Device memory accesses (e. g. the memory on a graphics card |
| 58 |
with video capturing hardware) may incur a performance penalty |
| 59 |
compared to main memory accesses, or reads may be significantly |
| 60 |
slower than writes or vice versa. Other I/O methods may be more |
| 61 |
efficient in such case. |
| 62 |
|
| 63 |
``flags`` |
| 64 |
The ``flags`` parameter specifies the type of the mapped object, |
| 65 |
mapping options and whether modifications made to the mapped copy of |
| 66 |
the page are private to the process or are to be shared with other |
| 67 |
references. |
| 68 |
|
| 69 |
``MAP_FIXED`` requests that the driver selects no other address than |
| 70 |
the one specified. If the specified address cannot be used, |
| 71 |
:c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified, |
| 72 |
``start`` must be a multiple of the pagesize. Use of this option is |
| 73 |
discouraged. |
| 74 |
|
| 75 |
One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set. |
| 76 |
``MAP_SHARED`` allows applications to share the mapped memory with |
| 77 |
other (e. g. child-) processes. |
| 78 |
|
| 79 |
.. note:: |
| 80 |
|
| 81 |
The Linux ``videobuf`` module which is used by some |
| 82 |
drivers supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests |
| 83 |
copy-on-write semantics. V4L2 applications should not set the |
| 84 |
``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` |
| 85 |
flags. |
| 86 |
|
| 87 |
``fd`` |
| 88 |
File descriptor returned by :c:func:`open()`. |
| 89 |
|
| 90 |
``offset`` |
| 91 |
Offset of the buffer in device memory. This must be the same value |
| 92 |
as returned by the driver in the struct |
| 93 |
:c:type:`v4l2_buffer` ``m`` union ``offset`` field for |
| 94 |
the single-planar API, and the same value as returned by the driver |
| 95 |
in the struct :c:type:`v4l2_plane` ``m`` union |
| 96 |
``mem_offset`` field for the multi-planar API. |
| 97 |
|
| 98 |
Description |
| 99 |
=========== |
| 100 |
|
| 101 |
The :c:func:`mmap()` function asks to map ``length`` bytes starting at |
| 102 |
``offset`` in the memory of the device specified by ``fd`` into the |
| 103 |
application address space, preferably at address ``start``. This latter |
| 104 |
address is a hint only, and is usually specified as 0. |
| 105 |
|
| 106 |
Suitable length and offset parameters are queried with the |
| 107 |
:ref:`VIDIOC_QUERYBUF` ioctl. Buffers must be |
| 108 |
allocated with the :ref:`VIDIOC_REQBUFS` ioctl |
| 109 |
before they can be queried. |
| 110 |
|
| 111 |
To unmap buffers the :c:func:`munmap()` function is used. |
| 112 |
|
| 113 |
Return Value |
| 114 |
============ |
| 115 |
|
| 116 |
On success :c:func:`mmap()` returns a pointer to the mapped buffer. On |
| 117 |
error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set |
| 118 |
appropriately. Possible error codes are: |
| 119 |
|
| 120 |
EBADF |
| 121 |
``fd`` is not a valid file descriptor. |
| 122 |
|
| 123 |
EACCES |
| 124 |
``fd`` is not open for reading and writing. |
| 125 |
|
| 126 |
EINVAL |
| 127 |
The ``start`` or ``length`` or ``offset`` are not suitable. (E. g. |
| 128 |
they are too large, or not aligned on a ``PAGESIZE`` boundary.) |
| 129 |
|
| 130 |
The ``flags`` or ``prot`` value is not supported. |
| 131 |
|
| 132 |
No buffers have been allocated with the |
| 133 |
:ref:`VIDIOC_REQBUFS` ioctl. |
| 134 |
|
| 135 |
ENOMEM |
| 136 |
Not enough physical or virtual memory was available to complete the |
| 137 |
request. |