Documentation/media/uapi/v4l/rw.rst

   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/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _rw:
  11
  12 **********
  13 Read/Write
  14 **********
  15
  16 Input 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
  22 Drivers may need the CPU to copy the data, but they may also support DMA
  23 to or from user memory, so this I/O method is not necessarily less
  24 efficient than other methods merely exchanging buffer pointers. It is
  25 considered inferior though because no meta-information like frame
  26 counters or timestamps are passed. This information is necessary to
  27 recognize frame dropping and to synchronize with other data streams.
  28 However this is also the simplest I/O method, requiring little or no
  29 setup to exchange data. It permits command line stunts like this (the
  30 vidctrl 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
  38 To read from the device applications use the :ref:`read() <func-read>`
  39 function, to write the :ref:`write() <func-write>` function. Drivers
  40 must implement one I/O method if they exchange data with applications,
  41 but it need not be this. [#f1]_ When reading or writing is supported, the
  42 driver 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.