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