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