V4L: add "function" sysfs attribute to v4l devices

From: Kay Sievers <[email protected]>

This adds a "function" string to help userspace to identify the type of device if multiple streams are available for a single v4l device.

This is meant to be used with udev, to create persistent device links for v4l devices, which will not depend on module-loading/device-enumeration order.

Cc Kees Cook <[email protected]>

Signed-off-by Kay Sievers <[email protected]>

---
 drivers/media/video/v4l2-common.c |   39
++++++++++++++++++++++++++++++++++++++ drivers/media/video/videodev.c    | 
 13 ++++++++++++
 include/linux/videodev2.h         |   16 +++++++++++++++
 include/media/v4l2-common.h       |    3 ++
 include/media/v4l2-dev.h          |    1
 5 files changed, 72 insertions(+)

---
diff -r 6aa6656852cb linux/drivers/media/video/v4l2-common.c
--- a/linux/drivers/media/video/v4l2-common.c Wed Apr 16 13:13:15 2008
-0300 +++ b/linux/drivers/media/video/v4l2-common.c Wed Apr 16 17:52:29
2008 -0700 @@ -81,6 +81,45 @@ MODULE_LICENSE("GPL");
* Video Standard Operations (contributed by Michael Schimek) */

linux/drivers/media/video/v4l2-common.c +15 -0

+/*
+ * Exports "function" string to userspace to identify the type of device
+ * if multiple streams are available for a single device.
+ *
+ * Types/string names should be reused if possible, instead of adding
+ * new very device specific types, they must _uniquely_ identify all
+ * streams belonging to the _same_ device though.
+ *
+ * No single device must export multiple streams with the same function
+ * string, because userspace uses this to find the correct device node.
+ *
+ * Unlike the free-text "name", it must be an easily machine useable
+ * string containing only [a-z0-9._-] characters.
+ *
+ * Strings must not change without a valid reason, they are part of the

linux/drivers/media/video/v4l2-common.c +14 -0

+	[V4L2_FN_VBI_CAP]		= "vbi-cap",
+	[V4L2_FN_VBI_OUT]		= "vbi-out",
+	[V4L2_FN_PCM_CAP]		= "pcm-cap",
+	[V4L2_FN_PCM_OUT]		= "pcm-out",
+	[V4L2_FN_RADIO_CAP]		= "radio-cap",
+};
+
+const char *v4l2_function_name(enum v4l2_function_type function)
+{
+	if (function > 0 && function < ARRAY_SIZE(v4l2_function_type_names))
+		return v4l2_function_type_names[function];
+	return NULL;
+}
+EXPORT_SYMBOL(v4l2_function_name);
 
 /* ----------------------------------------------------------------- */
 /* priority handling                                                 */

diff -r 6aa6656852cb linux/drivers/media/video/videodev.c

linux/drivers/media/video/videodev.c +13 -0

