Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) .. c:namespace:: V4L
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) .. _func-read:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) ***********
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) V4L2 read()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) ***********
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) Name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) v4l2-read - Read from a V4L2 device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20)     #include <unistd.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) .. c:function:: ssize_t read( int fd, void *buf, size_t count )
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28)     File descriptor returned by :c:func:`open()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) ``buf``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31)    Buffer to be filled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) ``count``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34)   Max number of bytes to read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) :c:func:`read()` attempts to read up to ``count`` bytes from file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) descriptor ``fd`` into the buffer starting at ``buf``. The layout of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) data in the buffer is discussed in the respective device interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) section, see ##. If ``count`` is zero, :c:func:`read()` returns zero
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) and has no other results. If ``count`` is greater than ``SSIZE_MAX``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) the result is unspecified. Regardless of the ``count`` value each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) :c:func:`read()` call will provide at most one frame (two fields)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) worth of data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) By default :c:func:`read()` blocks until data becomes available. When
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) the ``O_NONBLOCK`` flag was given to the :c:func:`open()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) function it returns immediately with an ``EAGAIN`` error code when no data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) is available. The :c:func:`select()` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) :c:func:`poll()` functions can always be used to suspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) execution until data becomes available. All drivers supporting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) :c:func:`read()` function must also support :c:func:`select()` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) :c:func:`poll()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) Drivers can implement read functionality in different ways, using a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) single or multiple buffers and discarding the oldest or newest frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) once the internal buffers are filled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) :c:func:`read()` never returns a "snapshot" of a buffer being filled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) Using a single buffer the driver will stop capturing when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) application starts reading the buffer until the read is finished. Thus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) only the period of the vertical blanking interval is available for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) reading, or the capture rate must fall below the nominal frame rate of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) the video standard.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) The behavior of :c:func:`read()` when called during the active picture
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) period or the vertical blanking separating the top and bottom field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) depends on the discarding policy. A driver discarding the oldest frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) keeps capturing into an internal buffer, continuously overwriting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) previously, not read frame, and returns the frame being received at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) time of the :c:func:`read()` call as soon as it is complete.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) A driver discarding the newest frames stops capturing until the next
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) :c:func:`read()` call. The frame being received at :c:func:`read()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) time is discarded, returning the following frame instead. Again this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) implies a reduction of the capture rate to one half or less of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) nominal frame rate. An example of this model is the video read mode of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) the bttv driver, initiating a DMA to user memory when :c:func:`read()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) is called and returning when the DMA finished.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) In the multiple buffer model drivers maintain a ring of internal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) buffers, automatically advancing to the next free buffer. This allows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) continuous capturing when the application can empty the buffers fast
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) enough. Again, the behavior when the driver runs out of free buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) depends on the discarding policy.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) Applications can get and set the number of buffers used internally by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) however. The discarding policy is not reported and cannot be changed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) For minimum requirements see :ref:`devices`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) Return Value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) On success, the number of bytes read is returned. It is not an error if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) this number is smaller than the number of bytes requested, or the amount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) of data required for one frame. This may happen for example because
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) :c:func:`read()` was interrupted by a signal. On error, -1 is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) returned, and the ``errno`` variable is set appropriately. In this case
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) the next read will start at the beginning of a new frame. Possible error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) codes are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) EAGAIN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)     Non-blocking I/O has been selected using O_NONBLOCK and no data was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)     immediately available for reading.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) EBADF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)     ``fd`` is not a valid file descriptor or is not open for reading, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)     the process already has the maximum number of files open.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) EBUSY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)     The driver does not support multiple read streams and the device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)     already in use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) EFAULT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)     ``buf`` references an inaccessible memory area.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) EINTR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)     The call was interrupted by a signal before any data was read.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) EIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)     I/O error. This indicates some hardware problem or a failure to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)     communicate with a remote device (USB camera etc.).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) EINVAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)     The :c:func:`read()` function is not supported by this driver, not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)     on this device, or generally not on this type of device.