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