1 files changed, 91 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst
new file mode 100644
index 000000000..35bbb2fea
--- /dev/null
+++ b/Documentation/userspace-api/media/v4l/format.rst
@@ -0,0 +1,91 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: V4L
+
+.. _format:
+
+************
+Data Formats
+************
+
+Data Format Negotiation
+=======================
+
+Different devices exchange different kinds of data with applications,
+for example video images, raw or sliced VBI data, RDS datagrams. Even
+within one kind many different formats are possible, in particular there is an
+abundance of image formats. Although drivers must provide a default and
+the selection persists across closing and reopening a device,
+applications should always negotiate a data format before engaging in
+data exchange. Negotiation means the application asks for a particular
+format and the driver selects and reports the best the hardware can do
+to satisfy the request. Of course applications can also just query the
+current selection.
+
+A single mechanism exists to negotiate all data formats using the
+aggregate struct :c:type:`v4l2_format` and the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine
+what the hardware *could* do, without actually selecting a new data
+format. The data formats supported by the V4L2 API are covered in the
+respective device section in :ref:`devices`. For a closer look at
+image formats see :ref:`pixfmt`.
+
+The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the
+initialization sequence. Prior to this point multiple panel applications
+can access the same device concurrently to select the current input,
+change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+assigns a logical stream (video data, VBI data etc.) exclusively to one
+file descriptor.
+
+Exclusive means no other application, more precisely no other file
+descriptor, can grab this stream or change device properties
+inconsistent with the negotiated parameters. A video standard change for
+example, when the new standard uses a different number of scan lines,
+can invalidate the selected image format. Therefore only the file
+descriptor owning the stream can make invalidating changes. Accordingly
+multiple file descriptors which grabbed different logical streams
+prevent each other from interfering with their settings. When for
+example video overlay is about to start or already in progress,
+simultaneous video capturing may be restricted to the same cropping and
+image size.
+
+When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side
+effects are implied by the next step, the selection of an I/O method
+with the :ref:`VIDIOC_REQBUFS` ioctl or implicit
+with the first :c:func:`read()` or
+:c:func:`write()` call.
+
+Generally only one logical stream can be assigned to a file descriptor,
+the exception being drivers permitting simultaneous video capturing and
+overlay using the same file descriptor for compatibility with V4L and
+earlier versions of V4L2. Switching the logical stream or returning into
+"panel mode" is possible by closing and reopening the device. Drivers
+*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
+
+All drivers exchanging data with applications must support the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.
+
+Image Format Enumeration
+========================
+
+Apart of the generic format negotiation functions a special ioctl to
+enumerate all image formats supported by video capture, overlay or
+output devices is available. [#f1]_
+
+The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported
+by all drivers exchanging image data with applications.
+
+.. important::
+
+    Drivers are not supposed to convert image formats in kernel space.
+    They must enumerate only formats directly supported by the hardware.
+    If necessary driver writers should publish an example conversion
+    routine or library for integration into applications.
+
+.. [#f1]
+   Enumerating formats an application has no a-priori knowledge of
+   (otherwise it could explicitly ask for them and need not enumerate)
+   seems useless, but there are applications serving as proxy between
+   drivers and the actual video applications for which this is useful.