1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _rw:
11
12**********
13Read/Write
14**********
15
16Input and output devices support the :ref:`read() <func-read>` and
17:ref:`write() <func-write>` function, respectively, when the
18``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct
19:c:type:`v4l2_capability` returned by the
20:ref:`VIDIOC_QUERYCAP` ioctl is set.
21
22Drivers may need the CPU to copy the data, but they may also support DMA
23to or from user memory, so this I/O method is not necessarily less
24efficient than other methods merely exchanging buffer pointers. It is
25considered inferior though because no meta-information like frame
26counters or timestamps are passed. This information is necessary to
27recognize frame dropping and to synchronize with other data streams.
28However this is also the simplest I/O method, requiring little or no
29setup to exchange data. It permits command line stunts like this (the
30vidctrl tool is fictitious):
31
32
33.. code-block:: none
34
35    $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288
36    $ dd if=/dev/video of=myimage.422 bs=202752 count=1
37
38To read from the device applications use the :ref:`read() <func-read>`
39function, to write the :ref:`write() <func-write>` function. Drivers
40must implement one I/O method if they exchange data with applications,
41but it need not be this. [#f1]_ When reading or writing is supported, the
42driver must also support the :ref:`select() <func-select>` and
43:ref:`poll() <func-poll>` function. [#f2]_
44
45.. [#f1]
46   It would be desirable if applications could depend on drivers
47   supporting all I/O interfaces, but as much as the complex memory
48   mapping I/O can be inadequate for some devices we have no reason to
49   require this interface, which is most useful for simple applications
50   capturing still images.
51
52.. [#f2]
53   At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
54   the same, and :ref:`select() <func-select>` is too important to be optional.
55