@@ -451,6 +451,18 @@ static DEVICE_ATTR(dev, S_IRUGO, show_de
 static DEVICE_ATTR(dev, S_IRUGO, show_dev, NULL);
 #endif
 
+static ssize_t show_function(struct device *cd,
+			     struct device_attribute *attr, char *buf)
+{
+	struct video_device *vfd = container_of(cd, struct video_device,
+						class_dev);
+	const char *function_name = v4l2_function_name(vfd->function);
+
+	if (!function_name)
+		return -ENOSYS;
+	return sprintf(buf, "%s\n", v4l2_function_name(vfd->function));
+}
+
 struct video_device *video_device_alloc(void)
 {
 	struct video_device *vfd;

@@ -486,6 +498,7 @@ static void video_release(struct device
 #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,13)
 static struct device_attribute video_device_attrs[] = {
 	__ATTR(name, S_IRUGO, show_name, NULL),
+	__ATTR(function, S_IRUGO, show_function, NULL),
 	__ATTR_NULL
 };
 #endif

diff -r 6aa6656852cb linux/include/linux/videodev2.h

linux/include/linux/videodev2.h +16 -0

@@ -138,6 +138,22 @@ enum v4l2_field {
 	 (field) == V4L2_FIELD_INTERLACED_BT ||\
 	 (field) == V4L2_FIELD_SEQ_TB ||\
 	 (field) == V4L2_FIELD_SEQ_BT)
+
+/* Exports "function" string to userspace to identify type of device */
+enum v4l2_function_type {
+	V4L2_FN_UNDEFINED,
+	V4L2_FN_VIDEO_CAP,
+	V4L2_FN_VIDEO_OUT,
+	V4L2_FN_MPEG_CAP,
+	V4L2_FN_MPEG_OUT,
+	V4L2_FN_YUV_CAP,
+	V4L2_FN_YUV_OUT,
+	V4L2_FN_VBI_CAP,
+	V4L2_FN_VBI_OUT,
+	V4L2_FN_PCM_CAP,
+	V4L2_FN_PCM_OUT,
+	V4L2_FN_RADIO_CAP,
+};
 
 enum v4l2_buf_type {
 	V4L2_BUF_TYPE_VIDEO_CAPTURE        = 1,

diff -r 6aa6656852cb linux/include/media/v4l2-common.h

linux/include/media/v4l2-common.h +3 -0

@@ -67,6 +67,9 @@
 			v4l_client_printk(KERN_DEBUG, client, fmt , ## arg); \
 	} while (0)
 
+
+/* map function enum to string */
+extern const char *v4l2_function_name(enum v4l2_function_type function);
 
 /* Use this macro for non-I2C drivers. Pass the driver name as the first
 arg. */ #define v4l_print_ioctl(name, cmd)  		 \

diff -r 6aa6656852cb linux/include/media/v4l2-dev.h

linux/drivers/media/video/v4l2-common.c MODULE_LICENSE("GPL"); · line 108

Quoted 7 lines · Kees Cook

linux/drivers/media/video/v4l2-common.c +7 -0

+static const char *v4l2_function_type_names[] = {
+	[V4L2_FN_VIDEO_CAP]		= "vid-cap",
+	[V4L2_FN_VIDEO_OUT]		= "vid-out",
+	[V4L2_FN_MPEG_CAP]		= "mpeg-cap",
+	[V4L2_FN_MPEG_OUT]		= "mpeg-out",
+	[V4L2_FN_YUV_CAP]		= "yuv-cap",
+	[V4L2_FN_YUV_OUT]		= "yuv-out",

I don't like those. Video capture devices can encode pixels in a variety of formats. MPEG and YUV are only two special cases. You will find devices encoding in RGB, Bayer, MJPEG, ... as well as some proprietary formats.

If I understand your problem correctly, you want to differentiate between multiple v4l devices created by a single driver for a single hardware device. Using the above functions might work for ivtv but rules out devices that output multiple streams in the same format.

Wouldn't it be better to fix the ivtv driver to use a single device node for both compressed and uncompressed streams ?

Hi Laurent,

Quoted 13 lines · Laurent Pinchart

linux/drivers/media/video/v4l2-common.c MODULE_LICENSE("GPL"); · line 108

Quoted 7 lines · Kees Cook

linux/drivers/media/video/v4l2-common.c +7 -0

+static const char *v4l2_function_type_names[] = {
+	[V4L2_FN_VIDEO_CAP]		= "vid-cap",
+	[V4L2_FN_VIDEO_OUT]		= "vid-out",
+	[V4L2_FN_MPEG_CAP]		= "mpeg-cap",
+	[V4L2_FN_MPEG_OUT]		= "mpeg-out",
+	[V4L2_FN_YUV_CAP]		= "yuv-cap",
+	[V4L2_FN_YUV_OUT]		= "yuv-out",

I don't like those. Video capture devices can encode pixels in a variety of formats. MPEG and YUV are only two special cases. You will find devices encoding in RGB, Bayer, MJPEG, ... as well as some proprietary formats.

If these devices have a variable encoding method, perhaps just use "vid-cap" as the general rule. (In the case that the output formats are selectable from a given device node at runtime.)

Quoted 7 lines

If I understand your problem correctly, you want to differentiate between multiple v4l devices created by a single driver for a single hardware device. Using the above functions might work for ivtv but rules out devices that output multiple streams in the same format.

Wouldn't it be better to fix the ivtv driver to use a single device node for both compressed and uncompressed streams ?

I'm not very familiar with the v4l code base, so I don't have a good answer about if it's right or not. The core problem does tend to boil down to dealing with drivers that create multiple device nodes for the same physical hardware (ivtv is not alone in this regard).

I don't know what the semantics are for device mode vs device node in v4l, but it seems that since there are multiple nodes being created for a given piece of hardware, something needs to be exported to sysfs to distinguish them.

Quoted 15 lines · Kees Cook

Quoted 13 lines · Laurent Pinchart

linux/drivers/media/video/v4l2-common.c MODULE_LICENSE("GPL"); · line 108

Quoted 7 lines · Kees Cook

linux/drivers/media/video/v4l2-common.c +7 -0

+static const char *v4l2_function_type_names[] = {
+	[V4L2_FN_VIDEO_CAP]		= "vid-cap",
+	[V4L2_FN_VIDEO_OUT]		= "vid-out",
+	[V4L2_FN_MPEG_CAP]		= "mpeg-cap",
+	[V4L2_FN_MPEG_OUT]		= "mpeg-out",
+	[V4L2_FN_YUV_CAP]		= "yuv-cap",
+	[V4L2_FN_YUV_OUT]		= "yuv-out",

I don't like those. Video capture devices can encode pixels in a variety of formats. MPEG and YUV are only two special cases. You will find devices encoding in RGB, Bayer, MJPEG, ... as well as some proprietary formats.

Quoted 3 lines

If these devices have a variable encoding method, perhaps just use "vid-cap" as the general rule. (In the case that the output formats are selectable from a given device node at runtime.)

That would indeed be better. The function name should be derived from the v4l type if possible.

Quoted 4 lines

I don't know what the semantics are for device mode vs device node in v4l, but it seems that since there are multiple nodes being created for a given piece of hardware, something needs to be exported to sysfs to distinguish them.

Good point.

v4l drivers create several device nodes for good or not-so-good reasons. I think we can classify the hardware/drivers in several categories:

1. The device supports multiple concurrent data streams for different kind of data. The is most often found for audio/video or video/vbi. Audio is handled through alsa, and video and vbi are handled through v4l. The driver then creates a device node for each video/vbi data stream. The devices can easily be distinguished by their v4l type.

2. The device supports a single data stream with a selectable data format. The driver will create a single device node, format selection is handled through the v4l API.

3. The device supports multiple concurrent data streams for a single kind of data. ivtv falls under this case. The most common use case is a device with several video pipes (usually 2) that can be used simultaneously to stream the same data (in different or identical formats, either fixed or configurable).

Case 3 is the only one to cause device node naming issues. I'm not sure if the driver does the right thing when it creates several device nodes. Should the peripheral be seen as a single device that allows access by two users simultaneously, or should it be seen as two fixed-format devices ? Each solution will probably come with its own set of issues.

Hi Laurent,

Quoted 20 lines · Laurent Pinchart

Quoted 18 lines · Kees Cook

Quoted 13 lines · Laurent Pinchart

linux/drivers/media/video/v4l2-common.c MODULE_LICENSE("GPL"); · line 108

Quoted 7 lines · Kees Cook

linux/drivers/media/video/v4l2-common.c +7 -0

+static const char *v4l2_function_type_names[] = {
+	[V4L2_FN_VIDEO_CAP]		= "vid-cap",
+	[V4L2_FN_VIDEO_OUT]		= "vid-out",
+	[V4L2_FN_MPEG_CAP]		= "mpeg-cap",
+	[V4L2_FN_MPEG_OUT]		= "mpeg-out",
+	[V4L2_FN_YUV_CAP]		= "yuv-cap",
+	[V4L2_FN_YUV_OUT]		= "yuv-out",

I don't like those. Video capture devices can encode pixels in a variety of formats. MPEG and YUV are only two special cases. You will find devices encoding in RGB, Bayer, MJPEG, ... as well as some proprietary formats.

If these devices have a variable encoding method, perhaps just use "vid-cap" as the general rule. (In the case that the output formats are selectable from a given device node at runtime.)

Quoted 2 lines

That would indeed be better. The function name should be derived from the v4l type if possible.

Sure, but I think Kay's point was this it needs to be relatively "static" so that userspace (and udev) can depend on it not changing very much. I am not attached to any of the names in the proposed patch -- they work for me, but I'd be happy to see a different list if it were more sensible.

Quoted 20 lines

Quoted 4 lines

I don't know what the semantics are for device mode vs device node in v4l, but it seems that since there are multiple nodes being created for a given piece of hardware, something needs to be exported to sysfs to distinguish them.

Good point.

v4l drivers create several device nodes for good or not-so-good reasons. I think we can classify the hardware/drivers in several categories:

1. The device supports multiple concurrent data streams for different kind of data. The is most often found for audio/video or video/vbi. Audio is handled through alsa, and video and vbi are handled through v4l. The driver then creates a device node for each video/vbi data stream. The devices can easily be distinguished by their v4l type.

2. The device supports a single data stream with a selectable data format. The driver will create a single device node, format selection is handled through the v4l API.

Quoted 5 lines

3. The device supports multiple concurrent data streams for a single kind of data. ivtv falls under this case. The most common use case is a device with several video pipes (usually 2) that can be used simultaneously to stream the same data (in different or identical formats, either fixed or configurable).

Right -- case 3 is where the main problems and special-cases appeared when trying to work out a viable "static" path for udev to use to address a given v4l device.

Quoted 5 lines

Case 3 is the only one to cause device node naming issues. I'm not sure if the driver does the right thing when it creates several device nodes. Should the peripheral be seen as a single device that allows access by two users simultaneously, or should it be seen as two fixed-format devices ? Each solution will probably come with its own set of issues.

Whatever the situation, I doubt it will change soon for ivtv (or the others), so I'd like to see the basic functionality of the patch adopted. If there are things about it that aren't good, or could be improved about it, can you provide an updated patch to address any concerns? I think taking the patch through some iterations could help focus the discussion about it.

Kees introduced a patch set last week that attempts to get stable device naming for v4l. The set used a string attribute called function to allow udev to assemble a unique and stable path for device nodes.

This patch is similar. However, instead of a string an integer is used called "stream". If the driver calls video_register_device in the same order every time it is loaded then we can end up with something like this with the right udev rules[1]:

/dev/v4l/by-path/pci-0000\:00\:1d.2-usb-0\:1\:1.0-video0 /dev/v4l/by-path/pci-0000\:00\:1d.2-usb-0\:1\:1.0-video1 /dev/v4l/by-path/pci-0000\:00\:1d.2-usb-0\:1\:1.0-video2

Kees: I don't have a device that creates multiple device nodes. Please test with ivtv. :D

Kees: I don't have a device that creates multiple device nodes. Please test with ivtv. :D

Quoted 2 lines · Brandon Philips

Kees: I don't have a device that creates multiple device nodes. Please test with ivtv. :D

Unfortunately, this doesn't work with ivtv -- each device has a streamid of 0. (video0, video24, video32 all on the same PCI path reported stream 0)