diff options
Diffstat (limited to 'Documentation/DocBook')
| -rw-r--r-- | Documentation/DocBook/gadget.tmpl | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/kernel-api.tmpl | 3 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/compat.xml | 7 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/io.xml | 188 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/v4l2.xml | 1 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-create-bufs.xml | 16 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-expbuf.xml | 212 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 17 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-reqbufs.xml | 47 | ||||
| -rw-r--r-- | Documentation/DocBook/uio-howto.tmpl | 56 | ||||
| -rw-r--r-- | Documentation/DocBook/writing-an-alsa-driver.tmpl | 85 |
11 files changed, 544 insertions, 90 deletions
diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl index 6ef2f0073e5..4017f147ba2 100644 --- a/Documentation/DocBook/gadget.tmpl +++ b/Documentation/DocBook/gadget.tmpl @@ -671,7 +671,7 @@ than a kernel driver. <para>There's a USB Mass Storage class driver, which provides a different solution for interoperability with systems such as MS-Windows and MacOS. -That <emphasis>File-backed Storage</emphasis> driver uses a +That <emphasis>Mass Storage</emphasis> driver uses a file or block device as backing store for a drive, like the <filename>loop</filename> driver. The USB host uses the BBB, CB, or CBI versions of the mass diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 00687ee9d36..f75ab4c1b28 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -58,6 +58,9 @@ <sect1><title>String Conversions</title> !Elib/vsprintf.c +!Finclude/linux/kernel.h kstrtol +!Finclude/linux/kernel.h kstrtoul +!Elib/kstrtox.c </sect1> <sect1><title>String Manipulation</title> <!-- All functions are exported at now diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 4fdf6b562d1..3dd9e78815d 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2586,6 +2586,13 @@ ioctls.</para> <para>Vendor and device specific media bus pixel formats. <xref linkend="v4l2-mbus-vendor-spec-fmts" />.</para> </listitem> + <listitem> + <para>Importing DMABUF file descriptors as a new IO method described + in <xref linkend="dmabuf" />.</para> + </listitem> + <listitem> + <para>Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl.</para> + </listitem> </itemizedlist> </section> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index b5d1cbdc558..388a3403265 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -331,7 +331,7 @@ application until one or more buffers can be dequeued. By default outgoing queue. When the <constant>O_NONBLOCK</constant> flag was given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> returns immediately with an &EAGAIN; when no buffer is available. The -&func-select; or &func-poll; function are always available.</para> +&func-select; or &func-poll; functions are always available.</para> <para>To start and stop capturing or output applications call the &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note @@ -472,6 +472,165 @@ rest should be evident.</para> </footnote></para> </section> + <section id="dmabuf"> + <title>Streaming I/O (DMA buffer importing)</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental"> experimental </link> + interface and may change in the future.</para> + </note> + +<para>The DMABUF framework provides a generic method for sharing buffers +between multiple devices. Device drivers that support DMABUF can export a DMA +buffer to userspace as a file descriptor (known as the exporter role), import a +DMA buffer from userspace using a file descriptor previously exported for a +different or the same device (known as the importer role), or both. This +section describes the DMABUF importer role API in V4L2.</para> + + <para>Refer to <link linked="vidioc-expbuf"> DMABUF exporting </link> for +details about exporting V4L2 buffers as DMABUF file descriptors.</para> + +<para>Input and output devices support the streaming I/O method when the +<constant>V4L2_CAP_STREAMING</constant> flag in the +<structfield>capabilities</structfield> field of &v4l2-capability; returned by +the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through +DMABUF file descriptors is supported is determined by calling the +&VIDIOC-REQBUFS; ioctl with the memory type set to +<constant>V4L2_MEMORY_DMABUF</constant>.</para> + + <para>This I/O method is dedicated to sharing DMA buffers between different +devices, which may be V4L devices or other video-related devices (e.g. DRM). +Buffers (planes) are allocated by a driver on behalf of an application. Next, +these buffers are exported to the application as file descriptors using an API +which is specific for an allocator driver. Only such file descriptor are +exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or +in &v4l2-plane; in the multi-planar API case). The driver must be switched +into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer +type.</para> + + <example> + <title>Initiating streaming I/O with DMABUF file descriptors</title> + + <programlisting> +&v4l2-requestbuffers; reqbuf; + +memset(&reqbuf, 0, sizeof (reqbuf)); +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; +reqbuf.memory = V4L2_MEMORY_DMABUF; +reqbuf.count = 1; + +if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { + if (errno == EINVAL) + printf("Video capturing or DMABUF streaming is not supported\n"); + else + perror("VIDIOC_REQBUFS"); + + exit(EXIT_FAILURE); +} + </programlisting> + </example> + + <para>The buffer (plane) file descriptor is passed on the fly with the +&VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be +associated with a different DMABUF descriptor. Although buffers are commonly +cycled, applications can pass a different DMABUF descriptor at each +<constant>VIDIOC_QBUF</constant> call.</para> + + <example> + <title>Queueing DMABUF using single plane API</title> + + <programlisting> +int buffer_queue(int v4lfd, int index, int dmafd) +{ + &v4l2-buffer; buf; + + memset(&buf, 0, sizeof buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_DMABUF; + buf.index = index; + buf.m.fd = dmafd; + + if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { + perror("VIDIOC_QBUF"); + return -1; + } + + return 0; +} + </programlisting> + </example> + + <example> + <title>Queueing DMABUF using multi plane API</title> + + <programlisting> +int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes) +{ + &v4l2-buffer; buf; + &v4l2-plane; planes[VIDEO_MAX_PLANES]; + int i; + + memset(&buf, 0, sizeof buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; + buf.memory = V4L2_MEMORY_DMABUF; + buf.index = index; + buf.m.planes = planes; + buf.length = n_planes; + + memset(&planes, 0, sizeof planes); + + for (i = 0; i < n_planes; ++i) + buf.m.planes[i].m.fd = dmafd[i]; + + if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { + perror("VIDIOC_QBUF"); + return -1; + } + + return 0; +} + </programlisting> + </example> + + <para>Captured or displayed buffers are dequeued with the +&VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any +time between the completion of the DMA and this ioctl. The memory is +also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or +when the device is closed.</para> + + <para>For capturing applications it is customary to enqueue a +number of empty buffers, to start capturing and enter the read loop. +Here the application waits until a filled buffer can be dequeued, and +re-enqueues the buffer when the data is no longer needed. Output +applications fill and enqueue buffers, when enough buffers are stacked +up output is started. In the write loop, when the application +runs out of free buffers it must wait until an empty buffer can be +dequeued and reused. Two methods exist to suspend execution of the +application until one or more buffers can be dequeued. By default +<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the +outgoing queue. When the <constant>O_NONBLOCK</constant> flag was +given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> +returns immediately with an &EAGAIN; when no buffer is available. The +&func-select; and &func-poll; functions are always available.</para> + + <para>To start and stop capturing or displaying applications call the +&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that +<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both queues and +unlocks all buffers as a side effect. Since there is no notion of doing +anything "now" on a multitasking system, if an application needs to synchronize +with another event it should examine the &v4l2-buffer; +<structfield>timestamp</structfield> of captured buffers, or set the field +before enqueuing buffers for output.</para> + + <para>Drivers implementing DMABUF importing I/O must support the +<constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>, +<constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and +<constant>VIDIOC_STREAMOFF</constant> ioctls, and the +<function>select()</function> and <function>poll()</function> functions.</para> + + </section> + <section id="async"> <title>Asynchronous I/O</title> @@ -673,6 +832,14 @@ memory, set by the application. See <xref linkend="userp" /> for details. <structname>v4l2_buffer</structname> structure.</entry> </row> <row> + <entry></entry> + <entry>int</entry> + <entry><structfield>fd</structfield></entry> + <entry>For the single-plane API and when +<structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this +is the file descriptor associated with a DMABUF buffer.</entry> + </row> + <row> <entry>__u32</entry> <entry><structfield>length</structfield></entry> <entry></entry> @@ -744,6 +911,15 @@ should set this to 0.</entry> </entry> </row> <row> + <entry></entry> + <entry>int</entry> + <entry><structfield>fd</structfield></entry> + <entry>When the memory type in the containing &v4l2-buffer; is + <constant>V4L2_MEMORY_DMABUF</constant>, this is a file + descriptor associated with a DMABUF buffer, similar to the + <structfield>fd</structfield> field in &v4l2-buffer;.</entry> + </row> + <row> <entry>__u32</entry> <entry><structfield>data_offset</structfield></entry> <entry></entry> @@ -923,7 +1099,7 @@ application. Drivers set or clear this flag when the </row> <row> <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry> - <entry>0x0400</entry> + <entry>0x0800</entry> <entry>Caches do not have to be invalidated for this buffer. Typically applications shall use this flag if the data captured in the buffer is not going to be touched by the CPU, instead the buffer will, probably, be @@ -932,7 +1108,7 @@ passed on to a DMA-capable hardware unit for further processing or output. </row> <row> <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry> - <entry>0x0800</entry> + <entry>0x1000</entry> <entry>Caches do not have to be cleaned for this buffer. Typically applications shall use this flag for output buffers if the data in this buffer has not been created by the CPU but by some DMA-capable unit, @@ -964,6 +1140,12 @@ pointer</link> I/O.</entry> <entry>3</entry> <entry>[to do]</entry> </row> + <row> + <entry><constant>V4L2_MEMORY_DMABUF</constant></entry> + <entry>4</entry> + <entry>The buffer is used for <link linkend="dmabuf">DMA shared +buffer</link> I/O.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 10ccde9d16d..4d110b1ad3e 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -543,6 +543,7 @@ and discussions on the V4L mailing list.</revremark> &sub-enuminput; &sub-enumoutput; &sub-enumstd; + &sub-expbuf; &sub-g-audio; &sub-g-audioout; &sub-g-crop; diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index a8cda1acacd..cd994367243 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -6,7 +6,8 @@ <refnamediv> <refname>VIDIOC_CREATE_BUFS</refname> - <refpurpose>Create buffers for Memory Mapped or User Pointer I/O</refpurpose> + <refpurpose>Create buffers for Memory Mapped or User Pointer or DMA Buffer + I/O</refpurpose> </refnamediv> <refsynopsisdiv> @@ -55,11 +56,11 @@ </note> <para>This ioctl is used to create buffers for <link linkend="mmap">memory -mapped</link> or <link linkend="userp">user pointer</link> -I/O. It can be used as an alternative or in addition to the -<constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter control over buffers -is required. This ioctl can be called multiple times to create buffers of -different sizes.</para> +mapped</link> or <link linkend="userp">user pointer</link> or <link +linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in +addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter +control over buffers is required. This ioctl can be called multiple times to +create buffers of different sizes.</para> <para>To allocate device buffers applications initialize relevant fields of the <structname>v4l2_create_buffers</structname> structure. They set the @@ -109,7 +110,8 @@ information.</para> <entry>__u32</entry> <entry><structfield>memory</structfield></entry> <entry>Applications set this field to -<constant>V4L2_MEMORY_MMAP</constant> or +<constant>V4L2_MEMORY_MMAP</constant>, +<constant>V4L2_MEMORY_DMABUF</constant> or <constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory" /></entry> </row> diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml new file mode 100644 index 00000000000..72dfbd20a80 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml @@ -0,0 +1,212 @@ +<refentry id="vidioc-expbuf"> + + <refmeta> + <refentrytitle>ioctl VIDIOC_EXPBUF</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_EXPBUF</refname> + <refpurpose>Export a buffer as a DMABUF file descriptor.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct v4l2_exportbuffer *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>VIDIOC_EXPBUF</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental"> experimental </link> + interface and may change in the future.</para> + </note> + +<para>This ioctl is an extension to the <link linkend="mmap">memory +mapping</link> I/O method, therefore it is available only for +<constant>V4L2_MEMORY_MMAP</constant> buffers. It can be used to export a +buffer as a DMABUF file at any time after buffers have been allocated with the +&VIDIOC-REQBUFS; ioctl.</para> + +<para> To export a buffer, applications fill &v4l2-exportbuffer;. The +<structfield> type </structfield> field is set to the same buffer type as was +previously used with &v4l2-requestbuffers;<structfield> type </structfield>. +Applications must also set the <structfield> index </structfield> field. Valid +index numbers range from zero to the number of buffers allocated with +&VIDIOC-REQBUFS; (&v4l2-requestbuffers;<structfield> count </structfield>) +minus one. For the multi-planar API, applications set the <structfield> plane +</structfield> field to the index of the plane to be exported. Valid planes +range from zero to the maximal number of valid planes for the currently active +format. For the single-planar API, applications must set <structfield> plane +</structfield> to zero. Additional flags may be posted in the <structfield> +flags </structfield> field. Refer to a manual for open() for details. +Currently only O_CLOEXEC is supported. All other fields must be set to zero. +In the case of multi-planar API, every plane is exported separately using +multiple <constant> VIDIOC_EXPBUF </constant> calls. </para> + +<para> After calling <constant>VIDIOC_EXPBUF</constant> the <structfield> fd +</structfield> field will be set by a driver. This is a DMABUF file +descriptor. The application may pass it to other DMABUF-aware devices. Refer to +<link linkend="dmabuf">DMABUF importing</link> for details about importing +DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it +is no longer used to allow the associated memory to be reclaimed. </para> + + </refsect1> + <refsect1> + <section> + <title>Examples</title> + + <example> + <title>Exporting a buffer.</title> + <programlisting> +int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd) +{ + &v4l2-exportbuffer; expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { + perror("VIDIOC_EXPBUF"); + return -1; + } + + *dmafd = expbuf.fd; + + return 0; +} + </programlisting> + </example> + + <example> + <title>Exporting a buffer using the multi-planar API.</title> + <programlisting> +int buffer_export_mp(int v4lfd, &v4l2-buf-type; bt, int index, + int dmafd[], int n_planes) +{ + int i; + + for (i = 0; i < n_planes; ++i) { + &v4l2-exportbuffer; expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + expbuf.plane = i; + if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { + perror("VIDIOC_EXPBUF"); + while (i) + close(dmafd[--i]); + return -1; + } + dmafd[i] = expbuf.fd; + } + + return 0; +} + </programlisting> + </example> + </section> + </refsect1> + + <refsect1> + <table pgwide="1" frame="none" id="v4l2-exportbuffer"> + <title>struct <structname>v4l2_exportbuffer</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>type</structfield></entry> + <entry>Type of the buffer, same as &v4l2-format; +<structfield>type</structfield> or &v4l2-requestbuffers; +<structfield>type</structfield>, set by the application. See <xref +linkend="v4l2-buf-type" /></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>index</structfield></entry> + <entry>Number of the buffer, set by the application. This field is +only used for <link linkend="mmap">memory mapping</link> I/O and can range from +zero to the number of buffers allocated with the &VIDIOC-REQBUFS; and/or +&VIDIOC-CREATE-BUFS; ioctls. </entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>plane</structfield></entry> + <entry>Index of the plane to be exported when using the +multi-planar API. Otherwise this value must be set to zero. </entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Flags for the newly created file, currently only <constant> +O_CLOEXEC </constant> is supported, refer to the manual of open() for more +details.</entry> + </row> + <row> + <entry>__s32</entry> + <entry><structfield>fd</structfield></entry> + <entry>The DMABUF file descriptor associated with a buffer. Set by + the driver.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved[11]</structfield></entry> + <entry>Reserved field for future use. Must be set to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + + </refsect1> + + <refsect1> + &return-value; + <variablelist> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>A queue is not in MMAP mode or DMABUF exporting is not +supported or <structfield> flags </structfield> or <structfield> type +</structfield> or <structfield> index </structfield> or <structfield> plane +</structfield> fields are invalid.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + +</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 2d37abefce1..3504a7f2f38 100644 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml @@ -109,6 +109,23 @@ they cannot be swapped out to disk. Buffers remain locked until dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or until the device is closed.</para> + <para>To enqueue a <link linkend="dmabuf">DMABUF</link> buffer applications +set the <structfield>memory</structfield> field to +<constant>V4L2_MEMORY_DMABUF</constant> and the <structfield>m.fd</structfield> +field to a file descriptor associated with a DMABUF buffer. When the +multi-planar API is used the <structfield>m.fd</structfield> fields of the +passed array of &v4l2-plane; have to be used instead. When +<constant>VIDIOC_QBUF</constant> is called with a pointer to this structure the +driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the +<constant>V4L2_BUF_FLAG_MAPPED</constant> and +<constant>V4L2_BUF_FLAG_DONE</constant> flags in the +<structfield>flags</structfield> field, or it returns an error code. This +ioctl locks the buffer. Locking a buffer means passing it to a driver for a +hardware access (usually DMA). If an application accesses (reads/writes) a +locked buffer then the result is undefined. Buffers remain locked until +dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or +until the device is closed.</para> + <para>Applications call the <constant>VIDIOC_DQBUF</constant> ioctl to dequeue a filled (capturing) or displayed (output) buffer from the driver's outgoing queue. They just set the diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml index 2b50ef2007f..78a06a9a5ec 100644 --- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml @@ -48,28 +48,30 @@ <refsect1> <title>Description</title> - <para>This ioctl is used to initiate <link linkend="mmap">memory -mapped</link> or <link linkend="userp">user pointer</link> -I/O. Memory mapped buffers are located in device memory and must be -allocated with this ioctl before they can be mapped into the -application's address space. User buffers are allocated by -applications themselves, and this ioctl is merely used to switch the -driver into user pointer I/O mode and to setup some internal structures.</para> +<para>This ioctl is used to initiate <link linkend="mmap">memory mapped</link>, +<link linkend="userp">user pointer</link> or <link +linkend="dmabuf">DMABUF</link> based I/O. Memory mapped buffers are located in +device memory and must be allocated with this ioctl before they can be mapped +into the application's address space. User buffers are allocated by +applications themselves, and this ioctl is merely used to switch the driver +into user pointer I/O mode and to setup some internal structures. +Similarly, DMABUF buffers are allocated by applications through a device +driver, and this ioctl only configures the driver into DMABUF I/O mode without +performing any direct allocation.</para> - <para>To allocate device buffers applications initialize all -fields of the <structname>v4l2_requestbuffers</structname> structure. -They set the <structfield>type</structfield> field to the respective -stream or buffer type, the <structfield>count</structfield> field to -the desired number of buffers, <structfield>memory</structfield> -must be set to the requested I/O method and the <structfield>reserved</structfield> array -must be zeroed. When the ioctl -is called with a pointer to this structure the driver will attempt to allocate -the requested number of buffers and it stores the actual number -allocated in the <structfield>count</structfield> field. It can be -smaller than the number requested, even zero, when the driver runs out -of free memory. A larger number is also possible when the driver requires -more buffers to function correctly. For example video output requires at least two buffers, -one displayed and one filled by the application.</para> + <para>To allocate device buffers applications initialize all fields of the +<structname>v4l2_requestbuffers</structname> structure. They set the +<structfield>type</structfield> field to the respective stream or buffer type, +the <structfield>count</structfield> field to the desired number of buffers, +<structfield>memory</structfield> must be set to the requested I/O method and +the <structfield>reserved</structfield> array must be zeroed. When the ioctl is +called with a pointer to this structure the driver will attempt to allocate the +requested number of buffers and it stores the actual number allocated in the +<structfield>count</structfield> field. It can be smaller than the number +requested, even zero, when the driver runs out of free memory. A larger number +is also possible when the driver requires more buffers to function correctly. +For example video output requires at least two buffers, one displayed and one +filled by the application.</para> <para>When the I/O method is not supported the ioctl returns an &EINVAL;.</para> @@ -102,7 +104,8 @@ as the &v4l2-format; <structfield>type</structfield> field. See <xref <entry>__u32</entry> <entry><structfield>memory</structfield></entry> <entry>Applications set this field to -<constant>V4L2_MEMORY_MMAP</constant> or +<constant>V4L2_MEMORY_MMAP</constant>, +<constant>V4L2_MEMORY_DMABUF</constant> or <constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory" />.</entry> </row> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index ac3d0018140..ddb05e98af0 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -719,6 +719,62 @@ framework to set up sysfs files for this region. Simply leave it alone. </para> </sect1> +<sect1 id="using uio_dmem_genirq"> +<title>Using uio_dmem_genirq for platform devices</title> + <para> + In addition to statically allocated memory ranges, they may also be + a desire to use dynamically allocated regions in a user space driver. + In particular, being able to access memory made available through the + dma-mapping API, may be particularly useful. The + <varname>uio_dmem_genirq</varname> driver provides a way to accomplish + this. + </para> + <para> + This driver is used in a similar manner to the + <varname>"uio_pdrv_genirq"</varname> driver with respect to interrupt + configuration and handling. + </para> + <para> + Set the <varname>.name</varname> element of + <varname>struct platform_device</varname> to + <varname>"uio_dmem_genirq"</varname> to use this driver. + </para> + <para> + When using this driver, fill in the <varname>.platform_data</varname> + element of <varname>struct platform_device</varname>, which is of type + <varname>struct uio_dmem_genirq_pdata</varname> and which contains the + following elements: + </para> + <itemizedlist> + <listitem><varname>struct uio_info uioinfo</varname>: The same + structure used as the <varname>uio_pdrv_genirq</varname> platform + data</listitem> + <listitem><varname>unsigned int *dynamic_region_sizes</varname>: + Pointer to list of sizes of dynamic memory regions to be mapped into + user space. + </listitem> + <listitem><varname>unsigned int num_dynamic_regions</varname>: + Number of elements in <varname>dynamic_region_sizes</varname> array. + </listitem> + </itemizedlist> + <para> + The dynamic regions defined in the platform data will be appended to + the <varname> mem[] </varname> array after the platform device + resources, which implies that the total number of static and dynamic + memory regions cannot exceed <varname>MAX_UIO_MAPS</varname>. + </para> + <para> + The dynamic memory regions will be allocated when the UIO device file, + <varname>/dev/uioX</varname> is opened. + Simiar to static memory resources, the memory region information for + dynamic regions is then visible via sysfs at + <varname>/sys/class/uio/uioX/maps/mapY/*</varname>. + The dynmaic memory regions will be freed when the UIO device file is + closed. When no processes are holding the device file open, the address + returned to userspace is ~0. + </para> +</sect1> + </chapter> <chapter id="userspace_driver" xreflabel="Writing a driver in user space"> diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl index cab4ec58e46..fb32aead5a0 100644 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl @@ -433,9 +433,9 @@ /* chip-specific constructor * (see "Management of Cards and Components") */ - static int __devinit snd_mychip_create(struct snd_card *card, - struct pci_dev *pci, - struct mychip **rchip) + static int snd_mychip_create(struct snd_card *card, + struct pci_dev *pci, + struct mychip **rchip) { struct mychip *chip; int err; @@ -475,8 +475,8 @@ } /* constructor -- see "Constructor" sub-section */ - static int __devinit snd_mychip_probe(struct pci_dev *pci, - const struct pci_device_id *pci_id) + static int snd_mychip_probe(struct pci_dev *pci, + const struct pci_device_id *pci_id) { static int dev; struct snd_card *card; @@ -526,7 +526,7 @@ } /* destructor -- see the "Destructor" sub-section */ - static void __devexit snd_mychip_remove(struct pci_dev *pci) + static void snd_mychip_remove(struct pci_dev *pci) { snd_card_free(pci_get_drvdata(pci)); pci_set_drvdata(pci, NULL); @@ -542,9 +542,8 @@ <para> The real constructor of PCI drivers is the <function>probe</function> callback. The <function>probe</function> callback and other component-constructors which are called - from the <function>probe</function> callback should be defined with - the <parameter>__devinit</parameter> prefix. You - cannot use the <parameter>__init</parameter> prefix for them, + from the <function>probe</function> callback cannot be used with + the <parameter>__init</parameter> prefix because any PCI device could be a hotplug device. </para> @@ -728,7 +727,7 @@ <informalexample> <programlisting> <![CDATA[ - static void __devexit snd_mychip_remove(struct pci_dev *pci) + static void snd_mychip_remove(struct pci_dev *pci) { snd_card_free(pci_get_drvdata(pci)); pci_set_drvdata(pci, NULL); @@ -1059,14 +1058,6 @@ </para> <para> - As further notes, the destructors (both - <function>snd_mychip_dev_free</function> and - <function>snd_mychip_free</function>) cannot be defined with - the <parameter>__devexit</parameter> prefix, because they may be - called from the constructor, too, at the false path. - </para> - - <para> For a device which allows hotplugging, you can use <function>snd_card_free_when_closed</function>. This one will postpone the destruction until all devices are closed. @@ -1120,9 +1111,9 @@ } /* chip-specific constructor */ - static int __devinit snd_mychip_create(struct snd_card *card, - struct pci_dev *pci, - struct mychip **rchip) + static int snd_mychip_create(struct snd_card *card, + struct pci_dev *pci, + struct mychip **rchip) { struct mychip *chip; int err; @@ -1200,7 +1191,7 @@ .name = KBUILD_MODNAME, .id_table = snd_mychip_ids, .probe = snd_mychip_probe, - .remove = __devexit_p(snd_mychip_remove), + .remove = snd_mychip_remove, }; /* module initialization */ @@ -1465,11 +1456,6 @@ </para> <para> - Again, remember that you cannot - use the <parameter>__devexit</parameter> prefix for this destructor. - </para> - - <para> We didn't implement the hardware disabling part in the above. If you need to do this, please note that the destructor may be called even before the initialization of the chip is completed. @@ -1619,7 +1605,7 @@ .name = KBUILD_MODNAME, .id_table = snd_mychip_ids, .probe = snd_mychip_probe, - .remove = __devexit_p(snd_mychip_remove), + .remove = snd_mychip_remove, }; ]]> </programlisting> @@ -1630,11 +1616,7 @@ The <structfield>probe</structfield> and <structfield>remove</structfield> functions have already been defined in the previous sections. - The <structfield>remove</structfield> function should - be defined with the - <function>__devexit_p()</function> macro, so that it's not - defined for built-in (and non-hot-pluggable) case. The - <structfield>name</structfield> + The <structfield>name</structfield> field is the name string of this device. Note that you must not use a slash <quote>/</quote> in this string. </para> @@ -1665,9 +1647,7 @@ <para> Note that these module entries are tagged with <parameter>__init</parameter> and - <parameter>__exit</parameter> prefixes, not - <parameter>__devinit</parameter> nor - <parameter>__devexit</parameter>. + <parameter>__exit</parameter> prefixes. </para> <para> @@ -1918,7 +1898,7 @@ */ /* create a pcm device */ - static int __devinit snd_mychip_new_pcm(struct mychip *chip) + static int snd_mychip_new_pcm(struct mychip *chip) { struct snd_pcm *pcm; int err; @@ -1957,7 +1937,7 @@ <informalexample> <programlisting> <![CDATA[ - static int __devinit snd_mychip_new_pcm(struct mychip *chip) + static int snd_mychip_new_pcm(struct mychip *chip) { struct snd_pcm *pcm; int err; @@ -2124,7 +2104,7 @@ .... } - static int __devinit snd_mychip_new_pcm(struct mychip *chip) + static int snd_mychip_new_pcm(struct mychip *chip) { struct snd_pcm *pcm; .... @@ -3399,7 +3379,7 @@ struct _snd_pcm_runtime { <title>Definition of a Control</title> <programlisting> <![CDATA[ - static struct snd_kcontrol_new my_control __devinitdata = { + static struct snd_kcontrol_new my_control = { .iface = SNDRV_CTL_ELEM_IFACE_MIXER, .name = "PCM Playback Switch", .index = 0, @@ -3415,13 +3395,6 @@ struct _snd_pcm_runtime { </para> <para> - Most likely the control is created via - <function>snd_ctl_new1()</function>, and in such a case, you can - add the <parameter>__devinitdata</parameter> prefix to the - definition as above. - </para> - - <para> The <structfield>iface</structfield> field specifies the control type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which is usually <constant>MIXER</constant>. @@ -3847,10 +3820,8 @@ struct _snd_pcm_runtime { <para> <function>snd_ctl_new1()</function> allocates a new - <structname>snd_kcontrol</structname> instance (that's why the definition - of <parameter>my_control</parameter> can be with - the <parameter>__devinitdata</parameter> - prefix), and <function>snd_ctl_add</function> assigns the given + <structname>snd_kcontrol</structname> instance, + and <function>snd_ctl_add</function> assigns the given control component to the card. </para> </section> @@ -3896,7 +3867,7 @@ struct _snd_pcm_runtime { <![CDATA[ static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0); - static struct snd_kcontrol_new my_control __devinitdata = { + static struct snd_kcontrol_new my_control = { ... .access = SNDRV_CTL_ELEM_ACCESS_READWRITE | SNDRV_CTL_ELEM_ACCESS_TLV_READ, @@ -5761,8 +5732,8 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int __devinit snd_mychip_probe(struct pci_dev *pci, - const struct pci_device_id *pci_id) + static int snd_mychip_probe(struct pci_dev *pci, + const struct pci_device_id *pci_id) { .... struct snd_card *card; @@ -5787,8 +5758,8 @@ struct _snd_pcm_runtime { <informalexample> <programlisting> <![CDATA[ - static int __devinit snd_mychip_probe(struct pci_dev *pci, - const struct pci_device_id *pci_id) + static int snd_mychip_probe(struct pci_dev *pci, + const struct pci_device_id *pci_id) { .... struct snd_card *card; @@ -5825,7 +5796,7 @@ struct _snd_pcm_runtime { .name = KBUILD_MODNAME, .id_table = snd_my_ids, .probe = snd_my_probe, - .remove = __devexit_p(snd_my_remove), + .remove = snd_my_remove, #ifdef CONFIG_PM .suspend = snd_my_suspend, .resume = snd_my_resume, |