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