diff options
author | Jens Axboe <axboe@kernel.dk> | 2018-02-07 15:54:20 -0700 |
---|---|---|
committer | Jens Axboe <axboe@kernel.dk> | 2018-02-07 15:54:20 -0700 |
commit | 61a695184fcc8f225327206b88320279dd8684af (patch) | |
tree | 6cbda2b0e7de94ebad95072d17cc0aa82c9d8ab3 /Documentation/media/uapi/dvb/dmx-mmap.rst | |
parent | 9e05c864993c5442227f83ae1694a737d7a102ed (diff) | |
parent | 581e400ff935d34d95811258586128bf11baef15 (diff) |
Merge branch 'master' into test
* master: (1190 commits)
ASoC: stm32: add of dependency for stm32 drivers
ASoC: mt8173-rt5650: fix child-node lookup
ASoC: dapm: fix debugfs read using path->connected
platform/x86: samsung-laptop: Re-use DEFINE_SHOW_ATTRIBUTE() macro
platform/x86: ideapad-laptop: Re-use DEFINE_SHOW_ATTRIBUTE() macro
platform/x86: dell-laptop: Re-use DEFINE_SHOW_ATTRIBUTE() macro
seq_file: Introduce DEFINE_SHOW_ATTRIBUTE() helper macro
Documentation/sysctl/user.txt: fix typo
MAINTAINERS: update ARM/QUALCOMM SUPPORT patterns
MAINTAINERS: update various PALM patterns
MAINTAINERS: update "ARM/OXNAS platform support" patterns
MAINTAINERS: update Cortina/Gemini patterns
MAINTAINERS: remove ARM/CLKDEV SUPPORT file pattern
MAINTAINERS: remove ANDROID ION pattern
mm: docs: add blank lines to silence sphinx "Unexpected indentation" errors
mm: docs: fix parameter names mismatch
mm: docs: fixup punctuation
pipe: read buffer limits atomically
pipe: simplify round_pipe_size()
pipe: reject F_SETPIPE_SZ with size over UINT_MAX
...
Diffstat (limited to 'Documentation/media/uapi/dvb/dmx-mmap.rst')
-rw-r--r-- | Documentation/media/uapi/dvb/dmx-mmap.rst | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/Documentation/media/uapi/dvb/dmx-mmap.rst b/Documentation/media/uapi/dvb/dmx-mmap.rst new file mode 100644 index 000000000000..15d107348b9f --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-mmap.rst @@ -0,0 +1,116 @@ +.. _dmx-mmap: + +***************** +Digital TV mmap() +***************** + +Name +==== + +dmx-mmap - Map device memory into application address space + +.. warning:: this API is still experimental + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + #include <sys/mman.h> + + +.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) + :name: dmx-mmap + +Arguments +========= + +``start`` + Map the buffer to this address in the application's address space. + When the ``MAP_FIXED`` flag is specified, ``start`` must be a + multiple of the pagesize and mmap will fail when the specified + address cannot be used. Use of this option is discouraged; + applications should just specify a ``NULL`` pointer here. + +``length`` + Length of the memory area to map. This must be a multiple of the + DVB packet length (188, on most drivers). + +``prot`` + The ``prot`` argument describes the desired memory protection. + Regardless of the device type and the direction of data exchange it + should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read + and write access to image buffers. Drivers should support at least + this combination of flags. + +``flags`` + The ``flags`` parameter specifies the type of the mapped object, + mapping options and whether modifications made to the mapped copy of + the page are private to the process or are to be shared with other + references. + + ``MAP_FIXED`` requests that the driver selects no other address than + the one specified. If the specified address cannot be used, + :ref:`mmap() <dmx-mmap>` will fail. If ``MAP_FIXED`` is specified, + ``start`` must be a multiple of the pagesize. Use of this option is + discouraged. + + One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set. + ``MAP_SHARED`` allows applications to share the mapped memory with + other (e. g. child-) processes. + + .. note:: + + The Linux Digital TV applications should not set the + ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` + flags. + +``fd`` + File descriptor returned by :ref:`open() <dmx_fopen>`. + +``offset`` + Offset of the buffer in device memory, as returned by + :ref:`DMX_QUERYBUF` ioctl. + + +Description +=========== + +The :ref:`mmap() <dmx-mmap>` function asks to map ``length`` bytes starting at +``offset`` in the memory of the device specified by ``fd`` into the +application address space, preferably at address ``start``. This latter +address is a hint only, and is usually specified as 0. + +Suitable length and offset parameters are queried with the +:ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the +:ref:`DMX_REQBUFS` ioctl before they can be queried. + +To unmap buffers the :ref:`munmap() <dmx-munmap>` function is used. + + +Return Value +============ + +On success :ref:`mmap() <dmx-mmap>` returns a pointer to the mapped buffer. On +error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set +appropriately. Possible error codes are: + +EBADF + ``fd`` is not a valid file descriptor. + +EACCES + ``fd`` is not open for reading and writing. + +EINVAL + The ``start`` or ``length`` or ``offset`` are not suitable. (E. g. + they are too large, or not aligned on a ``PAGESIZE`` boundary.) + + The ``flags`` or ``prot`` value is not supported. + + No buffers have been allocated with the + :ref:`DMX_REQBUFS` ioctl. + +ENOMEM + Not enough physical or virtual memory was available to complete the + request. |