diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/func-mmap.xml')
| -rw-r--r-- | Documentation/DocBook/media/v4l/func-mmap.xml | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/v4l/func-mmap.xml b/Documentation/DocBook/media/v4l/func-mmap.xml new file mode 100644 index 000000000..f31ad71bf --- /dev/null +++ b/Documentation/DocBook/media/v4l/func-mmap.xml @@ -0,0 +1,183 @@ +<refentry id="func-mmap"> + <refmeta> + <refentrytitle>V4L2 mmap()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>v4l2-mmap</refname> + <refpurpose>Map device memory into application address space</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo> +#include <unistd.h> +#include <sys/mman.h></funcsynopsisinfo> + <funcprototype> + <funcdef>void *<function>mmap</function></funcdef> + <paramdef>void *<parameter>start</parameter></paramdef> + <paramdef>size_t <parameter>length</parameter></paramdef> + <paramdef>int <parameter>prot</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>off_t <parameter>offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>start</parameter></term> + <listitem> + <para>Map the buffer to this address in the +application's address space. When the <constant>MAP_FIXED</constant> +flag is specified, <parameter>start</parameter> 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 <constant>NULL</constant> pointer here.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>length</parameter></term> + <listitem> + <para>Length of the memory area to map. This must be the +same value as returned by the driver in the &v4l2-buffer; +<structfield>length</structfield> field for the +single-planar API, and the same value as returned by the driver +in the &v4l2-plane; <structfield>length</structfield> field for the +multi-planar API.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>prot</parameter></term> + <listitem> + <para>The <parameter>prot</parameter> argument describes the +desired memory protection. Regardless of the device type and the +direction of data exchange it should be set to +<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>, +permitting read and write access to image buffers. Drivers should +support at least this combination of flags. Note the Linux +<filename>video-buf</filename> kernel module, which is used by the +bttv, saa7134, saa7146, cx88 and vivi driver supports only +<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When +the driver does not support the desired protection the +<function>mmap()</function> function fails.</para> + <para>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.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para>The <parameter>flags</parameter> 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.</para> + <para><constant>MAP_FIXED</constant> requests that the +driver selects no other address than the one specified. If the +specified address cannot be used, <function>mmap()</function> will fail. If +<constant>MAP_FIXED</constant> is specified, +<parameter>start</parameter> must be a multiple of the pagesize. Use +of this option is discouraged.</para> + <para>One of the <constant>MAP_SHARED</constant> or +<constant>MAP_PRIVATE</constant> flags must be set. +<constant>MAP_SHARED</constant> allows applications to share the +mapped memory with other (⪚ child-) processes. Note the Linux +<filename>video-buf</filename> module which is used by the bttv, +saa7134, saa7146, cx88 and vivi driver supports only +<constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant> +requests copy-on-write semantics. V4L2 applications should not set the +<constant>MAP_PRIVATE</constant>, <constant>MAP_DENYWRITE</constant>, +<constant>MAP_EXECUTABLE</constant> or <constant>MAP_ANON</constant> +flag.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>offset</parameter></term> + <listitem> + <para>Offset of the buffer in device memory. This must be the +same value as returned by the driver in the &v4l2-buffer; +<structfield>m</structfield> union <structfield>offset</structfield> field for +the single-planar API, and the same value as returned by the driver +in the &v4l2-plane; <structfield>m</structfield> union +<structfield>mem_offset</structfield> field for the multi-planar API.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>The <function>mmap()</function> function asks to map +<parameter>length</parameter> bytes starting at +<parameter>offset</parameter> in the memory of the device specified by +<parameter>fd</parameter> into the application address space, +preferably at address <parameter>start</parameter>. This latter +address is a hint only, and is usually specified as 0.</para> + + <para>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.</para> + + <para>To unmap buffers the &func-munmap; function is used.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success <function>mmap()</function> returns a pointer to +the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is +returned, and the <varname>errno</varname> variable is set +appropriately. Possible error codes are:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EBADF</errorcode></term> + <listitem> + <para><parameter>fd</parameter> is not a valid file +descriptor.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EACCES</errorcode></term> + <listitem> + <para><parameter>fd</parameter> is +not open for reading and writing.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The <parameter>start</parameter> or +<parameter>length</parameter> or <parameter>offset</parameter> are not +suitable. (E. g. they are too large, or not aligned on a +<constant>PAGESIZE</constant> boundary.)</para> + <para>The <parameter>flags</parameter> or +<parameter>prot</parameter> value is not supported.</para> + <para>No buffers have been allocated with the +&VIDIOC-REQBUFS; ioctl.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENOMEM</errorcode></term> + <listitem> + <para>Not enough physical or virtual memory was available to +complete the request.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> |