From 76cb841cb886eef6b3bee341a2266c76578724ad Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 03:02:30 +0200 Subject: Adding upstream version 4.19.249. Signed-off-by: Daniel Baumann --- Documentation/media/uapi/v4l/rw.rst | 47 +++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 Documentation/media/uapi/v4l/rw.rst (limited to 'Documentation/media/uapi/v4l/rw.rst') diff --git a/Documentation/media/uapi/v4l/rw.rst b/Documentation/media/uapi/v4l/rw.rst new file mode 100644 index 000000000..91596c0cc --- /dev/null +++ b/Documentation/media/uapi/v4l/rw.rst @@ -0,0 +1,47 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _rw: + +********** +Read/Write +********** + +Input and output devices support the :ref:`read() ` and +:ref:`write() ` function, respectively, when the +``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct +:c:type:`v4l2_capability` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl is set. + +Drivers may need the CPU to copy the data, but they may also support DMA +to or from user memory, so this I/O method is not necessarily less +efficient than other methods merely exchanging buffer pointers. It is +considered inferior though because no meta-information like frame +counters or timestamps are passed. This information is necessary to +recognize frame dropping and to synchronize with other data streams. +However this is also the simplest I/O method, requiring little or no +setup to exchange data. It permits command line stunts like this (the +vidctrl tool is fictitious): + + +.. code-block:: none + + $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288 + $ dd if=/dev/video of=myimage.422 bs=202752 count=1 + +To read from the device applications use the :ref:`read() ` +function, to write the :ref:`write() ` function. Drivers +must implement one I/O method if they exchange data with applications, +but it need not be this. [#f1]_ When reading or writing is supported, the +driver must also support the :ref:`select() ` and +:ref:`poll() ` function. [#f2]_ + +.. [#f1] + It would be desirable if applications could depend on drivers + supporting all I/O interfaces, but as much as the complex memory + mapping I/O can be inadequate for some devices we have no reason to + require this interface, which is most useful for simple applications + capturing still images. + +.. [#f2] + At the driver level :ref:`select() ` and :ref:`poll() ` are + the same, and :ref:`select() ` is too important to be optional. -- cgit v1.2.3