summaryrefslogtreecommitdiffstats
path: root/Documentation/media/uapi
diff options
context:
space:
mode:
authorLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>2016-04-12 19:40:46 -0300
committerMauro Carvalho Chehab <mchehab@s-opensource.com>2017-04-14 22:37:02 -0300
commitfb9ffa6a7f7ef39cc0f14f417b66411be5492512 (patch)
tree5763fa3d455d88c597b49969e04fe2825a0a2a38 /Documentation/media/uapi
parent3e9a0e0bfafdf6c28c520d43fd64c5775d04662f (diff)
downloadlinux-fb9ffa6a7f7ef39cc0f14f417b66411be5492512.tar.bz2
[media] v4l: Add metadata buffer type and format
The metadata buffer type is used to transfer metadata between userspace and kernelspace through a V4L2 buffers queue. It comes with a new metadata capture capability and format description. Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> Tested-by: Guennadi Liakhovetski <guennadi.liakhovetski@intel.com> Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com> Acked-by: Hans Verkuil <hans.verkuil@cisco.com> [hans.verkuil@cisco.com: removed left-over 'experimental' note] [hans.verkuil@cisco.com: add newline after _v4l2-meta-format label] Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'Documentation/media/uapi')
-rw-r--r--Documentation/media/uapi/v4l/buffer.rst3
-rw-r--r--Documentation/media/uapi/v4l/dev-meta.rst58
-rw-r--r--Documentation/media/uapi/v4l/devices.rst1
-rw-r--r--Documentation/media/uapi/v4l/vidioc-querycap.rst3
4 files changed, 65 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst
index d1e0d55dc219..64613d935edd 100644
--- a/Documentation/media/uapi/v4l/buffer.rst
+++ b/Documentation/media/uapi/v4l/buffer.rst
@@ -440,6 +440,9 @@ enum v4l2_buf_type
- 12
- Buffer for Software Defined Radio (SDR) output stream, see
:ref:`sdr`.
+ * - ``V4L2_BUF_TYPE_META_CAPTURE``
+ - 13
+ - Buffer for metadata capture, see :ref:`metadata`.
diff --git a/Documentation/media/uapi/v4l/dev-meta.rst b/Documentation/media/uapi/v4l/dev-meta.rst
new file mode 100644
index 000000000000..62518adfe37b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-meta.rst
@@ -0,0 +1,58 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _metadata:
+
+******************
+Metadata Interface
+******************
+
+Metadata refers to any non-image data that supplements video frames with
+additional information. This may include statistics computed over the image
+or frame capture parameters supplied by the image source. This interface is
+intended for transfer of metadata to userspace and control of that operation.
+
+The metadata interface is implemented on video capture device nodes. The device
+can be dedicated to metadata or can implement both video and metadata capture
+as specified in its reported capabilities.
+
+Querying Capabilities
+=====================
+
+Device nodes supporting the metadata interface set the ``V4L2_CAP_META_CAPTURE``
+flag in the ``device_caps`` field of the
+:c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP`
+ioctl. That flag means the device can capture metadata to memory.
+
+At least one of the read/write or streaming I/O methods must be supported.
+
+
+Data Format Negotiation
+=======================
+
+The metadata device uses the :ref:`format` ioctls to select the capture format.
+The metadata buffer content format is bound to that selected format. In addition
+to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be
+supported as well.
+
+To use the :ref:`format` ioctls applications set the ``type`` field of the
+:c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` and use the
+:c:type:`v4l2_meta_format` ``meta`` member of the ``fmt`` union as needed per
+the desired operation. Both drivers and applications must set the remainder of
+the :c:type:`v4l2_format` structure to 0.
+
+.. _v4l2-meta-format:
+
+.. flat-table:: struct v4l2_meta_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u32
+ - ``dataformat``
+ - The data format, set by the application. This is a little endian
+ :ref:`four character code <v4l2-fourcc>`. V4L2 defines metadata formats
+ in :ref:`meta-formats`.
+ * - __u32
+ - ``buffersize``
+ - Maximum buffer size in bytes required for data. The value is set by the
+ driver.
diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
index 5c3d6c29e12c..fb7f8c26cf09 100644
--- a/Documentation/media/uapi/v4l/devices.rst
+++ b/Documentation/media/uapi/v4l/devices.rst
@@ -25,3 +25,4 @@ Interfaces
dev-touch
dev-event
dev-subdev
+ dev-meta
diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst
index 165d8314327e..12e0d9a63cd8 100644
--- a/Documentation/media/uapi/v4l/vidioc-querycap.rst
+++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst
@@ -236,6 +236,9 @@ specification the ioctl returns an ``EINVAL`` error code.
* - ``V4L2_CAP_SDR_OUTPUT``
- 0x00400000
- The device supports the :ref:`SDR Output <sdr>` interface.
+ * - ``V4L2_CAP_META_CAPTURE``
+ - 0x00800000
+ - The device supports the :ref:`metadata` capture interface.
* - ``V4L2_CAP_READWRITE``
- 0x01000000
- The device supports the :ref:`read() <rw>` and/or