186 lines
6.7 KiB
XML
186 lines
6.7 KiB
XML
<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.</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.</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>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-parent-document: "v4l2.sgml"
|
|
indent-tabs-mode: nil
|
|
End:
|
|
-->
|