diff options
author | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2016-07-08 11:40:06 -0300 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2016-07-08 11:59:40 -0300 |
commit | 60c2820d0f6d3497975b6488e2599f8f611d8b95 (patch) | |
tree | b3b03707c6438ea9b99cc57e847ebf517f968ab1 /Documentation/media/uapi/v4l/func-mmap.rst | |
parent | a97369b5e21ea9b8b5fef7c0f4f48bbe60c07ca3 (diff) | |
download | linux-60c2820d0f6d3497975b6488e2599f8f611d8b95.tar.bz2 |
doc_rst: rename the media Sphinx suff to Documentation/media
The name of the subsystem is "media", and not "linux_tv". Also,
as we plan to add other stuff there in the future, let's
rename also the media uAPI book to media_uapi, to make it
clearer.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'Documentation/media/uapi/v4l/func-mmap.rst')
-rw-r--r-- | Documentation/media/uapi/v4l/func-mmap.rst | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/func-mmap.rst b/Documentation/media/uapi/v4l/func-mmap.rst new file mode 100644 index 000000000000..3502c2afd894 --- /dev/null +++ b/Documentation/media/uapi/v4l/func-mmap.rst @@ -0,0 +1,134 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _func-mmap: + +*********** +V4L2 mmap() +*********** + +Name +==== + +v4l2-mmap - Map device memory into application address space + + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + #include <sys/mman.h> + + +.. cpp:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) + + +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 the same value as + returned by the driver in the struct + :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the + single-planar API, and the same value as returned by the driver in + the struct :ref:`v4l2_plane <v4l2-plane>` ``length`` field for + the multi-planar API. + +``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. Note the Linux ``video-buf`` kernel + module, which is used by the bttv, saa7134, saa7146, cx88 and vivi + driver supports only ``PROT_READ`` | ``PROT_WRITE``. When the + driver does not support the desired protection the + :ref:`mmap() <func-mmap>` function fails. + + Note device memory accesses (e. g. the memory on a graphics card + with video capturing hardware) may incur a performance penalty + compared to main memory accesses, or reads may be significantly + slower than writes or vice versa. Other I/O methods may be more + efficient in this case. + +``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() <func-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 ``video-buf`` module + which is used by the bttv, saa7134, saa7146, cx88 and vivi driver + supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests copy-on-write + semantics. V4L2 applications should not set the ``MAP_PRIVATE``, + ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` flag. + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``offset`` + Offset of the buffer in device memory. This must be the same value + as returned by the driver in the struct + :ref:`v4l2_buffer <v4l2-buffer>` ``m`` union ``offset`` field for + the single-planar API, and the same value as returned by the driver + in the struct :ref:`v4l2_plane <v4l2-plane>` ``m`` union + ``mem_offset`` field for the multi-planar API. + + +Description +=========== + +The :ref:`mmap() <func-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:`VIDIOC_QUERYBUF` ioctl. Buffers must be +allocated with the :ref:`VIDIOC_REQBUFS` ioctl +before they can be queried. + +To unmap buffers the :ref:`munmap() <func-munmap>` function is used. + + +Return Value +============ + +On success :ref:`mmap() <func-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:`VIDIOC_REQBUFS` ioctl. + +ENOMEM + Not enough physical or virtual memory was available to complete the + request. |