@@ -39,19 +39,26 @@ Arguments
Description
===========
-To enumerate image formats applications initialize the ``type`` and
-``index`` field of struct :c:type:`v4l2_fmtdesc` and call
-the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
-fill the rest of the structure or return an ``EINVAL`` error code. All
-formats are enumerable by beginning at index zero and incrementing by
-one until ``EINVAL`` is returned. If applicable, drivers shall return
-formats in preference order, where preferred formats are returned before
-(that is, with lower ``index`` value) less-preferred formats.
-
-.. note::
-
- After switching input or output the list of enumerated image
- formats may be different.
+To enumerate image formats applications initialize the ``type``, ``index`` and
+``mbus_code`` fields of struct :c:type:`v4l2_fmtdesc` and call the
+:ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers fill the
+rest of the structure or return an ``EINVAL`` error code. All formats are
+enumerable by beginning at index zero and incrementing by one until ``EINVAL``
+is returned. If applicable, drivers shall return formats in preference order,
+where preferred formats are returned before (that is, with lower ``index``
+value) less-preferred formats.
+
+If the ``mbus_code`` is set to zero, drivers shall enumerate all image formats
+supported by the device. For video node-centric devices, the enumerated formats
+may depend on the active input or output of the device. For MC-centric devices,
+the enumerated formats shall not depend on the active configuration of the
+device.
+
+If the ``mbus_code`` field is set to a non-zero value, drivers shall restrict
+enumeration to only the image formats that can be produced from that media bus
+code, and set the ``V4L2_FMT_FLAG_MBUS_CODE`` flag in the ``flags`` field. The
+enumerated imge formats shall not depend on the active configuration of the
+device. Enumeration shall otherwise operate as previously described.
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -145,6 +152,13 @@ formats in preference order, where preferred formats are returned before
parameters are detected. This flag can only be used in combination
with the ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
compressed formats only. It is also only applies to stateful codecs.
+ * - ``V4L2_FMT_FLAG_MBUS_CODE``
+ - 0x0010
+ - The ``mbus_code`` field has been taken into account and only formats
+ compatible with the supplied media bus code are enumerated. This flag
+ shall only be set by drivers, and only when ``mbus_code`` is not zero.
+ Applications may read the flag to check if code-aware enumeration is
+ supported by the driver.
Return Value
@@ -264,12 +264,13 @@ static void v4l_print_fmtdesc(const void *arg, bool write_only)
{
const struct v4l2_fmtdesc *p = arg;
- pr_cont("index=%u, type=%s, flags=0x%x, pixelformat=%c%c%c%c, description='%.*s'\n",
+ pr_cont("index=%u, type=%s, flags=0x%x, pixelformat=%c%c%c%c, mbus_code=0x%04x, description='%.*s'\n",
p->index, prt_names(p->type, v4l2_type_names),
p->flags, (p->pixelformat & 0xff),
(p->pixelformat >> 8) & 0xff,
(p->pixelformat >> 16) & 0xff,
(p->pixelformat >> 24) & 0xff,
+ p->mbus_code,
(int)sizeof(p->description), p->description);
}
@@ -1416,12 +1417,17 @@ static int v4l_enum_fmt(const struct v4l2_ioctl_ops *ops,
struct video_device *vdev = video_devdata(file);
struct v4l2_fmtdesc *p = arg;
int ret = check_fmt(file, p->type);
+ u32 mbus_code;
u32 cap_mask;
if (ret)
return ret;
ret = -EINVAL;
+ mbus_code = p->mbus_code;
+ CLEAR_AFTER_FIELD(p, type);
+ p->mbus_code = mbus_code;
+
switch (p->type) {
case V4L2_BUF_TYPE_VIDEO_CAPTURE:
case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE:
@@ -2703,7 +2709,7 @@ DEFINE_V4L_STUB_FUNC(dv_timings_cap)
static const struct v4l2_ioctl_info v4l2_ioctls[] = {
IOCTL_INFO(VIDIOC_QUERYCAP, v4l_querycap, v4l_print_querycap, 0),
- IOCTL_INFO(VIDIOC_ENUM_FMT, v4l_enum_fmt, v4l_print_fmtdesc, INFO_FL_CLEAR(v4l2_fmtdesc, type)),
+ IOCTL_INFO(VIDIOC_ENUM_FMT, v4l_enum_fmt, v4l_print_fmtdesc, 0),
IOCTL_INFO(VIDIOC_G_FMT, v4l_g_fmt, v4l_print_format, 0),
IOCTL_INFO(VIDIOC_S_FMT, v4l_s_fmt, v4l_print_format, INFO_FL_PRIO),
IOCTL_INFO(VIDIOC_REQBUFS, v4l_reqbufs, v4l_print_requestbuffers, INFO_FL_PRIO | INFO_FL_QUEUE),
@@ -777,13 +777,15 @@ struct v4l2_fmtdesc {
__u32 flags;
__u8 description[32]; /* Description string */
__u32 pixelformat; /* Format fourcc */
- __u32 reserved[4];
+ __u32 mbus_code; /* Media bus code */
+ __u32 reserved[3];
};
#define V4L2_FMT_FLAG_COMPRESSED 0x0001
#define V4L2_FMT_FLAG_EMULATED 0x0002
#define V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM 0x0004
#define V4L2_FMT_FLAG_DYN_RESOLUTION 0x0008
+#define V4L2_FMT_FLAG_MBUS_CODE 0x0010
/* Frame Size and frame rate enumeration */
/*
The VIDIOC_ENUM_FMT ioctl enumerates all formats supported by a video node. For MC-centric devices, its behaviour has always been ill-defined, with drivers implementing one of the following behaviours: - No support for VIDIOC_ENUM_FMT at all - Enumerating all formats supported by the video node, regardless of the configuration of the pipeline - Enumerating formats supported by the video node for the active configuration of the connected subdevice The first behaviour is obviously useless for applications. The second behaviour provides the most information, but doesn't offer a way to find what formats are compatible with a given pipeline configuration. The third behaviour fixes that, but with the drawback that applications can't enumerate all supported formats anymore, and have to modify the active configuration of the pipeline to enumerate formats. The situation is messy as none of the implemented behaviours are ideal, and userspace can't predict what will happen as the behaviour is driver-specific. To fix this, let's extend the VIDIOC_ENUM_FMT with a missing capability: enumerating pixel formats for a given media bus code. The media bus code is passed through the v4l2_fmtdesc structure in a new mbus_code field (repurposed from the reserved fields), and an additional flag is added to report if the driver supports this API extension. With this capability in place, applications can enumerate pixel formats for a given media bus code without modifying the active configuration of the device. The current behaviour of the ioctl is preserved when the new mbus_code field is set to 0, ensuring compatibility with existing userspace. This behaviour is now documented as mandatory for MC-centric devices as well as the traditional video node-centric devices. This allows applications to query MC-centric devices for all the supported pixel formats, as well as for the pixel formats corresponding to a given media bus code. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> --- Hello, This API extension comes from a need I encountered when working on a simple pipeline handler for libcamera. The pipeline handlers we have so far are device-specific, and hardcode knowledge about the device drivers in their implementation, such as the mapping from media bus codes to pixel formats. For "simple" devices (currently defined as linear pipelines with no processing, which we will probably extend to include basic processing such as scaling and format conversion in the future), we want to have a single pipeline handler that will auto-configure the pipeline based on information retrieved from the kernel. I thus need an API to extract the mapping from media bus code to pixel format. Once Niklas patches that add V4L2_CAP_IO_MC land in master, I think this patch should be rebased, and specify that this API is mandatory for drivers that expose V4L2_CAP_IO_MC and invalid otherwise. It would be a good step towards correctly specifying the behaviour of video nodes for MC-centric devices. I will of course provide patches for v4l2-ctrl to support this extension, as well as for v4l2-compliance, but I would like feedback on the API first. .../media/uapi/v4l/vidioc-enum-fmt.rst | 40 +++++++++++++------ drivers/media/v4l2-core/v4l2-ioctl.c | 10 ++++- include/uapi/linux/videodev2.h | 4 +- 3 files changed, 38 insertions(+), 16 deletions(-)