Documentation/userspace-api/media/v4l/io.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _io:
   5
   6 ############
   7 Input/Output
   8 ############
   9 The V4L2 API defines several different methods to read from or write to
  10 a device. All drivers exchanging data with applications must support at
  11 least one of them.
  12
  13 The classic I/O method using the :c:func:`read()` and
  14 :c:func:`write()` function is automatically selected after opening a
  15 V4L2 device. When the driver does not support this method attempts to
  16 read or write will fail at any time.
  17
  18 Other methods must be negotiated. To select the streaming I/O method
  19 with memory mapped or user buffers applications call the
  20 :ref:`VIDIOC_REQBUFS` ioctl. The asynchronous I/O
  21 method is not defined yet.
  22
  23 Video overlay can be considered another I/O method, although the
  24 application does not directly receive the image data. It is selected by
  25 initiating video overlay with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
  26 ioctl. For more information see :ref:`overlay`.
  27
  28 Generally exactly one I/O method, including overlay, is associated with
  29 each file descriptor. The only exceptions are applications not
  30 exchanging data with a driver ("panel applications", see :ref:`open`)
  31 and drivers permitting simultaneous video capturing and overlay using
  32 the same file descriptor, for compatibility with V4L and earlier
  33 versions of V4L2.
  34
  35 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_REQBUFS` would permit this to some
  36 degree, but for simplicity drivers need not support switching the I/O
  37 method (after first switching away from read/write) other than by
  38 closing and reopening the device.
  39
  40 The following sections describe the various I/O methods in more detail.
  41
  42 .. toctree::
  43     :maxdepth: 1
  44
  45     rw
  46     mmap
  47     userp
  48     dmabuf
  49     async
  50     buffer
  51     field-order