mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-23 12:43:55 +08:00
4e03cb760d
As VIDIOC_G_foo is the reference used for VIDIOC_S_foo and VIDIOC_TRY_foo, we need to explicitly name the reference, as otherwise, it will mention the three ioctls altogether, with is not what we want. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
139 lines
4.9 KiB
ReStructuredText
139 lines
4.9 KiB
ReStructuredText
.. -*- coding: utf-8; mode: rst -*-
|
|
|
|
.. _func-read:
|
|
|
|
***********
|
|
V4L2 read()
|
|
***********
|
|
|
|
*man v4l2-read(2)*
|
|
|
|
Read from a V4L2 device
|
|
|
|
|
|
Synopsis
|
|
========
|
|
|
|
.. code-block:: c
|
|
|
|
#include <unistd.h>
|
|
|
|
|
|
.. c:function:: ssize_t read( int fd, void *buf, size_t count )
|
|
|
|
Arguments
|
|
=========
|
|
|
|
``fd``
|
|
File descriptor returned by :ref:`open() <func-open>`.
|
|
|
|
``buf``
|
|
``count``
|
|
|
|
|
|
Description
|
|
===========
|
|
|
|
:c:func:`read()` attempts to read up to ``count`` bytes from file
|
|
descriptor ``fd`` into the buffer starting at ``buf``. The layout of the
|
|
data in the buffer is discussed in the respective device interface
|
|
section, see ##. If ``count`` is zero, :c:func:`read()` returns zero
|
|
and has no other results. If ``count`` is greater than ``SSIZE_MAX``,
|
|
the result is unspecified. Regardless of the ``count`` value each
|
|
:c:func:`read()` call will provide at most one frame (two fields)
|
|
worth of data.
|
|
|
|
By default :c:func:`read()` blocks until data becomes available. When
|
|
the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>`
|
|
function it returns immediately with an EAGAIN error code when no data
|
|
is available. The :ref:`select() <func-select>` or
|
|
:ref:`poll() <func-poll>` functions can always be used to suspend
|
|
execution until data becomes available. All drivers supporting the
|
|
:c:func:`read()` function must also support :c:func:`select()` and
|
|
:c:func:`poll()`.
|
|
|
|
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.
|
|
|
|
:c:func:`read()` 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.
|
|
|
|
The behavior of :c:func:`read()` 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 :c:func:`read()` call as soon as it is complete.
|
|
|
|
A driver discarding the newest frames stops capturing until the next
|
|
:c:func:`read()` call. The frame being received at :c:func:`read()`
|
|
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 :c:func:`read()`
|
|
is called and returning when the DMA finished.
|
|
|
|
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.
|
|
|
|
Applications can get and set the number of buffers used internally by
|
|
the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
|
|
:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional,
|
|
however. The discarding policy is not reported and cannot be changed.
|
|
For minimum requirements see :ref:`devices`.
|
|
|
|
|
|
Return Value
|
|
============
|
|
|
|
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
|
|
:c:func:`read()` was interrupted by a signal. On error, -1 is
|
|
returned, and the ``errno`` variable is set appropriately. In this case
|
|
the next read will start at the beginning of a new frame. Possible error
|
|
codes are:
|
|
|
|
EAGAIN
|
|
Non-blocking I/O has been selected using O_NONBLOCK and no data was
|
|
immediately available for reading.
|
|
|
|
EBADF
|
|
``fd`` is not a valid file descriptor or is not open for reading, or
|
|
the process already has the maximum number of files open.
|
|
|
|
EBUSY
|
|
The driver does not support multiple read streams and the device is
|
|
already in use.
|
|
|
|
EFAULT
|
|
``buf`` references an inaccessible memory area.
|
|
|
|
EINTR
|
|
The call was interrupted by a signal before any data was read.
|
|
|
|
EIO
|
|
I/O error. This indicates some hardware problem or a failure to
|
|
communicate with a remote device (USB camera etc.).
|
|
|
|
EINVAL
|
|
The :c:func:`read()` function is not supported by this driver, not
|
|
on this device, or generally not on this type of device.
|
|
|
|
|
|
.. ------------------------------------------------------------------------------
|
|
.. This file was automatically converted from DocBook-XML with the dbxml
|
|
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
|
|
.. from the linux kernel, refer to:
|
|
..
|
|
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
|
|
.. ------------------------------------------------------------------------------
|