0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _io:
0005
0006 ############
0007 Input/Output
0008 ############
0009 The V4L2 API defines several different methods to read from or write to
0010 a device. All drivers exchanging data with applications must support at
0011 least one of them.
0012
0013 The classic I/O method using the :c:func:`read()` and
0014 :c:func:`write()` function is automatically selected after opening a
0015 V4L2 device. When the driver does not support this method attempts to
0016 read or write will fail at any time.
0017
0018 Other methods must be negotiated. To select the streaming I/O method
0019 with memory mapped or user buffers applications call the
0020 :ref:`VIDIOC_REQBUFS` ioctl. The asynchronous I/O
0021 method is not defined yet.
0022
0023 Video overlay can be considered another I/O method, although the
0024 application does not directly receive the image data. It is selected by
0025 initiating video overlay with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
0026 ioctl. For more information see :ref:`overlay`.
0027
0028 Generally exactly one I/O method, including overlay, is associated with
0029 each file descriptor. The only exceptions are applications not
0030 exchanging data with a driver ("panel applications", see :ref:`open`)
0031 and drivers permitting simultaneous video capturing and overlay using
0032 the same file descriptor, for compatibility with V4L and earlier
0033 versions of V4L2.
0034
0035 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_REQBUFS` would permit this to some
0036 degree, but for simplicity drivers need not support switching the I/O
0037 method (after first switching away from read/write) other than by
0038 closing and reopening the device.
0039
0040 The following sections describe the various I/O methods in more detail.
0041
0042 .. toctree::
0043 :maxdepth: 1
0044
0045 rw
0046 mmap
0047 userp
0048 dmabuf
0049 async
0050 buffer
0051 field-order
