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