0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _rw:
0005
0006 **********
0007 Read/Write
0008 **********
0009
0010 Input and output devices support the :c:func:`read()` and
0011 :c:func:`write()` function, respectively, when the
0012 ``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct
0013 :c:type:`v4l2_capability` returned by the
0014 :ref:`VIDIOC_QUERYCAP` ioctl is set.
0015
0016 Drivers may need the CPU to copy the data, but they may also support DMA
0017 to or from user memory, so this I/O method is not necessarily less
0018 efficient than other methods merely exchanging buffer pointers. It is
0019 considered inferior though because no meta-information like frame
0020 counters or timestamps are passed. This information is necessary to
0021 recognize frame dropping and to synchronize with other data streams.
0022 However this is also the simplest I/O method, requiring little or no
0023 setup to exchange data. It permits command line stunts like this (the
0024 vidctrl tool is fictitious):
0025
0026 .. code-block:: none
0027
0028 $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288
0029 $ dd if=/dev/video of=myimage.422 bs=202752 count=1
0030
0031 To read from the device applications use the :c:func:`read()`
0032 function, to write the :c:func:`write()` function. Drivers
0033 must implement one I/O method if they exchange data with applications,
0034 but it need not be this. [#f1]_ When reading or writing is supported, the
0035 driver must also support the :c:func:`select()` and
0036 :c:func:`poll()` function. [#f2]_
0037
0038 .. [#f1]
0039 It would be desirable if applications could depend on drivers
0040 supporting all I/O interfaces, but as much as the complex memory
0041 mapping I/O can be inadequate for some devices we have no reason to
0042 require this interface, which is most useful for simple applications
0043 capturing still images.
0044
0045 .. [#f2]
0046 At the driver level :c:func:`select()` and :c:func:`poll()` are
0047 the same, and :c:func:`select()` is too important to be optional.
