Documentation/media/uapi/v4l/rw.rst

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