Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit fb9ffa6a authored by Laurent Pinchart's avatar Laurent Pinchart Committed by Mauro Carvalho Chehab
Browse files

[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: default avatarLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Tested-by: default avatarGuennadi Liakhovetski <guennadi.liakhovetski@intel.com>
Acked-by: default avatarSakari Ailus <sakari.ailus@linux.intel.com>
Acked-by: default avatarHans 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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 3e9a0e0b

Documentation/media/uapi/v4l/buffer.rst

+3 −0
Original line number Diff line number Diff line
@@ -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`.

Documentation/media/uapi/v4l/dev-meta.rst

0 → 100644
+58 −0
Original line number Diff line number Diff line 
.. -*- 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.

Documentation/media/uapi/v4l/devices.rst

+1 −0
Original line number Diff line number Diff line
@@ -25,3 +25,4 @@ Interfaces 
    dev-touch

    dev-event

    dev-subdev

    dev-meta

Documentation/media/uapi/v4l/vidioc-querycap.rst

+3 −0
Original line number Diff line number Diff line
@@ -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

Documentation/media/videodev2.h.rst.exceptions

+2 −0
Original line number Diff line number Diff line
@@ -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