Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _io: |
| 4 | |
| 5 | ############ |
| 6 | Input/Output |
| 7 | ############ |
| 8 | The V4L2 API defines several different methods to read from or write to |
| 9 | a device. All drivers exchanging data with applications must support at |
| 10 | least one of them. |
| 11 | |
| 12 | The classic I/O method using the :c:func:`read()` and |
| 13 | :c:func:`write()` function is automatically selected after opening a |
| 14 | V4L2 device. When the driver does not support this method attempts to |
| 15 | read or write will fail at any time. |
| 16 | |
| 17 | Other methods must be negotiated. To select the streaming I/O method |
| 18 | with memory mapped or user buffers applications call the |
| 19 | :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl. The asynchronous I/O |
| 20 | method is not defined yet. |
| 21 | |
| 22 | Video overlay can be considered another I/O method, although the |
| 23 | application does not directly receive the image data. It is selected by |
| 24 | initiating video overlay with the :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` |
| 25 | ioctl. For more information see :ref:`overlay`. |
| 26 | |
| 27 | Generally exactly one I/O method, including overlay, is associated with |
| 28 | each file descriptor. The only exceptions are applications not |
| 29 | exchanging data with a driver ("panel applications", see :ref:`open`) |
| 30 | and drivers permitting simultaneous video capturing and overlay using |
| 31 | the same file descriptor, for compatibility with V4L and earlier |
| 32 | versions of V4L2. |
| 33 | |
| 34 | ``VIDIOC_S_FMT`` and ``VIDIOC_REQBUFS`` would permit this to some |
| 35 | degree, but for simplicity drivers need not support switching the I/O |
| 36 | method (after first switching away from read/write) other than by |
| 37 | closing and reopening the device. |
| 38 | |
| 39 | The following sections describe the various I/O methods in more detail. |
| 40 | |
| 41 | |
| 42 | .. toctree:: |
| 43 | :maxdepth: 1 |
| 44 | |
| 45 | rw |
| 46 | mmap |
| 47 | userp |
| 48 | dmabuf |
| 49 | async |
| 50 | buffer |
| 51 | field-order |
| 52 | |
| 53 | |
| 54 | |
| 55 | |
| 56 | .. ------------------------------------------------------------------------------ |
| 57 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 58 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 59 | .. from the linux kernel, refer to: |
| 60 | .. |
| 61 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 62 | .. ------------------------------------------------------------------------------ |