Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _rw: |
| 4 | |
| 5 | ********** |
| 6 | Read/Write |
| 7 | ********** |
| 8 | |
| 9 | Input and output devices support the :c:func:`read()` and |
| 10 | :c:func:`write()` function, respectively, when the |
| 11 | ``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct |
| 12 | :ref:`v4l2_capability <v4l2-capability>` returned by the |
| 13 | :ref:`VIDIOC_QUERYCAP <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 | |
| 27 | :: |
| 28 | |
| 29 | > vidctrl /dev/video --input=0 --format=YUYV --size=352x288 |
| 30 | > dd if=/dev/video of=myimage.422 bs=202752 count=1 |
| 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. [1]_ When reading or writing is supported, the |
| 35 | driver must also support the :ref:`select() <func-select>` and |
| 36 | :ref:`poll() <func-poll>` function. [2]_ |
| 37 | |
| 38 | .. [1] |
| 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 | .. [2] |
| 46 | At the driver level :c:func:`select()` and :c:func:`poll()` are |
| 47 | the same, and :c:func:`select()` is too important to be optional. |
| 48 | |
| 49 | |
| 50 | .. ------------------------------------------------------------------------------ |
| 51 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 52 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 53 | .. from the linux kernel, refer to: |
| 54 | .. |
| 55 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 56 | .. ------------------------------------------------------------------------------ |