From 849369d6c66d3054688672f97d31fceb8e8230fb Mon Sep 17 00:00:00 2001 From: root Date: Fri, 25 Dec 2015 04:40:36 +0000 Subject: initial_commit --- Documentation/DocBook/v4l/func-mmap.xml | 191 ++++++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 Documentation/DocBook/v4l/func-mmap.xml (limited to 'Documentation/DocBook/v4l/func-mmap.xml') diff --git a/Documentation/DocBook/v4l/func-mmap.xml b/Documentation/DocBook/v4l/func-mmap.xml new file mode 100644 index 00000000..786732b6 --- /dev/null +++ b/Documentation/DocBook/v4l/func-mmap.xml @@ -0,0 +1,191 @@ + + + V4L2 mmap() + &manvol; + + + + v4l2-mmap + Map device memory into application address space + + + + + +#include <unistd.h> +#include <sys/mman.h> + + 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 &v4l2-buffer; +length field for the +single-planar API, and the same value as returned by the driver +in the &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 +mmap() function fails. + Note device memory accesses (⪚ 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, 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 (⪚ 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 + + &fd; + + + + offset + + Offset of the buffer in device memory. This must be the +same value as returned by the driver in the &v4l2-buffer; +m union offset field for +the single-planar API, and the same value as returned by the driver +in the &v4l2-plane; m union +mem_offset field for the multi-planar API. + + + + + + + Description + + The 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 +&VIDIOC-QUERYBUF; ioctl. Buffers must be allocated with the +&VIDIOC-REQBUFS; ioctl before they can be queried. + + To unmap buffers the &func-munmap; function is used. + + + + Return Value + + On success 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 +&VIDIOC-REQBUFS; ioctl. + + + + ENOMEM + + Not enough physical or virtual memory was available to +complete the request. + + + + + + + -- cgit v1.2.3