diff options
author | Mauro Carvalho Chehab <mchehab@redhat.com> | 2011-05-31 23:27:44 +0400 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@redhat.com> | 2011-07-28 00:52:05 +0400 |
commit | 4266129964b8238526936d723de65b419d8069c6 (patch) | |
tree | 38c6b5cd3dc99b8599391ffad3b87e399bef56a2 /Documentation/DocBook/media/v4l/func-read.xml | |
parent | 04893043ae9ea8aa82b712491ed25ba6c4ffbca3 (diff) | |
download | linux-4266129964b8238526936d723de65b419d8069c6.tar.xz |
[media] DocBook: Move all media docbook stuff into its own directory
This patch addresses several issues pointed by Randy Dunlap
<rdunlap@xenotime.net> at changeset ece722c:
- In the generated index.html file, "media" is listed first, but it
should be listed in alphabetical order, not first.
- The generated files are (hidden) in .tmpmedia/
- The link from the top-level index.html file to "media" is to
media/index.html, but the file is actually in .tmpmedia/media/index.html
- Please build docs with and without using "O=builddir" and test that.
- Would it be possible for media to have its own Makefile instead of
merging into this one?
Due to the way cleandocs target works, I had to rename the media DocBook
to media_api, otherwise cleandocs would remove the /media directory.
Thanks-to: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/DocBook/media/v4l/func-read.xml')
-rw-r--r-- | Documentation/DocBook/media/v4l/func-read.xml | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/v4l/func-read.xml b/Documentation/DocBook/media/v4l/func-read.xml new file mode 100644 index 000000000000..a5089bf8873d --- /dev/null +++ b/Documentation/DocBook/media/v4l/func-read.xml @@ -0,0 +1,189 @@ +<refentry id="func-read"> + <refmeta> + <refentrytitle>V4L2 read()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>v4l2-read</refname> + <refpurpose>Read from a V4L2 device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> + <funcprototype> + <funcdef>ssize_t <function>read</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>void *<parameter>buf</parameter></paramdef> + <paramdef>size_t <parameter>count</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>buf</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>count</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para><function>read()</function> attempts to read up to +<parameter>count</parameter> bytes from file descriptor +<parameter>fd</parameter> into the buffer starting at +<parameter>buf</parameter>. The layout of the data in the buffer is +discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero, +<function>read()</function> returns zero and has no other results. If +<parameter>count</parameter> is greater than +<constant>SSIZE_MAX</constant>, the result is unspecified. Regardless +of the <parameter>count</parameter> value each +<function>read()</function> call will provide at most one frame (two +fields) worth of data.</para> + + <para>By default <function>read()</function> blocks until data +becomes available. When the <constant>O_NONBLOCK</constant> flag was +given to the &func-open; function it +returns immediately with an &EAGAIN; when no data is available. The +&func-select; or &func-poll; functions +can always be used to suspend execution until data becomes available. All +drivers supporting the <function>read()</function> function must also +support <function>select()</function> and +<function>poll()</function>.</para> + + <para>Drivers can implement read functionality in different +ways, using a single or multiple buffers and discarding the oldest or +newest frames once the internal buffers are filled.</para> + + <para><function>read()</function> never returns a "snapshot" of a +buffer being filled. Using a single buffer the driver will stop +capturing when the application starts reading the buffer until the +read is finished. Thus only the period of the vertical blanking +interval is available for reading, or the capture rate must fall below +the nominal frame rate of the video standard.</para> + +<para>The behavior of +<function>read()</function> when called during the active picture +period or the vertical blanking separating the top and bottom field +depends on the discarding policy. A driver discarding the oldest +frames keeps capturing into an internal buffer, continuously +overwriting the previously, not read frame, and returns the frame +being received at the time of the <function>read()</function> call as +soon as it is complete.</para> + + <para>A driver discarding the newest frames stops capturing until +the next <function>read()</function> call. The frame being received at +<function>read()</function> time is discarded, returning the following +frame instead. Again this implies a reduction of the capture rate to +one half or less of the nominal frame rate. An example of this model +is the video read mode of the bttv driver, initiating a DMA to user +memory when <function>read()</function> is called and returning when +the DMA finished.</para> + + <para>In the multiple buffer model drivers maintain a ring of +internal buffers, automatically advancing to the next free buffer. +This allows continuous capturing when the application can empty the +buffers fast enough. Again, the behavior when the driver runs out of +free buffers depends on the discarding policy.</para> + + <para>Applications can get and set the number of buffers used +internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; +ioctls. They are optional, however. The discarding policy is not +reported and cannot be changed. For minimum requirements see <xref + linkend="devices" />.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, the number of bytes read is returned. It is not +an error if this number is smaller than the number of bytes requested, +or the amount of data required for one frame. This may happen for +example because <function>read()</function> was interrupted by a +signal. On error, -1 is returned, and the <varname>errno</varname> +variable is set appropriately. In this case the next read will start +at the beginning of a new frame. Possible error codes are:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EAGAIN</errorcode></term> + <listitem> + <para>Non-blocking I/O has been selected using +O_NONBLOCK and no data was immediately available for reading.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EBADF</errorcode></term> + <listitem> + <para><parameter>fd</parameter> is not a valid file +descriptor or is not open for reading, or the process already has the +maximum number of files open.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> + <listitem> + <para>The driver does not support multiple read streams and the +device is already in use.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EFAULT</errorcode></term> + <listitem> + <para><parameter>buf</parameter> references an inaccessible +memory area.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINTR</errorcode></term> + <listitem> + <para>The call was interrupted by a signal before any +data was read.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EIO</errorcode></term> + <listitem> + <para>I/O error. This indicates some hardware problem or a +failure to communicate with a remote device (USB camera etc.).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The <function>read()</function> function is not +supported by this driver, not on this device, or generally not on this +type of device.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> + +<!-- +Local Variables: +mode: sgml +sgml-parent-document: "v4l2.sgml" +indent-tabs-mode: nil +End: +--> |