diff options
author | Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> | 2016-04-12 19:40:46 -0300 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-04-14 22:37:02 -0300 |
commit | fb9ffa6a7f7ef39cc0f14f417b66411be5492512 (patch) | |
tree | 5763fa3d455d88c597b49969e04fe2825a0a2a38 /Documentation | |
parent | 3e9a0e0bfafdf6c28c520d43fd64c5775d04662f (diff) |
[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')
-rw-r--r-- | Documentation/media/uapi/v4l/buffer.rst | 3 | ||||
-rw-r--r-- | Documentation/media/uapi/v4l/dev-meta.rst | 58 | ||||
-rw-r--r-- | Documentation/media/uapi/v4l/devices.rst | 1 | ||||
-rw-r--r-- | Documentation/media/uapi/v4l/vidioc-querycap.rst | 3 | ||||
-rw-r--r-- | Documentation/media/videodev2.h.rst.exceptions | 2 |
5 files changed, 67 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 diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions index e11a0d0a8931..c9c611b18ba1 100644 --- a/Documentation/media/videodev2.h.rst.exceptions +++ b/Documentation/media/videodev2.h.rst.exceptions @@ -27,6 +27,7 @@ replace symbol V4L2_FIELD_SEQ_TB :c:type:`v4l2_field` replace symbol V4L2_FIELD_TOP :c:type:`v4l2_field` # Documented enum v4l2_buf_type +replace symbol V4L2_BUF_TYPE_META_CAPTURE :c:type:`v4l2_buf_type` replace symbol V4L2_BUF_TYPE_SDR_CAPTURE :c:type:`v4l2_buf_type` replace symbol V4L2_BUF_TYPE_SDR_OUTPUT :c:type:`v4l2_buf_type` replace symbol V4L2_BUF_TYPE_SLICED_VBI_CAPTURE :c:type:`v4l2_buf_type` @@ -152,6 +153,7 @@ replace define V4L2_CAP_MODULATOR device-capabilities replace define V4L2_CAP_SDR_CAPTURE device-capabilities replace define V4L2_CAP_EXT_PIX_FORMAT device-capabilities replace define V4L2_CAP_SDR_OUTPUT device-capabilities +replace define V4L2_CAP_META_CAPTURE device-capabilities replace define V4L2_CAP_READWRITE device-capabilities replace define V4L2_CAP_ASYNCIO device-capabilities replace define V4L2_CAP_STREAMING device-capabilities |