^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:: DTV.dmx
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. _dmx-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) Digital TV 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) dmx-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) .. warning:: this API is still experimental
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) #include <unistd.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) #include <sys/mman.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) .. 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 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) ``start``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Map the buffer to this address in the application's address space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) When the ``MAP_FIXED`` flag is specified, ``start`` must be a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) multiple of the pagesize and mmap will fail when the specified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) address cannot be used. Use of this option is discouraged;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) applications should just specify a ``NULL`` pointer here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) ``length``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Length of the memory area to map. This must be a multiple of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) DVB packet length (188, on most drivers).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) ``prot``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) The ``prot`` argument describes the desired memory protection.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Regardless of the device type and the direction of data exchange it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) and write access to image buffers. Drivers should support at least
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) this combination of flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) ``flags``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) The ``flags`` parameter specifies the type of the mapped object,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) mapping options and whether modifications made to the mapped copy of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) the page are private to the process or are to be shared with other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) references.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) ``MAP_FIXED`` requests that the driver selects no other address than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) the one specified. If the specified address cannot be used,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) ``start`` must be a multiple of the pagesize. Use of this option is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) discouraged.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) ``MAP_SHARED`` allows applications to share the mapped memory with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) other (e. g. child-) processes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) The Linux Digital TV applications should not set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) File descriptor returned by :c:func:`open()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) ``offset``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) Offset of the buffer in device memory, as returned by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) :ref:`DMX_QUERYBUF` ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) The :c:func:`mmap()` function asks to map ``length`` bytes starting at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) ``offset`` in the memory of the device specified by ``fd`` into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) application address space, preferably at address ``start``. This latter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) address is a hint only, and is usually specified as 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) Suitable length and offset parameters are queried with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) :ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) :ref:`DMX_REQBUFS` ioctl before they can be queried.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) To unmap buffers the :c:func:`munmap()` function is used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) Return Value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) On success :c:func:`mmap()` returns a pointer to the mapped buffer. On
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) appropriately. Possible error codes are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) EBADF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) ``fd`` is not a valid file descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) EACCES
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) ``fd`` is not open for reading and writing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) EINVAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) The ``start`` or ``length`` or ``offset`` are not suitable. (E. g.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) they are too large, or not aligned on a ``PAGESIZE`` boundary.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) The ``flags`` or ``prot`` value is not supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) No buffers have been allocated with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) :ref:`DMX_REQBUFS` ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) ENOMEM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Not enough physical or virtual memory was available to complete the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) request.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags