[v3 0/3] media: Register read-only sub-dev devnode

[v3 0/3] media: Register read-only sub-dev devnode

[Jacopo Mondi]

Add new function v4l2_device_register_ro_subdev_nodes() to pair with
v4l2_device_register_subdev_nodes() that allows a bridge driver to register the
device node for its subdevices in read-only mode.

Devnode-centric (aka non-MC) bridge drivers control their subdevices through
direct calls to v4l2 subdev operations and do not want userspace to be able
to control the subdevice configuration by calling ioctls on the sub-device
devnode. For this reason, they usually refrain from registering any devnode at
all for their subdevices.

However it is sometimes required for userspace to access the sub-dev device
nodes to collect information on the actual configuration, without changing
the one currently applied to the device.

This requirement became pressing while working on libcamera on devnode-centric
platforms that do not expose any sub-device for their camera sensor to prevent
userspace from changing their configuration. To allow them to register device
node and being guaranteed to retain control of the subdevice configuration this
series proposes a way to register device nodes in read-only to restrict
access to all ioctls that could potentially affect the sub-dev configuration.

Thanks
   j

v1->v2:
- Documentation:
  - Add a new patch using Laurent's suggestion to update the sub-device
    userspace API introduction
  - Take in some of Laurent's suggestions in v4l2-subdev.rst and add a new
    section in dev-subdev.rst
- Implementation:
  - As noted by Andrey, V4L2_FL_* are meant to be used as bitmasks. Use
    test_bit()/set_bit() as the rest of the v4l2 core does. It's a bit an
    overkill compared to use plain BIT() as noted by Sakari but I preferred
    consistency with the rest of the core
  - Make v4l2_device_register_subdev_nodes() and
    v4l2_device_register_ro_subdev_nodes() to v4l2-device.h and make them
    inline functions. Documentation style has been copied from other functions
    with similar implementations, such as __video_register_device() in
    v4l2-dev.h

Jacopo Mondi (3):
  Documentation: media: Update sub-device API intro
  Documentation: media: Document read-only subdevice
  media: v4l2-dev: Add v4l2_device_register_ro_subdev_node()

 Documentation/media/kapi/v4l2-subdev.rst      | 53 ++++++++++++++++++-
 Documentation/media/uapi/v4l/dev-subdev.rst   |  5 ++
 .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
 Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
 .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
 .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 +++
 .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 +++
 .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 +++
 drivers/media/v4l2-core/v4l2-device.c         |  7 ++-
 drivers/media/v4l2-core/v4l2-subdev.c         | 19 +++++++
 include/media/v4l2-dev.h                      |  7 +++
 include/media/v4l2-device.h                   | 42 +++++++++++++--
 12 files changed, 170 insertions(+), 8 deletions(-)

--
2.25.1

[v2 1/3] Documentation: media: Update sub-device API intro

[Jacopo Mondi]

Update the V4L2 sub-device userspace API introduction to provide more
details on why complex devices might want to register devnodes for the
connected subdevices.

Suggested-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
---
 Documentation/media/kapi/v4l2-subdev.rst | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
index 29e07e23f888..41ccb3e5c707 100644
--- a/Documentation/media/kapi/v4l2-subdev.rst
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -275,8 +275,13 @@ system the .unbind() method is called. All three callbacks are optional.
 V4L2 sub-device userspace API
 -----------------------------
 
-Beside exposing a kernel API through the :c:type:`v4l2_subdev_ops` structure,
-V4L2 sub-devices can also be controlled directly by userspace applications.
+Bridge drivers traditionally expose one or multiple video nodes to userspace,
+and control subdevices through the :c:type:`v4l2_subdev_ops` operations in
+response to video node operations. This hides the complexity of the underlying
+hardware from applications. For complex devices, finer-grained control of the
+device than what the video nodes offer may be required. In those cases, bridge
+drivers that implement :ref:`the media controller API <media_controller>` may
+opt for making the subdevice operations directly accessible from userpace.
 
 Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access
 sub-devices directly. If a sub-device supports direct userspace configuration
-- 
2.25.1

[v2 2/3] Documentation: media: Document read-only subdevice

[Jacopo Mondi]

Document a new kapi function to register subdev device nodes in read only
mode and for each affected ioctl report how access is restricted.

Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
---
 Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
 Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
 .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
 Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
 .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
 .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
 .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
 .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
 8 files changed, 94 insertions(+)

diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
index 41ccb3e5c707..6506a673e6a1 100644
--- a/Documentation/media/kapi/v4l2-subdev.rst
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -332,6 +332,50 @@ Private ioctls
 	All ioctls not in the above list are passed directly to the sub-device
 	driver through the core::ioctl operation.
 
+Read-only sub-device userspace API
+----------------------------------
+
+Bridge drivers that control their connected subdevices through direct calls to
+the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
+want userspace to be able to change the same parameters through the subdevice
+device node and thus do not usually register any.
+
+It is sometimes useful to report to userspace the current subdevice
+configuration through a read-only API, that does not permit applications to
+change to the device parameters but allows interfacing to the subdevice device
+node to inspect them.
+
+For instance, to implement cameras based on computational photography, userspace
+needs to know the detailed camera sensor configuration (in terms of skipping,
+binning, cropping and scaling) for each supported output resolution. To support
+such use cases, bridge drivers may expose the subdevice operations to userspace
+through a read-only API.
+
+To create a read-only device node for all the subdevices registered with the
+``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
+:c:func:`v4l2_device_register_ro_subdev_nodes`.
+
+Access to the following ioctls for userspace applications is restricted on
+sub-device device nodes registered with
+:c:func:`v4l2_device_register_ro_subdev_nodes`.
+
+``VIDIOC_SUBDEV_S_FMT``,
+``VIDIOC_SUBDEV_S_CROP``,
+``VIDIOC_SUBDEV_S_SELECTION``:
+
+	These ioctls are only allowed on a read-only subdevice device node
+	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
+	formats and selection rectangles.
+
+``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
+``VIDIOC_SUBDEV_S_DV_TIMINGS``,
+``VIDIOC_SUBDEV_S_STD``:
+
+	These ioctls are not allowed on a read-only subdevice node.
+
+In case the ioclt is not allowed, or the format to modify is set to
+``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
+the errno variable is set to ``-EPERM``.
 
 I2C sub-device drivers
 ----------------------
diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
index 029bb2d9928a..6082f9c2f8f4 100644
--- a/Documentation/media/uapi/v4l/dev-subdev.rst
+++ b/Documentation/media/uapi/v4l/dev-subdev.rst
@@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
 Sub-device character device nodes, conventionally named
 ``/dev/v4l-subdev*``, use major number 81.
 
+Drivers may opt to limit the sub-device character devices to only expose
+operations that don't modify the device state. In such a case the sub-devices
+are referred to as ``read-only`` in the rest of this documentation, and the
+related restrictions are documented in individual ioctls.
+
 
 Controls
 ========
diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
index e36dd2622857..611f94e4510a 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
@@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
 structure as argument. If the ioctl is not supported or the timing
 values are not correct, the driver returns ``EINVAL`` error code.
 
+Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
+registered in read-only mode is not allowed. An error is returned and the errno
+variable is set to ``-EPERM``.
+
 The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
 the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
 the current input or output does not support DV timings (e.g. if
@@ -81,6 +85,8 @@ ENODATA
 EBUSY
     The device is busy and therefore can not change the timings.
 
+EPERM
+    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
 
 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 
diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
index e633e42e3910..e220b38b859f 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
@@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
 does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
 returned.
 
+Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
+in read-only mode is not allowed. An error is returned and the errno variable is
+set to ``-EPERM``.
 
 Return Value
 ============
@@ -79,3 +82,6 @@ EINVAL
 
 ENODATA
     Standard video timings are not supported for this input or output.
+
+EPERM
+    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
index 632ee053accc..62f5d9870ca7 100644
--- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
@@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
 applications querying the same sub-device would thus not interact with
 each other.
 
+If the subdev device node has been registered in read-only mode calls to
+``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
+``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
+variable is set to ``-EPERM``.
+
 Drivers must not return an error solely because the requested crop
 rectangle doesn't match the device capabilities. They must instead
 modify the rectangle to match what the hardware can provide. The
@@ -123,3 +128,7 @@ EINVAL
     references a non-existing pad, the ``which`` field references a
     non-existing format, or cropping is not supported on the given
     subdev pad.
+
+EPERM
+    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
+    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
index 472577bd1745..3a2f64bb00e7 100644
--- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
@@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
 a low-pass noise filter might crop pixels at the frame boundaries,
 modifying its output frame size.
 
+If the subdev device node has been registered in read-only mode calls to
+``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
+``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
+variable is set to ``-EPERM``.
+
 Drivers must not return an error solely because the requested format
 doesn't match the device capabilities. They must instead modify the
 format to match what the hardware can provide. The modified format
@@ -146,6 +151,9 @@ EINVAL
     ``pad`` references a non-existing pad, or the ``which`` field
     references a non-existing format.
 
+EPERM
+    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
+    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
 
 ============
 
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
index 4b1b4bc78bfe..34aa39096e3d 100644
--- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
@@ -65,6 +65,10 @@ struct
 contains the current frame interval as would be returned by a
 ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
 
+Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
+registered in read-only mode is not allowed. An error is returned and the errno
+variable is set to ``-EPERM``.
+
 Drivers must not return an error solely because the requested interval
 doesn't match the device capabilities. They must instead modify the
 interval to match what the hardware can provide. The modified interval
@@ -118,3 +122,7 @@ EINVAL
     :c:type:`v4l2_subdev_frame_interval`
     ``pad`` references a non-existing pad, or the pad doesn't support
     frame intervals.
+
+EPERM
+    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
+    subdevice.
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
index fc73d27e6d74..abd046cef612 100644
--- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
@@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
 See :ref:`subdev` for more information on how each selection target
 affects the image processing pipeline inside the subdevice.
 
+If the subdev device node has been registered in read-only mode calls to
+``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
+``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
+variable is set to ``-EPERM``.
 
 Types of selection targets
 --------------------------
@@ -123,3 +127,7 @@ EINVAL
     ``pad`` references a non-existing pad, the ``which`` field
     references a non-existing format, or the selection target is not
     supported on the given subdev pad.
+
+EPERM
+    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
+    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
-- 
2.25.1

[v2 3/3] media: v4l2-dev: Add v4l2_device_register_ro_subdev_node()

[Jacopo Mondi]

Add to the V4L2 core a function to register device nodes for video
subdevices in read-only mode.

Registering a device node in read-only mode is useful to expose to
userspace the current sub-device configuration, without allowing
application to change it by using the V4L2 subdevice ioctls.

Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
---
 drivers/media/v4l2-core/v4l2-device.c |  7 +++--
 drivers/media/v4l2-core/v4l2-subdev.c | 19 ++++++++++++
 include/media/v4l2-dev.h              |  7 +++++
 include/media/v4l2-device.h           | 42 ++++++++++++++++++++++++---
 4 files changed, 69 insertions(+), 6 deletions(-)

diff --git a/drivers/media/v4l2-core/v4l2-device.c b/drivers/media/v4l2-core/v4l2-device.c
index c69941214bb2..4517a70379ce 100644
--- a/drivers/media/v4l2-core/v4l2-device.c
+++ b/drivers/media/v4l2-core/v4l2-device.c
@@ -186,7 +186,8 @@ static void v4l2_device_release_subdev_node(struct video_device *vdev)
 	kfree(vdev);
 }

-int v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
+int __v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev,
+					bool read_only)
 {
 	struct video_device *vdev;
 	struct v4l2_subdev *sd;
@@ -215,6 +216,8 @@ int v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
 		vdev->fops = &v4l2_subdev_fops;
 		vdev->release = v4l2_device_release_subdev_node;
 		vdev->ctrl_handler = sd->ctrl_handler;
+		if (read_only)
+			set_bit(V4L2_FL_RO_DEVNODE, &vdev->flags);
 		err = __video_register_device(vdev, VFL_TYPE_SUBDEV, -1, 1,
 					      sd->owner);
 		if (err < 0) {
@@ -252,7 +255,7 @@ int v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)

 	return err;
 }
-EXPORT_SYMBOL_GPL(v4l2_device_register_subdev_nodes);
+EXPORT_SYMBOL_GPL(__v4l2_device_register_subdev_nodes);

 void v4l2_device_unregister_subdev(struct v4l2_subdev *sd)
 {
diff --git a/drivers/media/v4l2-core/v4l2-subdev.c b/drivers/media/v4l2-core/v4l2-subdev.c
index a376b351135f..87fea21919fc 100644
--- a/drivers/media/v4l2-core/v4l2-subdev.c
+++ b/drivers/media/v4l2-core/v4l2-subdev.c
@@ -331,6 +331,7 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
 	struct v4l2_fh *vfh = file->private_data;
 #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
 	struct v4l2_subdev_fh *subdev_fh = to_v4l2_subdev_fh(vfh);
+	bool ro_subdev = test_bit(V4L2_FL_RO_DEVNODE, &vdev->flags);
 #endif
 	int rval;

@@ -477,6 +478,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
 	case VIDIOC_SUBDEV_S_FMT: {
 		struct v4l2_subdev_format *format = arg;

+		if (format->which != V4L2_SUBDEV_FORMAT_TRY && ro_subdev)
+			return -EPERM;
+
 		memset(format->reserved, 0, sizeof(format->reserved));
 		memset(format->format.reserved, 0, sizeof(format->format.reserved));
 		return v4l2_subdev_call(sd, pad, set_fmt, subdev_fh->pad, format);
@@ -504,6 +508,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
 		struct v4l2_subdev_crop *crop = arg;
 		struct v4l2_subdev_selection sel;

+		if (crop->which != V4L2_SUBDEV_FORMAT_TRY && ro_subdev)
+			return -EPERM;
+
 		memset(crop->reserved, 0, sizeof(crop->reserved));
 		memset(&sel, 0, sizeof(sel));
 		sel.which = crop->which;
@@ -545,6 +552,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
 	case VIDIOC_SUBDEV_S_FRAME_INTERVAL: {
 		struct v4l2_subdev_frame_interval *fi = arg;

+		if (ro_subdev)
+			return -EPERM;
+
 		memset(fi->reserved, 0, sizeof(fi->reserved));
 		return v4l2_subdev_call(sd, video, s_frame_interval, arg);
 	}
@@ -568,6 +578,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
 	case VIDIOC_SUBDEV_S_SELECTION: {
 		struct v4l2_subdev_selection *sel = arg;

+		if (sel->which != V4L2_SUBDEV_FORMAT_TRY && ro_subdev)
+			return -EPERM;
+
 		memset(sel->reserved, 0, sizeof(sel->reserved));
 		return v4l2_subdev_call(
 			sd, pad, set_selection, subdev_fh->pad, sel);
@@ -604,6 +617,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
 		return v4l2_subdev_call(sd, video, g_dv_timings, arg);

 	case VIDIOC_SUBDEV_S_DV_TIMINGS:
+		if (ro_subdev)
+			return -EPERM;
+
 		return v4l2_subdev_call(sd, video, s_dv_timings, arg);

 	case VIDIOC_SUBDEV_G_STD:
@@ -612,6 +628,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
 	case VIDIOC_SUBDEV_S_STD: {
 		v4l2_std_id *std = arg;

+		if (ro_subdev)
+			return -EPERM;
+
 		return v4l2_subdev_call(sd, video, s_std, *std);
 	}

diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index 4602c15ff878..bdbd953a976c 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -82,11 +82,18 @@ struct v4l2_ctrl_handler;
  *	but the old crop API will still work as expected in order to preserve
  *	backwards compatibility.
  *	Never set this flag for new drivers.
+ * @V4L2_FL_RO_DEVNODE:
+ *	indicates that the video device node is registered in read-only mode.
+ *	The flag only applies to device nodes registered for sub-devices, it is
+ *	set by the core when the sub-devices device nodes are registered with
+ *	v4l2_device_register_ro_subdev_nodes() and used by the sub-device ioctl
+ *	handler to restrict access to some ioctl calls.
  */
 enum v4l2_video_device_flags {
 	V4L2_FL_REGISTERED		= 0,
 	V4L2_FL_USES_V4L2_FH		= 1,
 	V4L2_FL_QUIRK_INVERTED_CROP	= 2,
+	V4L2_FL_RO_DEVNODE		= 3,
 };

 /* Priority helper functions */
diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h
index 7c912b7d2870..c01aa9df70b5 100644
--- a/include/media/v4l2-device.h
+++ b/include/media/v4l2-device.h
@@ -174,14 +174,48 @@ int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
 void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);

 /**
- * v4l2_device_register_subdev_nodes - Registers device nodes for all subdevs
- *	of the v4l2 device that are marked with
- *	the %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
+ * __v4l2_device_register_ro_subdev_nodes - Registers device nodes for
+ *      all subdevs of the v4l2 device that are marked with the
+ *      %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
  *
  * @v4l2_dev: pointer to struct v4l2_device
+ * @read_only: subdevices read-only flag. True to register the subdevices
+ *	device nodes in read-only mode, false to allow full access to the
+ *	subdevice userspace API.
  */
 int __must_check
-v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev);
+__v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev,
+				    bool read_only);
+
+/**
+ * v4l2_device_register_subdev_nodes - Registers subdevices device nodes with
+ *	unrestricted access to the subdevice userspace operations
+ *
+ * Internally calls __v4l2_device_register_subdev_nodes(). See its documentation
+ * for more details.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ */
+static inline int __must_check
+v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
+{
+	return __v4l2_device_register_subdev_nodes(v4l2_dev, false);
+}
+
+/**
+ * v4l2_device_register_ro_subdev_nodes - Registers subdevices device nodes
+ *	in read-only mode
+ *
+ * Internally calls __v4l2_device_register_subdev_nodes(). See its documentation
+ * for more details.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ */
+static inline int __must_check
+v4l2_device_register_ro_subdev_nodes(struct v4l2_device *v4l2_dev)
+{
+	return __v4l2_device_register_subdev_nodes(v4l2_dev, true);
+}

 /**
  * v4l2_subdev_notify - Sends a notification to v4l2_device.
--
2.25.1

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Sakari Ailus]

Hi Jacopo,

Thanks for the patchset.

On Fri, Mar 27, 2020 at 11:35:21PM +0100, Jacopo Mondi wrote:
> Document a new kapi function to register subdev device nodes in read only
> mode and for each affected ioctl report how access is restricted.
> 
> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> ---
>  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
>  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
>  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
>  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
>  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
>  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
>  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
>  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
>  8 files changed, 94 insertions(+)
> 
> diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
> index 41ccb3e5c707..6506a673e6a1 100644
> --- a/Documentation/media/kapi/v4l2-subdev.rst
> +++ b/Documentation/media/kapi/v4l2-subdev.rst
> @@ -332,6 +332,50 @@ Private ioctls
>  	All ioctls not in the above list are passed directly to the sub-device
>  	driver through the core::ioctl operation.
>  
> +Read-only sub-device userspace API
> +----------------------------------
> +
> +Bridge drivers that control their connected subdevices through direct calls to
> +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
> +want userspace to be able to change the same parameters through the subdevice
> +device node and thus do not usually register any.
> +
> +It is sometimes useful to report to userspace the current subdevice
> +configuration through a read-only API, that does not permit applications to
> +change to the device parameters but allows interfacing to the subdevice device
> +node to inspect them.
> +
> +For instance, to implement cameras based on computational photography, userspace
> +needs to know the detailed camera sensor configuration (in terms of skipping,
> +binning, cropping and scaling) for each supported output resolution. To support
> +such use cases, bridge drivers may expose the subdevice operations to userspace
> +through a read-only API.
> +
> +To create a read-only device node for all the subdevices registered with the
> +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> +
> +Access to the following ioctls for userspace applications is restricted on
> +sub-device device nodes registered with
> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> +
> +``VIDIOC_SUBDEV_S_FMT``,
> +``VIDIOC_SUBDEV_S_CROP``,
> +``VIDIOC_SUBDEV_S_SELECTION``:
> +
> +	These ioctls are only allowed on a read-only subdevice device node
> +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
> +	formats and selection rectangles.
> +
> +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
> +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
> +``VIDIOC_SUBDEV_S_STD``:
> +
> +	These ioctls are not allowed on a read-only subdevice node.
> +
> +In case the ioclt is not allowed, or the format to modify is set to

"IOCTL".

> +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
> +the errno variable is set to ``-EPERM``.
>  
>  I2C sub-device drivers
>  ----------------------
> diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
> index 029bb2d9928a..6082f9c2f8f4 100644
> --- a/Documentation/media/uapi/v4l/dev-subdev.rst
> +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
> @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
>  Sub-device character device nodes, conventionally named
>  ``/dev/v4l-subdev*``, use major number 81.
>  
> +Drivers may opt to limit the sub-device character devices to only expose
> +operations that don't modify the device state. In such a case the sub-devices
> +are referred to as ``read-only`` in the rest of this documentation, and the
> +related restrictions are documented in individual ioctls.

Perhaps "IOCTLs".

With these, for the set,

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

> +
>  
>  Controls
>  ========
> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> index e36dd2622857..611f94e4510a 100644
> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
>  structure as argument. If the ioctl is not supported or the timing
>  values are not correct, the driver returns ``EINVAL`` error code.
>  
> +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
> +registered in read-only mode is not allowed. An error is returned and the errno
> +variable is set to ``-EPERM``.
> +
>  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
>  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
>  the current input or output does not support DV timings (e.g. if
> @@ -81,6 +85,8 @@ ENODATA
>  EBUSY
>      The device is busy and therefore can not change the timings.
>  
> +EPERM
> +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
>  
>  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
>  
> diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> index e633e42e3910..e220b38b859f 100644
> --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
>  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
>  returned.
>  
> +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
> +in read-only mode is not allowed. An error is returned and the errno variable is
> +set to ``-EPERM``.
>  
>  Return Value
>  ============
> @@ -79,3 +82,6 @@ EINVAL
>  
>  ENODATA
>      Standard video timings are not supported for this input or output.
> +
> +EPERM
> +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> index 632ee053accc..62f5d9870ca7 100644
> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
>  applications querying the same sub-device would thus not interact with
>  each other.
>  
> +If the subdev device node has been registered in read-only mode calls to
> +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> +variable is set to ``-EPERM``.
> +
>  Drivers must not return an error solely because the requested crop
>  rectangle doesn't match the device capabilities. They must instead
>  modify the rectangle to match what the hardware can provide. The
> @@ -123,3 +128,7 @@ EINVAL
>      references a non-existing pad, the ``which`` field references a
>      non-existing format, or cropping is not supported on the given
>      subdev pad.
> +
> +EPERM
> +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> index 472577bd1745..3a2f64bb00e7 100644
> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
>  a low-pass noise filter might crop pixels at the frame boundaries,
>  modifying its output frame size.
>  
> +If the subdev device node has been registered in read-only mode calls to
> +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> +variable is set to ``-EPERM``.
> +
>  Drivers must not return an error solely because the requested format
>  doesn't match the device capabilities. They must instead modify the
>  format to match what the hardware can provide. The modified format
> @@ -146,6 +151,9 @@ EINVAL
>      ``pad`` references a non-existing pad, or the ``which`` field
>      references a non-existing format.
>  
> +EPERM
> +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
>  
>  ============
>  
> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> index 4b1b4bc78bfe..34aa39096e3d 100644
> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> @@ -65,6 +65,10 @@ struct
>  contains the current frame interval as would be returned by a
>  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
>  
> +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
> +registered in read-only mode is not allowed. An error is returned and the errno
> +variable is set to ``-EPERM``.
> +
>  Drivers must not return an error solely because the requested interval
>  doesn't match the device capabilities. They must instead modify the
>  interval to match what the hardware can provide. The modified interval
> @@ -118,3 +122,7 @@ EINVAL
>      :c:type:`v4l2_subdev_frame_interval`
>      ``pad`` references a non-existing pad, or the pad doesn't support
>      frame intervals.
> +
> +EPERM
> +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
> +    subdevice.
> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> index fc73d27e6d74..abd046cef612 100644
> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
>  See :ref:`subdev` for more information on how each selection target
>  affects the image processing pipeline inside the subdevice.
>  
> +If the subdev device node has been registered in read-only mode calls to
> +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> +variable is set to ``-EPERM``.
>  
>  Types of selection targets
>  --------------------------
> @@ -123,3 +127,7 @@ EINVAL
>      ``pad`` references a non-existing pad, the ``which`` field
>      references a non-existing format, or the selection target is not
>      supported on the given subdev pad.
> +
> +EPERM
> +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
> +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.

-- 
Regards,

Sakari Ailus

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Hans Verkuil]

Hi Jacopo,

Some comments below:

On 3/27/20 11:35 PM, Jacopo Mondi wrote:
> Document a new kapi function to register subdev device nodes in read only

kAPI

> mode and for each affected ioctl report how access is restricted.
> 
> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> ---
>  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
>  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
>  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
>  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
>  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
>  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
>  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
>  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
>  8 files changed, 94 insertions(+)
> 
> diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
> index 41ccb3e5c707..6506a673e6a1 100644
> --- a/Documentation/media/kapi/v4l2-subdev.rst
> +++ b/Documentation/media/kapi/v4l2-subdev.rst
> @@ -332,6 +332,50 @@ Private ioctls
>  	All ioctls not in the above list are passed directly to the sub-device
>  	driver through the core::ioctl operation.
>  
> +Read-only sub-device userspace API
> +----------------------------------
> +
> +Bridge drivers that control their connected subdevices through direct calls to
> +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
> +want userspace to be able to change the same parameters through the subdevice
> +device node and thus do not usually register any.
> +
> +It is sometimes useful to report to userspace the current subdevice
> +configuration through a read-only API, that does not permit applications to
> +change to the device parameters but allows interfacing to the subdevice device
> +node to inspect them.
> +
> +For instance, to implement cameras based on computational photography, userspace
> +needs to know the detailed camera sensor configuration (in terms of skipping,
> +binning, cropping and scaling) for each supported output resolution. To support
> +such use cases, bridge drivers may expose the subdevice operations to userspace
> +through a read-only API.
> +
> +To create a read-only device node for all the subdevices registered with the
> +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
> +:c:func:`v4l2_device_register_ro_subdev_nodes`.

Should we add something about creating a /dev/media device as well? It's basically
required for this functionality.

I think it might be a good idea to put v4l2_device_register_ro_subdev_nodes()
under #ifdef CONFIG_MEDIA_CONTROLLER so that this config *has* to be set in order
to be able to call this function. Or possibly have an explicit test in
__v4l2_device_register_subdev_nodes for the presence of a media device if
read_only is true.

> +
> +Access to the following ioctls for userspace applications is restricted on
> +sub-device device nodes registered with
> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> +
> +``VIDIOC_SUBDEV_S_FMT``,
> +``VIDIOC_SUBDEV_S_CROP``,
> +``VIDIOC_SUBDEV_S_SELECTION``:
> +
> +	These ioctls are only allowed on a read-only subdevice device node
> +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
> +	formats and selection rectangles.
> +
> +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
> +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
> +``VIDIOC_SUBDEV_S_STD``:
> +
> +	These ioctls are not allowed on a read-only subdevice node.
> +
> +In case the ioclt is not allowed, or the format to modify is set to
> +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
> +the errno variable is set to ``-EPERM``.
>  
>  I2C sub-device drivers
>  ----------------------
> diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
> index 029bb2d9928a..6082f9c2f8f4 100644
> --- a/Documentation/media/uapi/v4l/dev-subdev.rst
> +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
> @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
>  Sub-device character device nodes, conventionally named
>  ``/dev/v4l-subdev*``, use major number 81.
>  
> +Drivers may opt to limit the sub-device character devices to only expose
> +operations that don't modify the device state. In such a case the sub-devices

don't -> do not

("don't" is a bit too informal)

> +are referred to as ``read-only`` in the rest of this documentation, and the
> +related restrictions are documented in individual ioctls.
> +
>  
>  Controls
>  ========
> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> index e36dd2622857..611f94e4510a 100644
> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
>  structure as argument. If the ioctl is not supported or the timing
>  values are not correct, the driver returns ``EINVAL`` error code.
>  
> +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
> +registered in read-only mode is not allowed. An error is returned and the errno
> +variable is set to ``-EPERM``.
> +
>  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
>  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
>  the current input or output does not support DV timings (e.g. if
> @@ -81,6 +85,8 @@ ENODATA
>  EBUSY
>      The device is busy and therefore can not change the timings.
>  
> +EPERM
> +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
>  
>  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
>  
> diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> index e633e42e3910..e220b38b859f 100644
> --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
>  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
>  returned.
>  
> +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
> +in read-only mode is not allowed. An error is returned and the errno variable is
> +set to ``-EPERM``.
>  
>  Return Value
>  ============
> @@ -79,3 +82,6 @@ EINVAL
>  
>  ENODATA
>      Standard video timings are not supported for this input or output.
> +
> +EPERM
> +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> index 632ee053accc..62f5d9870ca7 100644
> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
>  applications querying the same sub-device would thus not interact with
>  each other.
>  
> +If the subdev device node has been registered in read-only mode calls to

mode calls -> mode, calls

> +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> +variable is set to ``-EPERM``.
> +
>  Drivers must not return an error solely because the requested crop
>  rectangle doesn't match the device capabilities. They must instead
>  modify the rectangle to match what the hardware can provide. The
> @@ -123,3 +128,7 @@ EINVAL
>      references a non-existing pad, the ``which`` field references a
>      non-existing format, or cropping is not supported on the given
>      subdev pad.
> +
> +EPERM
> +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> index 472577bd1745..3a2f64bb00e7 100644
> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
>  a low-pass noise filter might crop pixels at the frame boundaries,
>  modifying its output frame size.
>  
> +If the subdev device node has been registered in read-only mode calls to

ditto.

> +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> +variable is set to ``-EPERM``.
> +
>  Drivers must not return an error solely because the requested format
>  doesn't match the device capabilities. They must instead modify the
>  format to match what the hardware can provide. The modified format
> @@ -146,6 +151,9 @@ EINVAL
>      ``pad`` references a non-existing pad, or the ``which`` field
>      references a non-existing format.
>  
> +EPERM
> +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
>  
>  ============
>  
> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> index 4b1b4bc78bfe..34aa39096e3d 100644
> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> @@ -65,6 +65,10 @@ struct
>  contains the current frame interval as would be returned by a
>  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
>  
> +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
> +registered in read-only mode is not allowed. An error is returned and the errno
> +variable is set to ``-EPERM``.
> +
>  Drivers must not return an error solely because the requested interval
>  doesn't match the device capabilities. They must instead modify the
>  interval to match what the hardware can provide. The modified interval
> @@ -118,3 +122,7 @@ EINVAL
>      :c:type:`v4l2_subdev_frame_interval`
>      ``pad`` references a non-existing pad, or the pad doesn't support
>      frame intervals.
> +
> +EPERM
> +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
> +    subdevice.
> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> index fc73d27e6d74..abd046cef612 100644
> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
>  See :ref:`subdev` for more information on how each selection target
>  affects the image processing pipeline inside the subdevice.
>  
> +If the subdev device node has been registered in read-only mode calls to

ditto

> +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> +variable is set to ``-EPERM``.
>  
>  Types of selection targets
>  --------------------------
> @@ -123,3 +127,7 @@ EINVAL
>      ``pad`` references a non-existing pad, the ``which`` field
>      references a non-existing format, or the selection target is not
>      supported on the given subdev pad.
> +
> +EPERM
> +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
> +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> 

Regards,

	Hans

Re: [v2 3/3] media: v4l2-dev: Add v4l2_device_register_ro_subdev_node()

[Hans Verkuil]

On 3/27/20 11:35 PM, Jacopo Mondi wrote:
> Add to the V4L2 core a function to register device nodes for video
> subdevices in read-only mode.
> 
> Registering a device node in read-only mode is useful to expose to
> userspace the current sub-device configuration, without allowing
> application to change it by using the V4L2 subdevice ioctls.
> 
> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> ---
>  drivers/media/v4l2-core/v4l2-device.c |  7 +++--
>  drivers/media/v4l2-core/v4l2-subdev.c | 19 ++++++++++++
>  include/media/v4l2-dev.h              |  7 +++++
>  include/media/v4l2-device.h           | 42 ++++++++++++++++++++++++---
>  4 files changed, 69 insertions(+), 6 deletions(-)
> 
> diff --git a/drivers/media/v4l2-core/v4l2-device.c b/drivers/media/v4l2-core/v4l2-device.c
> index c69941214bb2..4517a70379ce 100644
> --- a/drivers/media/v4l2-core/v4l2-device.c
> +++ b/drivers/media/v4l2-core/v4l2-device.c
> @@ -186,7 +186,8 @@ static void v4l2_device_release_subdev_node(struct video_device *vdev)
>  	kfree(vdev);
>  }
> 
> -int v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
> +int __v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev,
> +					bool read_only)
>  {
>  	struct video_device *vdev;
>  	struct v4l2_subdev *sd;
> @@ -215,6 +216,8 @@ int v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
>  		vdev->fops = &v4l2_subdev_fops;
>  		vdev->release = v4l2_device_release_subdev_node;
>  		vdev->ctrl_handler = sd->ctrl_handler;
> +		if (read_only)
> +			set_bit(V4L2_FL_RO_DEVNODE, &vdev->flags);

I noticed the discussion about set_bit vs BIT: if memory serves, then at some point
in time setting/testing/clearing the V4L2_FL_REGISTERED had to be atomic. However,
looking at it today this no longer appears to be needed, so it can probably all be
replaced by normal bit operations. But that should be done in a separate patch if
anyone is interested in making that change.

>  		err = __video_register_device(vdev, VFL_TYPE_SUBDEV, -1, 1,
>  					      sd->owner);
>  		if (err < 0) {
> @@ -252,7 +255,7 @@ int v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
> 
>  	return err;
>  }
> -EXPORT_SYMBOL_GPL(v4l2_device_register_subdev_nodes);
> +EXPORT_SYMBOL_GPL(__v4l2_device_register_subdev_nodes);
> 
>  void v4l2_device_unregister_subdev(struct v4l2_subdev *sd)
>  {
> diff --git a/drivers/media/v4l2-core/v4l2-subdev.c b/drivers/media/v4l2-core/v4l2-subdev.c
> index a376b351135f..87fea21919fc 100644
> --- a/drivers/media/v4l2-core/v4l2-subdev.c
> +++ b/drivers/media/v4l2-core/v4l2-subdev.c
> @@ -331,6 +331,7 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
>  	struct v4l2_fh *vfh = file->private_data;
>  #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
>  	struct v4l2_subdev_fh *subdev_fh = to_v4l2_subdev_fh(vfh);
> +	bool ro_subdev = test_bit(V4L2_FL_RO_DEVNODE, &vdev->flags);
>  #endif
>  	int rval;
> 
> @@ -477,6 +478,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
>  	case VIDIOC_SUBDEV_S_FMT: {
>  		struct v4l2_subdev_format *format = arg;
> 
> +		if (format->which != V4L2_SUBDEV_FORMAT_TRY && ro_subdev)
> +			return -EPERM;
> +
>  		memset(format->reserved, 0, sizeof(format->reserved));
>  		memset(format->format.reserved, 0, sizeof(format->format.reserved));
>  		return v4l2_subdev_call(sd, pad, set_fmt, subdev_fh->pad, format);
> @@ -504,6 +508,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
>  		struct v4l2_subdev_crop *crop = arg;
>  		struct v4l2_subdev_selection sel;
> 
> +		if (crop->which != V4L2_SUBDEV_FORMAT_TRY && ro_subdev)
> +			return -EPERM;
> +
>  		memset(crop->reserved, 0, sizeof(crop->reserved));
>  		memset(&sel, 0, sizeof(sel));
>  		sel.which = crop->which;
> @@ -545,6 +552,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
>  	case VIDIOC_SUBDEV_S_FRAME_INTERVAL: {
>  		struct v4l2_subdev_frame_interval *fi = arg;
> 
> +		if (ro_subdev)
> +			return -EPERM;
> +
>  		memset(fi->reserved, 0, sizeof(fi->reserved));
>  		return v4l2_subdev_call(sd, video, s_frame_interval, arg);
>  	}
> @@ -568,6 +578,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
>  	case VIDIOC_SUBDEV_S_SELECTION: {
>  		struct v4l2_subdev_selection *sel = arg;
> 
> +		if (sel->which != V4L2_SUBDEV_FORMAT_TRY && ro_subdev)
> +			return -EPERM;
> +
>  		memset(sel->reserved, 0, sizeof(sel->reserved));
>  		return v4l2_subdev_call(
>  			sd, pad, set_selection, subdev_fh->pad, sel);
> @@ -604,6 +617,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
>  		return v4l2_subdev_call(sd, video, g_dv_timings, arg);
> 
>  	case VIDIOC_SUBDEV_S_DV_TIMINGS:
> +		if (ro_subdev)
> +			return -EPERM;
> +
>  		return v4l2_subdev_call(sd, video, s_dv_timings, arg);
> 
>  	case VIDIOC_SUBDEV_G_STD:
> @@ -612,6 +628,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
>  	case VIDIOC_SUBDEV_S_STD: {
>  		v4l2_std_id *std = arg;
> 
> +		if (ro_subdev)
> +			return -EPERM;
> +
>  		return v4l2_subdev_call(sd, video, s_std, *std);
>  	}
> 
> diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
> index 4602c15ff878..bdbd953a976c 100644
> --- a/include/media/v4l2-dev.h
> +++ b/include/media/v4l2-dev.h
> @@ -82,11 +82,18 @@ struct v4l2_ctrl_handler;
>   *	but the old crop API will still work as expected in order to preserve
>   *	backwards compatibility.
>   *	Never set this flag for new drivers.
> + * @V4L2_FL_RO_DEVNODE:
> + *	indicates that the video device node is registered in read-only mode.
> + *	The flag only applies to device nodes registered for sub-devices, it is
> + *	set by the core when the sub-devices device nodes are registered with
> + *	v4l2_device_register_ro_subdev_nodes() and used by the sub-device ioctl
> + *	handler to restrict access to some ioctl calls.
>   */
>  enum v4l2_video_device_flags {
>  	V4L2_FL_REGISTERED		= 0,
>  	V4L2_FL_USES_V4L2_FH		= 1,
>  	V4L2_FL_QUIRK_INVERTED_CROP	= 2,
> +	V4L2_FL_RO_DEVNODE		= 3,

I think this should be renamed to V4L2_FL_SUBDEV_RO_DEVNODE since this is subdev
specific and not for general device node usage. 'SUBDEV' should definitely be
part of the flag name.

>  };
> 
>  /* Priority helper functions */
> diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h
> index 7c912b7d2870..c01aa9df70b5 100644
> --- a/include/media/v4l2-device.h
> +++ b/include/media/v4l2-device.h
> @@ -174,14 +174,48 @@ int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
>  void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);
> 
>  /**
> - * v4l2_device_register_subdev_nodes - Registers device nodes for all subdevs
> - *	of the v4l2 device that are marked with
> - *	the %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
> + * __v4l2_device_register_ro_subdev_nodes - Registers device nodes for
> + *      all subdevs of the v4l2 device that are marked with the
> + *      %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
>   *
>   * @v4l2_dev: pointer to struct v4l2_device
> + * @read_only: subdevices read-only flag. True to register the subdevices
> + *	device nodes in read-only mode, false to allow full access to the
> + *	subdevice userspace API.
>   */
>  int __must_check
> -v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev);
> +__v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev,
> +				    bool read_only);
> +
> +/**
> + * v4l2_device_register_subdev_nodes - Registers subdevices device nodes with
> + *	unrestricted access to the subdevice userspace operations
> + *
> + * Internally calls __v4l2_device_register_subdev_nodes(). See its documentation
> + * for more details.
> + *
> + * @v4l2_dev: pointer to struct v4l2_device
> + */
> +static inline int __must_check
> +v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
> +{
> +	return __v4l2_device_register_subdev_nodes(v4l2_dev, false);
> +}
> +
> +/**
> + * v4l2_device_register_ro_subdev_nodes - Registers subdevices device nodes
> + *	in read-only mode
> + *
> + * Internally calls __v4l2_device_register_subdev_nodes(). See its documentation
> + * for more details.
> + *
> + * @v4l2_dev: pointer to struct v4l2_device
> + */
> +static inline int __must_check
> +v4l2_device_register_ro_subdev_nodes(struct v4l2_device *v4l2_dev)
> +{
> +	return __v4l2_device_register_subdev_nodes(v4l2_dev, true);
> +}
> 
>  /**
>   * v4l2_subdev_notify - Sends a notification to v4l2_device.
> --
> 2.25.1
> 

Regards,

	Hans

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Laurent Pinchart]

Hi Hans,

On Wed, Apr 01, 2020 at 01:19:00PM +0200, Hans Verkuil wrote:
> On 3/27/20 11:35 PM, Jacopo Mondi wrote:
> > Document a new kapi function to register subdev device nodes in read only
> 
> kAPI
> 
> > mode and for each affected ioctl report how access is restricted.
> > 
> > Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> > ---
> >  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
> >  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
> >  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
> >  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
> >  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
> >  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
> >  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
> >  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
> >  8 files changed, 94 insertions(+)
> > 
> > diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
> > index 41ccb3e5c707..6506a673e6a1 100644
> > --- a/Documentation/media/kapi/v4l2-subdev.rst
> > +++ b/Documentation/media/kapi/v4l2-subdev.rst
> > @@ -332,6 +332,50 @@ Private ioctls
> >  	All ioctls not in the above list are passed directly to the sub-device
> >  	driver through the core::ioctl operation.
> >  
> > +Read-only sub-device userspace API
> > +----------------------------------
> > +
> > +Bridge drivers that control their connected subdevices through direct calls to
> > +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
> > +want userspace to be able to change the same parameters through the subdevice
> > +device node and thus do not usually register any.
> > +
> > +It is sometimes useful to report to userspace the current subdevice
> > +configuration through a read-only API, that does not permit applications to
> > +change to the device parameters but allows interfacing to the subdevice device
> > +node to inspect them.
> > +
> > +For instance, to implement cameras based on computational photography, userspace
> > +needs to know the detailed camera sensor configuration (in terms of skipping,
> > +binning, cropping and scaling) for each supported output resolution. To support
> > +such use cases, bridge drivers may expose the subdevice operations to userspace
> > +through a read-only API.
> > +
> > +To create a read-only device node for all the subdevices registered with the
> > +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
> > +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> 
> Should we add something about creating a /dev/media device as well? It's basically
> required for this functionality.

I'm not opposed to that, but I don't think this should be specific to
the read-only API, as it's a shared requirement with thr R/W API. The
previous section, "V4L2 sub-device userspace API", doesn't mention media
devices.

> I think it might be a good idea to put v4l2_device_register_ro_subdev_nodes()
> under #ifdef CONFIG_MEDIA_CONTROLLER so that this config *has* to be set in order
> to be able to call this function. Or possibly have an explicit test in
> __v4l2_device_register_subdev_nodes for the presence of a media device if
> read_only is true.

VIDEO_V4L2_SUBDEV_API depends on MEDIA_CONTROLLER, but only part of that
actually depends on MEDIA_CONTROLLER in the code. I'd vote to simplify
this and make MEDIA_CONTROLLER a requirement for any userspace access
from userspace.

> > +
> > +Access to the following ioctls for userspace applications is restricted on
> > +sub-device device nodes registered with
> > +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> > +
> > +``VIDIOC_SUBDEV_S_FMT``,
> > +``VIDIOC_SUBDEV_S_CROP``,
> > +``VIDIOC_SUBDEV_S_SELECTION``:
> > +
> > +	These ioctls are only allowed on a read-only subdevice device node
> > +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
> > +	formats and selection rectangles.
> > +
> > +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
> > +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
> > +``VIDIOC_SUBDEV_S_STD``:
> > +
> > +	These ioctls are not allowed on a read-only subdevice node.
> > +
> > +In case the ioclt is not allowed, or the format to modify is set to
> > +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
> > +the errno variable is set to ``-EPERM``.
> >  
> >  I2C sub-device drivers
> >  ----------------------
> > diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
> > index 029bb2d9928a..6082f9c2f8f4 100644
> > --- a/Documentation/media/uapi/v4l/dev-subdev.rst
> > +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
> > @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
> >  Sub-device character device nodes, conventionally named
> >  ``/dev/v4l-subdev*``, use major number 81.
> >  
> > +Drivers may opt to limit the sub-device character devices to only expose
> > +operations that don't modify the device state. In such a case the sub-devices
> 
> don't -> do not
> 
> ("don't" is a bit too informal)
> 
> > +are referred to as ``read-only`` in the rest of this documentation, and the
> > +related restrictions are documented in individual ioctls.
> > +
> >  
> >  Controls
> >  ========
> > diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > index e36dd2622857..611f94e4510a 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
> >  structure as argument. If the ioctl is not supported or the timing
> >  values are not correct, the driver returns ``EINVAL`` error code.
> >  
> > +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
> > +registered in read-only mode is not allowed. An error is returned and the errno
> > +variable is set to ``-EPERM``.
> > +
> >  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
> >  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
> >  the current input or output does not support DV timings (e.g. if
> > @@ -81,6 +85,8 @@ ENODATA
> >  EBUSY
> >      The device is busy and therefore can not change the timings.
> >  
> > +EPERM
> > +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
> >  
> >  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
> >  
> > diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > index e633e42e3910..e220b38b859f 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
> >  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
> >  returned.
> >  
> > +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
> > +in read-only mode is not allowed. An error is returned and the errno variable is
> > +set to ``-EPERM``.
> >  
> >  Return Value
> >  ============
> > @@ -79,3 +82,6 @@ EINVAL
> >  
> >  ENODATA
> >      Standard video timings are not supported for this input or output.
> > +
> > +EPERM
> > +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
> > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > index 632ee053accc..62f5d9870ca7 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
> >  applications querying the same sub-device would thus not interact with
> >  each other.
> >  
> > +If the subdev device node has been registered in read-only mode calls to
> 
> mode calls -> mode, calls
> 
> > +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
> > +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > +variable is set to ``-EPERM``.
> > +
> >  Drivers must not return an error solely because the requested crop
> >  rectangle doesn't match the device capabilities. They must instead
> >  modify the rectangle to match what the hardware can provide. The
> > @@ -123,3 +128,7 @@ EINVAL
> >      references a non-existing pad, the ``which`` field references a
> >      non-existing format, or cropping is not supported on the given
> >      subdev pad.
> > +
> > +EPERM
> > +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
> > +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > index 472577bd1745..3a2f64bb00e7 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
> >  a low-pass noise filter might crop pixels at the frame boundaries,
> >  modifying its output frame size.
> >  
> > +If the subdev device node has been registered in read-only mode calls to
> 
> ditto.
> 
> > +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
> > +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > +variable is set to ``-EPERM``.
> > +
> >  Drivers must not return an error solely because the requested format
> >  doesn't match the device capabilities. They must instead modify the
> >  format to match what the hardware can provide. The modified format
> > @@ -146,6 +151,9 @@ EINVAL
> >      ``pad`` references a non-existing pad, or the ``which`` field
> >      references a non-existing format.
> >  
> > +EPERM
> > +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
> > +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> >  
> >  ============
> >  
> > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > index 4b1b4bc78bfe..34aa39096e3d 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > @@ -65,6 +65,10 @@ struct
> >  contains the current frame interval as would be returned by a
> >  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
> >  
> > +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
> > +registered in read-only mode is not allowed. An error is returned and the errno
> > +variable is set to ``-EPERM``.
> > +
> >  Drivers must not return an error solely because the requested interval
> >  doesn't match the device capabilities. They must instead modify the
> >  interval to match what the hardware can provide. The modified interval
> > @@ -118,3 +122,7 @@ EINVAL
> >      :c:type:`v4l2_subdev_frame_interval`
> >      ``pad`` references a non-existing pad, or the pad doesn't support
> >      frame intervals.
> > +
> > +EPERM
> > +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
> > +    subdevice.
> > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > index fc73d27e6d74..abd046cef612 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
> >  See :ref:`subdev` for more information on how each selection target
> >  affects the image processing pipeline inside the subdevice.
> >  
> > +If the subdev device node has been registered in read-only mode calls to
> 
> ditto
> 
> > +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
> > +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > +variable is set to ``-EPERM``.
> >  
> >  Types of selection targets
> >  --------------------------
> > @@ -123,3 +127,7 @@ EINVAL
> >      ``pad`` references a non-existing pad, the ``which`` field
> >      references a non-existing format, or the selection target is not
> >      supported on the given subdev pad.
> > +
> > +EPERM
> > +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
> > +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> > 

-- 
Regards,

Laurent Pinchart

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Hans Verkuil]

On 4/1/20 1:46 PM, Laurent Pinchart wrote:
> Hi Hans,
> 
> On Wed, Apr 01, 2020 at 01:19:00PM +0200, Hans Verkuil wrote:
>> On 3/27/20 11:35 PM, Jacopo Mondi wrote:
>>> Document a new kapi function to register subdev device nodes in read only
>>
>> kAPI
>>
>>> mode and for each affected ioctl report how access is restricted.
>>>
>>> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
>>> ---
>>>  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
>>>  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
>>>  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
>>>  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
>>>  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
>>>  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
>>>  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
>>>  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
>>>  8 files changed, 94 insertions(+)
>>>
>>> diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
>>> index 41ccb3e5c707..6506a673e6a1 100644
>>> --- a/Documentation/media/kapi/v4l2-subdev.rst
>>> +++ b/Documentation/media/kapi/v4l2-subdev.rst
>>> @@ -332,6 +332,50 @@ Private ioctls
>>>  	All ioctls not in the above list are passed directly to the sub-device
>>>  	driver through the core::ioctl operation.
>>>  
>>> +Read-only sub-device userspace API
>>> +----------------------------------
>>> +
>>> +Bridge drivers that control their connected subdevices through direct calls to
>>> +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
>>> +want userspace to be able to change the same parameters through the subdevice
>>> +device node and thus do not usually register any.
>>> +
>>> +It is sometimes useful to report to userspace the current subdevice
>>> +configuration through a read-only API, that does not permit applications to
>>> +change to the device parameters but allows interfacing to the subdevice device
>>> +node to inspect them.
>>> +
>>> +For instance, to implement cameras based on computational photography, userspace
>>> +needs to know the detailed camera sensor configuration (in terms of skipping,
>>> +binning, cropping and scaling) for each supported output resolution. To support
>>> +such use cases, bridge drivers may expose the subdevice operations to userspace
>>> +through a read-only API.
>>> +
>>> +To create a read-only device node for all the subdevices registered with the
>>> +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
>>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
>>
>> Should we add something about creating a /dev/media device as well? It's basically
>> required for this functionality.
> 
> I'm not opposed to that, but I don't think this should be specific to
> the read-only API, as it's a shared requirement with thr R/W API. The
> previous section, "V4L2 sub-device userspace API", doesn't mention media
> devices.

True.

> 
>> I think it might be a good idea to put v4l2_device_register_ro_subdev_nodes()
>> under #ifdef CONFIG_MEDIA_CONTROLLER so that this config *has* to be set in order
>> to be able to call this function. Or possibly have an explicit test in
>> __v4l2_device_register_subdev_nodes for the presence of a media device if
>> read_only is true.
> 
> VIDEO_V4L2_SUBDEV_API depends on MEDIA_CONTROLLER, but only part of that
> actually depends on MEDIA_CONTROLLER in the code. I'd vote to simplify
> this and make MEDIA_CONTROLLER a requirement for any userspace access
> from userspace.

I agree.

Regards,

	Hans

> 
>>> +
>>> +Access to the following ioctls for userspace applications is restricted on
>>> +sub-device device nodes registered with
>>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
>>> +
>>> +``VIDIOC_SUBDEV_S_FMT``,
>>> +``VIDIOC_SUBDEV_S_CROP``,
>>> +``VIDIOC_SUBDEV_S_SELECTION``:
>>> +
>>> +	These ioctls are only allowed on a read-only subdevice device node
>>> +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
>>> +	formats and selection rectangles.
>>> +
>>> +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
>>> +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
>>> +``VIDIOC_SUBDEV_S_STD``:
>>> +
>>> +	These ioctls are not allowed on a read-only subdevice node.
>>> +
>>> +In case the ioclt is not allowed, or the format to modify is set to
>>> +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
>>> +the errno variable is set to ``-EPERM``.
>>>  
>>>  I2C sub-device drivers
>>>  ----------------------
>>> diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
>>> index 029bb2d9928a..6082f9c2f8f4 100644
>>> --- a/Documentation/media/uapi/v4l/dev-subdev.rst
>>> +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
>>> @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
>>>  Sub-device character device nodes, conventionally named
>>>  ``/dev/v4l-subdev*``, use major number 81.
>>>  
>>> +Drivers may opt to limit the sub-device character devices to only expose
>>> +operations that don't modify the device state. In such a case the sub-devices
>>
>> don't -> do not
>>
>> ("don't" is a bit too informal)
>>
>>> +are referred to as ``read-only`` in the rest of this documentation, and the
>>> +related restrictions are documented in individual ioctls.
>>> +
>>>  
>>>  Controls
>>>  ========
>>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
>>> index e36dd2622857..611f94e4510a 100644
>>> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
>>> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
>>> @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
>>>  structure as argument. If the ioctl is not supported or the timing
>>>  values are not correct, the driver returns ``EINVAL`` error code.
>>>  
>>> +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
>>> +registered in read-only mode is not allowed. An error is returned and the errno
>>> +variable is set to ``-EPERM``.
>>> +
>>>  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
>>>  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
>>>  the current input or output does not support DV timings (e.g. if
>>> @@ -81,6 +85,8 @@ ENODATA
>>>  EBUSY
>>>      The device is busy and therefore can not change the timings.
>>>  
>>> +EPERM
>>> +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
>>>  
>>>  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
>>>  
>>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
>>> index e633e42e3910..e220b38b859f 100644
>>> --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
>>> +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
>>> @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
>>>  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
>>>  returned.
>>>  
>>> +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
>>> +in read-only mode is not allowed. An error is returned and the errno variable is
>>> +set to ``-EPERM``.
>>>  
>>>  Return Value
>>>  ============
>>> @@ -79,3 +82,6 @@ EINVAL
>>>  
>>>  ENODATA
>>>      Standard video timings are not supported for this input or output.
>>> +
>>> +EPERM
>>> +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
>>> index 632ee053accc..62f5d9870ca7 100644
>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
>>> @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
>>>  applications querying the same sub-device would thus not interact with
>>>  each other.
>>>  
>>> +If the subdev device node has been registered in read-only mode calls to
>>
>> mode calls -> mode, calls
>>
>>> +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
>>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
>>> +variable is set to ``-EPERM``.
>>> +
>>>  Drivers must not return an error solely because the requested crop
>>>  rectangle doesn't match the device capabilities. They must instead
>>>  modify the rectangle to match what the hardware can provide. The
>>> @@ -123,3 +128,7 @@ EINVAL
>>>      references a non-existing pad, the ``which`` field references a
>>>      non-existing format, or cropping is not supported on the given
>>>      subdev pad.
>>> +
>>> +EPERM
>>> +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
>>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
>>> index 472577bd1745..3a2f64bb00e7 100644
>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
>>> @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
>>>  a low-pass noise filter might crop pixels at the frame boundaries,
>>>  modifying its output frame size.
>>>  
>>> +If the subdev device node has been registered in read-only mode calls to
>>
>> ditto.
>>
>>> +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
>>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
>>> +variable is set to ``-EPERM``.
>>> +
>>>  Drivers must not return an error solely because the requested format
>>>  doesn't match the device capabilities. They must instead modify the
>>>  format to match what the hardware can provide. The modified format
>>> @@ -146,6 +151,9 @@ EINVAL
>>>      ``pad`` references a non-existing pad, or the ``which`` field
>>>      references a non-existing format.
>>>  
>>> +EPERM
>>> +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
>>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
>>>  
>>>  ============
>>>  
>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
>>> index 4b1b4bc78bfe..34aa39096e3d 100644
>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
>>> @@ -65,6 +65,10 @@ struct
>>>  contains the current frame interval as would be returned by a
>>>  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
>>>  
>>> +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
>>> +registered in read-only mode is not allowed. An error is returned and the errno
>>> +variable is set to ``-EPERM``.
>>> +
>>>  Drivers must not return an error solely because the requested interval
>>>  doesn't match the device capabilities. They must instead modify the
>>>  interval to match what the hardware can provide. The modified interval
>>> @@ -118,3 +122,7 @@ EINVAL
>>>      :c:type:`v4l2_subdev_frame_interval`
>>>      ``pad`` references a non-existing pad, or the pad doesn't support
>>>      frame intervals.
>>> +
>>> +EPERM
>>> +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
>>> +    subdevice.
>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
>>> index fc73d27e6d74..abd046cef612 100644
>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
>>> @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
>>>  See :ref:`subdev` for more information on how each selection target
>>>  affects the image processing pipeline inside the subdevice.
>>>  
>>> +If the subdev device node has been registered in read-only mode calls to
>>
>> ditto
>>
>>> +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
>>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
>>> +variable is set to ``-EPERM``.
>>>  
>>>  Types of selection targets
>>>  --------------------------
>>> @@ -123,3 +127,7 @@ EINVAL
>>>      ``pad`` references a non-existing pad, the ``which`` field
>>>      references a non-existing format, or the selection target is not
>>>      supported on the given subdev pad.
>>> +
>>> +EPERM
>>> +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
>>> +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
>>>
> 

Re: [v2 3/3] media: v4l2-dev: Add v4l2_device_register_ro_subdev_node()

[Jacopo Mondi]

Hi Hans,
   thanks for review
   `
On Wed, Apr 01, 2020 at 01:28:08PM +0200, Hans Verkuil wrote:
> On 3/27/20 11:35 PM, Jacopo Mondi wrote:
> > Add to the V4L2 core a function to register device nodes for video
> > subdevices in read-only mode.
> >
> > Registering a device node in read-only mode is useful to expose to
> > userspace the current sub-device configuration, without allowing
> > application to change it by using the V4L2 subdevice ioctls.
> >
> > Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> > ---
> >  drivers/media/v4l2-core/v4l2-device.c |  7 +++--
> >  drivers/media/v4l2-core/v4l2-subdev.c | 19 ++++++++++++
> >  include/media/v4l2-dev.h              |  7 +++++
> >  include/media/v4l2-device.h           | 42 ++++++++++++++++++++++++---
> >  4 files changed, 69 insertions(+), 6 deletions(-)
> >
> > diff --git a/drivers/media/v4l2-core/v4l2-device.c b/drivers/media/v4l2-core/v4l2-device.c
> > index c69941214bb2..4517a70379ce 100644
> > --- a/drivers/media/v4l2-core/v4l2-device.c
> > +++ b/drivers/media/v4l2-core/v4l2-device.c
> > @@ -186,7 +186,8 @@ static void v4l2_device_release_subdev_node(struct video_device *vdev)
> >  	kfree(vdev);
> >  }
> >
> > -int v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
> > +int __v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev,
> > +					bool read_only)
> >  {
> >  	struct video_device *vdev;
> >  	struct v4l2_subdev *sd;
> > @@ -215,6 +216,8 @@ int v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
> >  		vdev->fops = &v4l2_subdev_fops;
> >  		vdev->release = v4l2_device_release_subdev_node;
> >  		vdev->ctrl_handler = sd->ctrl_handler;
> > +		if (read_only)
> > +			set_bit(V4L2_FL_RO_DEVNODE, &vdev->flags);
>
> I noticed the discussion about set_bit vs BIT: if memory serves, then at some point
> in time setting/testing/clearing the V4L2_FL_REGISTERED had to be atomic. However,
> looking at it today this no longer appears to be needed, so it can probably all be
> replaced by normal bit operations. But that should be done in a separate patch if
> anyone is interested in making that change.
>

Ack, I agree it's an overkill and that it could be changed on top

> >  		err = __video_register_device(vdev, VFL_TYPE_SUBDEV, -1, 1,
> >  					      sd->owner);
> >  		if (err < 0) {
> > @@ -252,7 +255,7 @@ int v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
> >
> >  	return err;
> >  }
> > -EXPORT_SYMBOL_GPL(v4l2_device_register_subdev_nodes);
> > +EXPORT_SYMBOL_GPL(__v4l2_device_register_subdev_nodes);
> >
> >  void v4l2_device_unregister_subdev(struct v4l2_subdev *sd)
> >  {
> > diff --git a/drivers/media/v4l2-core/v4l2-subdev.c b/drivers/media/v4l2-core/v4l2-subdev.c
> > index a376b351135f..87fea21919fc 100644
> > --- a/drivers/media/v4l2-core/v4l2-subdev.c
> > +++ b/drivers/media/v4l2-core/v4l2-subdev.c
> > @@ -331,6 +331,7 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
> >  	struct v4l2_fh *vfh = file->private_data;
> >  #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
> >  	struct v4l2_subdev_fh *subdev_fh = to_v4l2_subdev_fh(vfh);
> > +	bool ro_subdev = test_bit(V4L2_FL_RO_DEVNODE, &vdev->flags);
> >  #endif
> >  	int rval;
> >
> > @@ -477,6 +478,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
> >  	case VIDIOC_SUBDEV_S_FMT: {
> >  		struct v4l2_subdev_format *format = arg;
> >
> > +		if (format->which != V4L2_SUBDEV_FORMAT_TRY && ro_subdev)
> > +			return -EPERM;
> > +
> >  		memset(format->reserved, 0, sizeof(format->reserved));
> >  		memset(format->format.reserved, 0, sizeof(format->format.reserved));
> >  		return v4l2_subdev_call(sd, pad, set_fmt, subdev_fh->pad, format);
> > @@ -504,6 +508,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
> >  		struct v4l2_subdev_crop *crop = arg;
> >  		struct v4l2_subdev_selection sel;
> >
> > +		if (crop->which != V4L2_SUBDEV_FORMAT_TRY && ro_subdev)
> > +			return -EPERM;
> > +
> >  		memset(crop->reserved, 0, sizeof(crop->reserved));
> >  		memset(&sel, 0, sizeof(sel));
> >  		sel.which = crop->which;
> > @@ -545,6 +552,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
> >  	case VIDIOC_SUBDEV_S_FRAME_INTERVAL: {
> >  		struct v4l2_subdev_frame_interval *fi = arg;
> >
> > +		if (ro_subdev)
> > +			return -EPERM;
> > +
> >  		memset(fi->reserved, 0, sizeof(fi->reserved));
> >  		return v4l2_subdev_call(sd, video, s_frame_interval, arg);
> >  	}
> > @@ -568,6 +578,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
> >  	case VIDIOC_SUBDEV_S_SELECTION: {
> >  		struct v4l2_subdev_selection *sel = arg;
> >
> > +		if (sel->which != V4L2_SUBDEV_FORMAT_TRY && ro_subdev)
> > +			return -EPERM;
> > +
> >  		memset(sel->reserved, 0, sizeof(sel->reserved));
> >  		return v4l2_subdev_call(
> >  			sd, pad, set_selection, subdev_fh->pad, sel);
> > @@ -604,6 +617,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
> >  		return v4l2_subdev_call(sd, video, g_dv_timings, arg);
> >
> >  	case VIDIOC_SUBDEV_S_DV_TIMINGS:
> > +		if (ro_subdev)
> > +			return -EPERM;
> > +
> >  		return v4l2_subdev_call(sd, video, s_dv_timings, arg);
> >
> >  	case VIDIOC_SUBDEV_G_STD:
> > @@ -612,6 +628,9 @@ static long subdev_do_ioctl(struct file *file, unsigned int cmd, void *arg)
> >  	case VIDIOC_SUBDEV_S_STD: {
> >  		v4l2_std_id *std = arg;
> >
> > +		if (ro_subdev)
> > +			return -EPERM;
> > +
> >  		return v4l2_subdev_call(sd, video, s_std, *std);
> >  	}
> >
> > diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
> > index 4602c15ff878..bdbd953a976c 100644
> > --- a/include/media/v4l2-dev.h
> > +++ b/include/media/v4l2-dev.h
> > @@ -82,11 +82,18 @@ struct v4l2_ctrl_handler;
> >   *	but the old crop API will still work as expected in order to preserve
> >   *	backwards compatibility.
> >   *	Never set this flag for new drivers.
> > + * @V4L2_FL_RO_DEVNODE:
> > + *	indicates that the video device node is registered in read-only mode.
> > + *	The flag only applies to device nodes registered for sub-devices, it is
> > + *	set by the core when the sub-devices device nodes are registered with
> > + *	v4l2_device_register_ro_subdev_nodes() and used by the sub-device ioctl
> > + *	handler to restrict access to some ioctl calls.
> >   */
> >  enum v4l2_video_device_flags {
> >  	V4L2_FL_REGISTERED		= 0,
> >  	V4L2_FL_USES_V4L2_FH		= 1,
> >  	V4L2_FL_QUIRK_INVERTED_CROP	= 2,
> > +	V4L2_FL_RO_DEVNODE		= 3,
>
> I think this should be renamed to V4L2_FL_SUBDEV_RO_DEVNODE since this is subdev
> specific and not for general device node usage. 'SUBDEV' should definitely be
> part of the flag name.
>

True indeed! I'll rename the flag

Thanks
   j

> >  };
> >
> >  /* Priority helper functions */
> > diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h
> > index 7c912b7d2870..c01aa9df70b5 100644
> > --- a/include/media/v4l2-device.h
> > +++ b/include/media/v4l2-device.h
> > @@ -174,14 +174,48 @@ int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
> >  void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);
> >
> >  /**
> > - * v4l2_device_register_subdev_nodes - Registers device nodes for all subdevs
> > - *	of the v4l2 device that are marked with
> > - *	the %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
> > + * __v4l2_device_register_ro_subdev_nodes - Registers device nodes for
> > + *      all subdevs of the v4l2 device that are marked with the
> > + *      %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
> >   *
> >   * @v4l2_dev: pointer to struct v4l2_device
> > + * @read_only: subdevices read-only flag. True to register the subdevices
> > + *	device nodes in read-only mode, false to allow full access to the
> > + *	subdevice userspace API.
> >   */
> >  int __must_check
> > -v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev);
> > +__v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev,
> > +				    bool read_only);
> > +
> > +/**
> > + * v4l2_device_register_subdev_nodes - Registers subdevices device nodes with
> > + *	unrestricted access to the subdevice userspace operations
> > + *
> > + * Internally calls __v4l2_device_register_subdev_nodes(). See its documentation
> > + * for more details.
> > + *
> > + * @v4l2_dev: pointer to struct v4l2_device
> > + */
> > +static inline int __must_check
> > +v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev)
> > +{
> > +	return __v4l2_device_register_subdev_nodes(v4l2_dev, false);
> > +}
> > +
> > +/**
> > + * v4l2_device_register_ro_subdev_nodes - Registers subdevices device nodes
> > + *	in read-only mode
> > + *
> > + * Internally calls __v4l2_device_register_subdev_nodes(). See its documentation
> > + * for more details.
> > + *
> > + * @v4l2_dev: pointer to struct v4l2_device
> > + */
> > +static inline int __must_check
> > +v4l2_device_register_ro_subdev_nodes(struct v4l2_device *v4l2_dev)
> > +{
> > +	return __v4l2_device_register_subdev_nodes(v4l2_dev, true);
> > +}
> >
> >  /**
> >   * v4l2_subdev_notify - Sends a notification to v4l2_device.
> > --
> > 2.25.1
> >
>
> Regards,
>
> 	Hans

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Jacopo Mondi]

Hi Hans, Laurent,

On Wed, Apr 01, 2020 at 01:54:13PM +0200, Hans Verkuil wrote:
> On 4/1/20 1:46 PM, Laurent Pinchart wrote:
> > Hi Hans,
> >
> > On Wed, Apr 01, 2020 at 01:19:00PM +0200, Hans Verkuil wrote:
> >> On 3/27/20 11:35 PM, Jacopo Mondi wrote:

[snip]

> >>> +To create a read-only device node for all the subdevices registered with the
> >>> +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
> >>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> >>
> >> Should we add something about creating a /dev/media device as well? It's basically
> >> required for this functionality.
> >
> > I'm not opposed to that, but I don't think this should be specific to
> > the read-only API, as it's a shared requirement with thr R/W API. The
> > previous section, "V4L2 sub-device userspace API", doesn't mention media
> > devices.
>
> True.
>
> >
> >> I think it might be a good idea to put v4l2_device_register_ro_subdev_nodes()
> >> under #ifdef CONFIG_MEDIA_CONTROLLER so that this config *has* to be set in order
> >> to be able to call this function. Or possibly have an explicit test in
> >> __v4l2_device_register_subdev_nodes for the presence of a media device if
> >> read_only is true.
> >
> > VIDEO_V4L2_SUBDEV_API depends on MEDIA_CONTROLLER, but only part of that
> > actually depends on MEDIA_CONTROLLER in the code. I'd vote to simplify
> > this and make MEDIA_CONTROLLER a requirement for any userspace access
> > from userspace.
>
> I agree.

I initially looked into making this new function conditional on the
presence of VIDEO_V4L2_SUBDEV_API, but then I've noticed only some part
of the code in drivers/media/v4l2-core/v4l2-subdev.c is guarded by
that flag, and at the same time v4l2_device_register_subdev_nodes() was
not. So I assumed registering read-only wihtout V4L2_SUBDEV_API should
have been allowed in the same way, even if in case V4L2_SUBDEV_API is
not enabled, ro or rw does not actually make any difference.

How would you like to proceed forward ? Guarding
v4l2_device_register_[ro_]subdev_node() with MEDIA_CONTROLLER flag ?

Thanks
  j

>
> Regards,
>
> 	Hans
>
> >
> >>> +
> >>> +Access to the following ioctls for userspace applications is restricted on
> >>> +sub-device device nodes registered with
> >>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> >>> +
> >>> +``VIDIOC_SUBDEV_S_FMT``,
> >>> +``VIDIOC_SUBDEV_S_CROP``,
> >>> +``VIDIOC_SUBDEV_S_SELECTION``:
> >>> +
> >>> +	These ioctls are only allowed on a read-only subdevice device node
> >>> +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
> >>> +	formats and selection rectangles.
> >>> +
> >>> +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
> >>> +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
> >>> +``VIDIOC_SUBDEV_S_STD``:
> >>> +
> >>> +	These ioctls are not allowed on a read-only subdevice node.
> >>> +
> >>> +In case the ioclt is not allowed, or the format to modify is set to
> >>> +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
> >>> +the errno variable is set to ``-EPERM``.
> >>>
> >>>  I2C sub-device drivers
> >>>  ----------------------
> >>> diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
> >>> index 029bb2d9928a..6082f9c2f8f4 100644
> >>> --- a/Documentation/media/uapi/v4l/dev-subdev.rst
> >>> +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
> >>> @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
> >>>  Sub-device character device nodes, conventionally named
> >>>  ``/dev/v4l-subdev*``, use major number 81.
> >>>
> >>> +Drivers may opt to limit the sub-device character devices to only expose
> >>> +operations that don't modify the device state. In such a case the sub-devices
> >>
> >> don't -> do not
> >>
> >> ("don't" is a bit too informal)
> >>
> >>> +are referred to as ``read-only`` in the rest of this documentation, and the
> >>> +related restrictions are documented in individual ioctls.
> >>> +
> >>>
> >>>  Controls
> >>>  ========
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> >>> index e36dd2622857..611f94e4510a 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> >>> @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
> >>>  structure as argument. If the ioctl is not supported or the timing
> >>>  values are not correct, the driver returns ``EINVAL`` error code.
> >>>
> >>> +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
> >>> +registered in read-only mode is not allowed. An error is returned and the errno
> >>> +variable is set to ``-EPERM``.
> >>> +
> >>>  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
> >>>  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
> >>>  the current input or output does not support DV timings (e.g. if
> >>> @@ -81,6 +85,8 @@ ENODATA
> >>>  EBUSY
> >>>      The device is busy and therefore can not change the timings.
> >>>
> >>> +EPERM
> >>> +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
> >>>
> >>>  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
> >>>
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> >>> index e633e42e3910..e220b38b859f 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> >>> @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
> >>>  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
> >>>  returned.
> >>>
> >>> +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
> >>> +in read-only mode is not allowed. An error is returned and the errno variable is
> >>> +set to ``-EPERM``.
> >>>
> >>>  Return Value
> >>>  ============
> >>> @@ -79,3 +82,6 @@ EINVAL
> >>>
> >>>  ENODATA
> >>>      Standard video timings are not supported for this input or output.
> >>> +
> >>> +EPERM
> >>> +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> >>> index 632ee053accc..62f5d9870ca7 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> >>> @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
> >>>  applications querying the same sub-device would thus not interact with
> >>>  each other.
> >>>
> >>> +If the subdev device node has been registered in read-only mode calls to
> >>
> >> mode calls -> mode, calls
> >>
> >>> +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
> >>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> >>> +variable is set to ``-EPERM``.
> >>> +
> >>>  Drivers must not return an error solely because the requested crop
> >>>  rectangle doesn't match the device capabilities. They must instead
> >>>  modify the rectangle to match what the hardware can provide. The
> >>> @@ -123,3 +128,7 @@ EINVAL
> >>>      references a non-existing pad, the ``which`` field references a
> >>>      non-existing format, or cropping is not supported on the given
> >>>      subdev pad.
> >>> +
> >>> +EPERM
> >>> +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
> >>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> >>> index 472577bd1745..3a2f64bb00e7 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> >>> @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
> >>>  a low-pass noise filter might crop pixels at the frame boundaries,
> >>>  modifying its output frame size.
> >>>
> >>> +If the subdev device node has been registered in read-only mode calls to
> >>
> >> ditto.
> >>
> >>> +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
> >>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> >>> +variable is set to ``-EPERM``.
> >>> +
> >>>  Drivers must not return an error solely because the requested format
> >>>  doesn't match the device capabilities. They must instead modify the
> >>>  format to match what the hardware can provide. The modified format
> >>> @@ -146,6 +151,9 @@ EINVAL
> >>>      ``pad`` references a non-existing pad, or the ``which`` field
> >>>      references a non-existing format.
> >>>
> >>> +EPERM
> >>> +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
> >>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> >>>
> >>>  ============
> >>>
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> >>> index 4b1b4bc78bfe..34aa39096e3d 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> >>> @@ -65,6 +65,10 @@ struct
> >>>  contains the current frame interval as would be returned by a
> >>>  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
> >>>
> >>> +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
> >>> +registered in read-only mode is not allowed. An error is returned and the errno
> >>> +variable is set to ``-EPERM``.
> >>> +
> >>>  Drivers must not return an error solely because the requested interval
> >>>  doesn't match the device capabilities. They must instead modify the
> >>>  interval to match what the hardware can provide. The modified interval
> >>> @@ -118,3 +122,7 @@ EINVAL
> >>>      :c:type:`v4l2_subdev_frame_interval`
> >>>      ``pad`` references a non-existing pad, or the pad doesn't support
> >>>      frame intervals.
> >>> +
> >>> +EPERM
> >>> +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
> >>> +    subdevice.
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> >>> index fc73d27e6d74..abd046cef612 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> >>> @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
> >>>  See :ref:`subdev` for more information on how each selection target
> >>>  affects the image processing pipeline inside the subdevice.
> >>>
> >>> +If the subdev device node has been registered in read-only mode calls to
> >>
> >> ditto
> >>
> >>> +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
> >>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> >>> +variable is set to ``-EPERM``.
> >>>
> >>>  Types of selection targets
> >>>  --------------------------
> >>> @@ -123,3 +127,7 @@ EINVAL
> >>>      ``pad`` references a non-existing pad, the ``which`` field
> >>>      references a non-existing format, or the selection target is not
> >>>      supported on the given subdev pad.
> >>> +
> >>> +EPERM
> >>> +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
> >>> +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> >>>
> >
>

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Jacopo Mondi]

Hi Sakari,
   one small question

On Sat, Mar 28, 2020 at 01:33:58AM +0200, Sakari Ailus wrote:
> Hi Jacopo,
>
> Thanks for the patchset.
>
> On Fri, Mar 27, 2020 at 11:35:21PM +0100, Jacopo Mondi wrote:
> > Document a new kapi function to register subdev device nodes in read only
> > mode and for each affected ioctl report how access is restricted.
> >
> > Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> > ---
> >  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
> >  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
> >  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
> >  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
> >  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
> >  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
> >  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
> >  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
> >  8 files changed, 94 insertions(+)
> >
> > diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
> > index 41ccb3e5c707..6506a673e6a1 100644
> > --- a/Documentation/media/kapi/v4l2-subdev.rst
> > +++ b/Documentation/media/kapi/v4l2-subdev.rst
> > @@ -332,6 +332,50 @@ Private ioctls
> >  	All ioctls not in the above list are passed directly to the sub-device
> >  	driver through the core::ioctl operation.
> >
> > +Read-only sub-device userspace API
> > +----------------------------------
> > +
> > +Bridge drivers that control their connected subdevices through direct calls to
> > +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
> > +want userspace to be able to change the same parameters through the subdevice
> > +device node and thus do not usually register any.
> > +
> > +It is sometimes useful to report to userspace the current subdevice
> > +configuration through a read-only API, that does not permit applications to
> > +change to the device parameters but allows interfacing to the subdevice device
> > +node to inspect them.
> > +
> > +For instance, to implement cameras based on computational photography, userspace
> > +needs to know the detailed camera sensor configuration (in terms of skipping,
> > +binning, cropping and scaling) for each supported output resolution. To support
> > +such use cases, bridge drivers may expose the subdevice operations to userspace
> > +through a read-only API.
> > +
> > +To create a read-only device node for all the subdevices registered with the
> > +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
> > +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> > +
> > +Access to the following ioctls for userspace applications is restricted on
> > +sub-device device nodes registered with
> > +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> > +
> > +``VIDIOC_SUBDEV_S_FMT``,
> > +``VIDIOC_SUBDEV_S_CROP``,
> > +``VIDIOC_SUBDEV_S_SELECTION``:
> > +
> > +	These ioctls are only allowed on a read-only subdevice device node
> > +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
> > +	formats and selection rectangles.
> > +
> > +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
> > +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
> > +``VIDIOC_SUBDEV_S_STD``:
> > +
> > +	These ioctls are not allowed on a read-only subdevice node.
> > +
> > +In case the ioclt is not allowed, or the format to modify is set to
>
> "IOCTL".

are you referring to the typo ioclt/ioctl or are you suggesting to
spell IOCTL uppercase ? As the rest of the documentation uses
lowercase "ioctl" ...
>
> > +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
> > +the errno variable is set to ``-EPERM``.
> >
> >  I2C sub-device drivers
> >  ----------------------
> > diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
> > index 029bb2d9928a..6082f9c2f8f4 100644
> > --- a/Documentation/media/uapi/v4l/dev-subdev.rst
> > +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
> > @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
> >  Sub-device character device nodes, conventionally named
> >  ``/dev/v4l-subdev*``, use major number 81.
> >
> > +Drivers may opt to limit the sub-device character devices to only expose
> > +operations that don't modify the device state. In such a case the sub-devices
> > +are referred to as ``read-only`` in the rest of this documentation, and the
> > +related restrictions are documented in individual ioctls.
>
> Perhaps "IOCTLs".

Same here, the rest of the documentation uses lowercase.

Thanks
  j
>
> With these, for the set,
>
> Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
>
> > +
> >
> >  Controls
> >  ========
> > diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > index e36dd2622857..611f94e4510a 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
> >  structure as argument. If the ioctl is not supported or the timing
> >  values are not correct, the driver returns ``EINVAL`` error code.
> >
> > +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
> > +registered in read-only mode is not allowed. An error is returned and the errno
> > +variable is set to ``-EPERM``.
> > +
> >  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
> >  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
> >  the current input or output does not support DV timings (e.g. if
> > @@ -81,6 +85,8 @@ ENODATA
> >  EBUSY
> >      The device is busy and therefore can not change the timings.
> >
> > +EPERM
> > +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
> >
> >  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
> >
> > diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > index e633e42e3910..e220b38b859f 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
> >  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
> >  returned.
> >
> > +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
> > +in read-only mode is not allowed. An error is returned and the errno variable is
> > +set to ``-EPERM``.
> >
> >  Return Value
> >  ============
> > @@ -79,3 +82,6 @@ EINVAL
> >
> >  ENODATA
> >      Standard video timings are not supported for this input or output.
> > +
> > +EPERM
> > +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
> > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > index 632ee053accc..62f5d9870ca7 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
> >  applications querying the same sub-device would thus not interact with
> >  each other.
> >
> > +If the subdev device node has been registered in read-only mode calls to
> > +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
> > +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > +variable is set to ``-EPERM``.
> > +
> >  Drivers must not return an error solely because the requested crop
> >  rectangle doesn't match the device capabilities. They must instead
> >  modify the rectangle to match what the hardware can provide. The
> > @@ -123,3 +128,7 @@ EINVAL
> >      references a non-existing pad, the ``which`` field references a
> >      non-existing format, or cropping is not supported on the given
> >      subdev pad.
> > +
> > +EPERM
> > +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
> > +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > index 472577bd1745..3a2f64bb00e7 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
> >  a low-pass noise filter might crop pixels at the frame boundaries,
> >  modifying its output frame size.
> >
> > +If the subdev device node has been registered in read-only mode calls to
> > +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
> > +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > +variable is set to ``-EPERM``.
> > +
> >  Drivers must not return an error solely because the requested format
> >  doesn't match the device capabilities. They must instead modify the
> >  format to match what the hardware can provide. The modified format
> > @@ -146,6 +151,9 @@ EINVAL
> >      ``pad`` references a non-existing pad, or the ``which`` field
> >      references a non-existing format.
> >
> > +EPERM
> > +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
> > +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> >
> >  ============
> >
> > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > index 4b1b4bc78bfe..34aa39096e3d 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > @@ -65,6 +65,10 @@ struct
> >  contains the current frame interval as would be returned by a
> >  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
> >
> > +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
> > +registered in read-only mode is not allowed. An error is returned and the errno
> > +variable is set to ``-EPERM``.
> > +
> >  Drivers must not return an error solely because the requested interval
> >  doesn't match the device capabilities. They must instead modify the
> >  interval to match what the hardware can provide. The modified interval
> > @@ -118,3 +122,7 @@ EINVAL
> >      :c:type:`v4l2_subdev_frame_interval`
> >      ``pad`` references a non-existing pad, or the pad doesn't support
> >      frame intervals.
> > +
> > +EPERM
> > +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
> > +    subdevice.
> > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > index fc73d27e6d74..abd046cef612 100644
> > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
> >  See :ref:`subdev` for more information on how each selection target
> >  affects the image processing pipeline inside the subdevice.
> >
> > +If the subdev device node has been registered in read-only mode calls to
> > +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
> > +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > +variable is set to ``-EPERM``.
> >
> >  Types of selection targets
> >  --------------------------
> > @@ -123,3 +127,7 @@ EINVAL
> >      ``pad`` references a non-existing pad, the ``which`` field
> >      references a non-existing format, or the selection target is not
> >      supported on the given subdev pad.
> > +
> > +EPERM
> > +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
> > +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
>
> --
> Regards,
>
> Sakari Ailus

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Laurent Pinchart]

Hi Hans,

On Wed, Apr 01, 2020 at 01:54:13PM +0200, Hans Verkuil wrote:
> On 4/1/20 1:46 PM, Laurent Pinchart wrote:
> > On Wed, Apr 01, 2020 at 01:19:00PM +0200, Hans Verkuil wrote:
> >> On 3/27/20 11:35 PM, Jacopo Mondi wrote:
> >>> Document a new kapi function to register subdev device nodes in read only
> >>
> >> kAPI
> >>
> >>> mode and for each affected ioctl report how access is restricted.
> >>>
> >>> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> >>> ---
> >>>  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
> >>>  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
> >>>  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
> >>>  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
> >>>  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
> >>>  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
> >>>  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
> >>>  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
> >>>  8 files changed, 94 insertions(+)
> >>>
> >>> diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
> >>> index 41ccb3e5c707..6506a673e6a1 100644
> >>> --- a/Documentation/media/kapi/v4l2-subdev.rst
> >>> +++ b/Documentation/media/kapi/v4l2-subdev.rst
> >>> @@ -332,6 +332,50 @@ Private ioctls
> >>>  	All ioctls not in the above list are passed directly to the sub-device
> >>>  	driver through the core::ioctl operation.
> >>>  
> >>> +Read-only sub-device userspace API
> >>> +----------------------------------
> >>> +
> >>> +Bridge drivers that control their connected subdevices through direct calls to
> >>> +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
> >>> +want userspace to be able to change the same parameters through the subdevice
> >>> +device node and thus do not usually register any.
> >>> +
> >>> +It is sometimes useful to report to userspace the current subdevice
> >>> +configuration through a read-only API, that does not permit applications to
> >>> +change to the device parameters but allows interfacing to the subdevice device
> >>> +node to inspect them.
> >>> +
> >>> +For instance, to implement cameras based on computational photography, userspace
> >>> +needs to know the detailed camera sensor configuration (in terms of skipping,
> >>> +binning, cropping and scaling) for each supported output resolution. To support
> >>> +such use cases, bridge drivers may expose the subdevice operations to userspace
> >>> +through a read-only API.
> >>> +
> >>> +To create a read-only device node for all the subdevices registered with the
> >>> +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
> >>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> >>
> >> Should we add something about creating a /dev/media device as well? It's basically
> >> required for this functionality.
> > 
> > I'm not opposed to that, but I don't think this should be specific to
> > the read-only API, as it's a shared requirement with thr R/W API. The
> > previous section, "V4L2 sub-device userspace API", doesn't mention media
> > devices.
> 
> True.
> 
> >> I think it might be a good idea to put v4l2_device_register_ro_subdev_nodes()
> >> under #ifdef CONFIG_MEDIA_CONTROLLER so that this config *has* to be set in order
> >> to be able to call this function. Or possibly have an explicit test in
> >> __v4l2_device_register_subdev_nodes for the presence of a media device if
> >> read_only is true.
> > 
> > VIDEO_V4L2_SUBDEV_API depends on MEDIA_CONTROLLER, but only part of that
> > actually depends on MEDIA_CONTROLLER in the code. I'd vote to simplify
> > this and make MEDIA_CONTROLLER a requirement for any userspace access
> > from userspace.
> 
> I agree.

Does that mean we should rework it as a prerequisite for this series, as
part of the series, or separately ?

> >>> +
> >>> +Access to the following ioctls for userspace applications is restricted on
> >>> +sub-device device nodes registered with
> >>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> >>> +
> >>> +``VIDIOC_SUBDEV_S_FMT``,
> >>> +``VIDIOC_SUBDEV_S_CROP``,
> >>> +``VIDIOC_SUBDEV_S_SELECTION``:
> >>> +
> >>> +	These ioctls are only allowed on a read-only subdevice device node
> >>> +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
> >>> +	formats and selection rectangles.
> >>> +
> >>> +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
> >>> +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
> >>> +``VIDIOC_SUBDEV_S_STD``:
> >>> +
> >>> +	These ioctls are not allowed on a read-only subdevice node.
> >>> +
> >>> +In case the ioclt is not allowed, or the format to modify is set to
> >>> +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
> >>> +the errno variable is set to ``-EPERM``.
> >>>  
> >>>  I2C sub-device drivers
> >>>  ----------------------
> >>> diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
> >>> index 029bb2d9928a..6082f9c2f8f4 100644
> >>> --- a/Documentation/media/uapi/v4l/dev-subdev.rst
> >>> +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
> >>> @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
> >>>  Sub-device character device nodes, conventionally named
> >>>  ``/dev/v4l-subdev*``, use major number 81.
> >>>  
> >>> +Drivers may opt to limit the sub-device character devices to only expose
> >>> +operations that don't modify the device state. In such a case the sub-devices
> >>
> >> don't -> do not
> >>
> >> ("don't" is a bit too informal)
> >>
> >>> +are referred to as ``read-only`` in the rest of this documentation, and the
> >>> +related restrictions are documented in individual ioctls.
> >>> +
> >>>  
> >>>  Controls
> >>>  ========
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> >>> index e36dd2622857..611f94e4510a 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> >>> @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
> >>>  structure as argument. If the ioctl is not supported or the timing
> >>>  values are not correct, the driver returns ``EINVAL`` error code.
> >>>  
> >>> +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
> >>> +registered in read-only mode is not allowed. An error is returned and the errno
> >>> +variable is set to ``-EPERM``.
> >>> +
> >>>  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
> >>>  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
> >>>  the current input or output does not support DV timings (e.g. if
> >>> @@ -81,6 +85,8 @@ ENODATA
> >>>  EBUSY
> >>>      The device is busy and therefore can not change the timings.
> >>>  
> >>> +EPERM
> >>> +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
> >>>  
> >>>  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
> >>>  
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> >>> index e633e42e3910..e220b38b859f 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> >>> @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
> >>>  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
> >>>  returned.
> >>>  
> >>> +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
> >>> +in read-only mode is not allowed. An error is returned and the errno variable is
> >>> +set to ``-EPERM``.
> >>>  
> >>>  Return Value
> >>>  ============
> >>> @@ -79,3 +82,6 @@ EINVAL
> >>>  
> >>>  ENODATA
> >>>      Standard video timings are not supported for this input or output.
> >>> +
> >>> +EPERM
> >>> +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> >>> index 632ee053accc..62f5d9870ca7 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> >>> @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
> >>>  applications querying the same sub-device would thus not interact with
> >>>  each other.
> >>>  
> >>> +If the subdev device node has been registered in read-only mode calls to
> >>
> >> mode calls -> mode, calls
> >>
> >>> +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
> >>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> >>> +variable is set to ``-EPERM``.
> >>> +
> >>>  Drivers must not return an error solely because the requested crop
> >>>  rectangle doesn't match the device capabilities. They must instead
> >>>  modify the rectangle to match what the hardware can provide. The
> >>> @@ -123,3 +128,7 @@ EINVAL
> >>>      references a non-existing pad, the ``which`` field references a
> >>>      non-existing format, or cropping is not supported on the given
> >>>      subdev pad.
> >>> +
> >>> +EPERM
> >>> +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
> >>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> >>> index 472577bd1745..3a2f64bb00e7 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> >>> @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
> >>>  a low-pass noise filter might crop pixels at the frame boundaries,
> >>>  modifying its output frame size.
> >>>  
> >>> +If the subdev device node has been registered in read-only mode calls to
> >>
> >> ditto.
> >>
> >>> +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
> >>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> >>> +variable is set to ``-EPERM``.
> >>> +
> >>>  Drivers must not return an error solely because the requested format
> >>>  doesn't match the device capabilities. They must instead modify the
> >>>  format to match what the hardware can provide. The modified format
> >>> @@ -146,6 +151,9 @@ EINVAL
> >>>      ``pad`` references a non-existing pad, or the ``which`` field
> >>>      references a non-existing format.
> >>>  
> >>> +EPERM
> >>> +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
> >>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> >>>  
> >>>  ============
> >>>  
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> >>> index 4b1b4bc78bfe..34aa39096e3d 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> >>> @@ -65,6 +65,10 @@ struct
> >>>  contains the current frame interval as would be returned by a
> >>>  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
> >>>  
> >>> +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
> >>> +registered in read-only mode is not allowed. An error is returned and the errno
> >>> +variable is set to ``-EPERM``.
> >>> +
> >>>  Drivers must not return an error solely because the requested interval
> >>>  doesn't match the device capabilities. They must instead modify the
> >>>  interval to match what the hardware can provide. The modified interval
> >>> @@ -118,3 +122,7 @@ EINVAL
> >>>      :c:type:`v4l2_subdev_frame_interval`
> >>>      ``pad`` references a non-existing pad, or the pad doesn't support
> >>>      frame intervals.
> >>> +
> >>> +EPERM
> >>> +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
> >>> +    subdevice.
> >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> >>> index fc73d27e6d74..abd046cef612 100644
> >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> >>> @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
> >>>  See :ref:`subdev` for more information on how each selection target
> >>>  affects the image processing pipeline inside the subdevice.
> >>>  
> >>> +If the subdev device node has been registered in read-only mode calls to
> >>
> >> ditto
> >>
> >>> +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
> >>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> >>> +variable is set to ``-EPERM``.
> >>>  
> >>>  Types of selection targets
> >>>  --------------------------
> >>> @@ -123,3 +127,7 @@ EINVAL
> >>>      ``pad`` references a non-existing pad, the ``which`` field
> >>>      references a non-existing format, or the selection target is not
> >>>      supported on the given subdev pad.
> >>> +
> >>> +EPERM
> >>> +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
> >>> +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.

-- 
Regards,

Laurent Pinchart

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Sakari Ailus]

Hi Jacopo,

On Thu, Apr 02, 2020 at 12:10:21AM +0200, Jacopo Mondi wrote:
> Hi Sakari,
>    one small question
> 
> On Sat, Mar 28, 2020 at 01:33:58AM +0200, Sakari Ailus wrote:
> > Hi Jacopo,
> >
> > Thanks for the patchset.
> >
> > On Fri, Mar 27, 2020 at 11:35:21PM +0100, Jacopo Mondi wrote:
> > > Document a new kapi function to register subdev device nodes in read only
> > > mode and for each affected ioctl report how access is restricted.
> > >
> > > Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> > > ---
> > >  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
> > >  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
> > >  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
> > >  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
> > >  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
> > >  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
> > >  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
> > >  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
> > >  8 files changed, 94 insertions(+)
> > >
> > > diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
> > > index 41ccb3e5c707..6506a673e6a1 100644
> > > --- a/Documentation/media/kapi/v4l2-subdev.rst
> > > +++ b/Documentation/media/kapi/v4l2-subdev.rst
> > > @@ -332,6 +332,50 @@ Private ioctls
> > >  	All ioctls not in the above list are passed directly to the sub-device
> > >  	driver through the core::ioctl operation.
> > >
> > > +Read-only sub-device userspace API
> > > +----------------------------------
> > > +
> > > +Bridge drivers that control their connected subdevices through direct calls to
> > > +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
> > > +want userspace to be able to change the same parameters through the subdevice
> > > +device node and thus do not usually register any.
> > > +
> > > +It is sometimes useful to report to userspace the current subdevice
> > > +configuration through a read-only API, that does not permit applications to
> > > +change to the device parameters but allows interfacing to the subdevice device
> > > +node to inspect them.
> > > +
> > > +For instance, to implement cameras based on computational photography, userspace
> > > +needs to know the detailed camera sensor configuration (in terms of skipping,
> > > +binning, cropping and scaling) for each supported output resolution. To support
> > > +such use cases, bridge drivers may expose the subdevice operations to userspace
> > > +through a read-only API.
> > > +
> > > +To create a read-only device node for all the subdevices registered with the
> > > +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
> > > +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> > > +
> > > +Access to the following ioctls for userspace applications is restricted on
> > > +sub-device device nodes registered with
> > > +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> > > +
> > > +``VIDIOC_SUBDEV_S_FMT``,
> > > +``VIDIOC_SUBDEV_S_CROP``,
> > > +``VIDIOC_SUBDEV_S_SELECTION``:
> > > +
> > > +	These ioctls are only allowed on a read-only subdevice device node
> > > +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
> > > +	formats and selection rectangles.
> > > +
> > > +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
> > > +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
> > > +``VIDIOC_SUBDEV_S_STD``:
> > > +
> > > +	These ioctls are not allowed on a read-only subdevice node.
> > > +
> > > +In case the ioclt is not allowed, or the format to modify is set to
> >
> > "IOCTL".
> 
> are you referring to the typo ioclt/ioctl or are you suggesting to
> spell IOCTL uppercase ? As the rest of the documentation uses
> lowercase "ioctl" ...

Ok; then just use lower case.

> >
> > > +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
> > > +the errno variable is set to ``-EPERM``.
> > >
> > >  I2C sub-device drivers
> > >  ----------------------
> > > diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
> > > index 029bb2d9928a..6082f9c2f8f4 100644
> > > --- a/Documentation/media/uapi/v4l/dev-subdev.rst
> > > +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
> > > @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
> > >  Sub-device character device nodes, conventionally named
> > >  ``/dev/v4l-subdev*``, use major number 81.
> > >
> > > +Drivers may opt to limit the sub-device character devices to only expose
> > > +operations that don't modify the device state. In such a case the sub-devices
> > > +are referred to as ``read-only`` in the rest of this documentation, and the
> > > +related restrictions are documented in individual ioctls.
> >
> > Perhaps "IOCTLs".
> 
> Same here, the rest of the documentation uses lowercase.
> 
> Thanks
>   j
> >
> > With these, for the set,
> >
> > Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> >
> > > +
> > >
> > >  Controls
> > >  ========
> > > diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > > index e36dd2622857..611f94e4510a 100644
> > > --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > > +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > > @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
> > >  structure as argument. If the ioctl is not supported or the timing
> > >  values are not correct, the driver returns ``EINVAL`` error code.
> > >
> > > +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
> > > +registered in read-only mode is not allowed. An error is returned and the errno
> > > +variable is set to ``-EPERM``.
> > > +
> > >  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
> > >  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
> > >  the current input or output does not support DV timings (e.g. if
> > > @@ -81,6 +85,8 @@ ENODATA
> > >  EBUSY
> > >      The device is busy and therefore can not change the timings.
> > >
> > > +EPERM
> > > +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
> > >
> > >  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
> > >
> > > diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > > index e633e42e3910..e220b38b859f 100644
> > > --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > > +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > > @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
> > >  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
> > >  returned.
> > >
> > > +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
> > > +in read-only mode is not allowed. An error is returned and the errno variable is
> > > +set to ``-EPERM``.
> > >
> > >  Return Value
> > >  ============
> > > @@ -79,3 +82,6 @@ EINVAL
> > >
> > >  ENODATA
> > >      Standard video timings are not supported for this input or output.
> > > +
> > > +EPERM
> > > +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
> > > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > > index 632ee053accc..62f5d9870ca7 100644
> > > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > > @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
> > >  applications querying the same sub-device would thus not interact with
> > >  each other.
> > >
> > > +If the subdev device node has been registered in read-only mode calls to
> > > +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
> > > +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > > +variable is set to ``-EPERM``.
> > > +
> > >  Drivers must not return an error solely because the requested crop
> > >  rectangle doesn't match the device capabilities. They must instead
> > >  modify the rectangle to match what the hardware can provide. The
> > > @@ -123,3 +128,7 @@ EINVAL
> > >      references a non-existing pad, the ``which`` field references a
> > >      non-existing format, or cropping is not supported on the given
> > >      subdev pad.
> > > +
> > > +EPERM
> > > +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
> > > +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> > > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > > index 472577bd1745..3a2f64bb00e7 100644
> > > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > > @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
> > >  a low-pass noise filter might crop pixels at the frame boundaries,
> > >  modifying its output frame size.
> > >
> > > +If the subdev device node has been registered in read-only mode calls to
> > > +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
> > > +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > > +variable is set to ``-EPERM``.
> > > +
> > >  Drivers must not return an error solely because the requested format
> > >  doesn't match the device capabilities. They must instead modify the
> > >  format to match what the hardware can provide. The modified format
> > > @@ -146,6 +151,9 @@ EINVAL
> > >      ``pad`` references a non-existing pad, or the ``which`` field
> > >      references a non-existing format.
> > >
> > > +EPERM
> > > +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
> > > +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> > >
> > >  ============
> > >
> > > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > > index 4b1b4bc78bfe..34aa39096e3d 100644
> > > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > > @@ -65,6 +65,10 @@ struct
> > >  contains the current frame interval as would be returned by a
> > >  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
> > >
> > > +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
> > > +registered in read-only mode is not allowed. An error is returned and the errno
> > > +variable is set to ``-EPERM``.
> > > +
> > >  Drivers must not return an error solely because the requested interval
> > >  doesn't match the device capabilities. They must instead modify the
> > >  interval to match what the hardware can provide. The modified interval
> > > @@ -118,3 +122,7 @@ EINVAL
> > >      :c:type:`v4l2_subdev_frame_interval`
> > >      ``pad`` references a non-existing pad, or the pad doesn't support
> > >      frame intervals.
> > > +
> > > +EPERM
> > > +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
> > > +    subdevice.
> > > diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > > index fc73d27e6d74..abd046cef612 100644
> > > --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > > +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > > @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
> > >  See :ref:`subdev` for more information on how each selection target
> > >  affects the image processing pipeline inside the subdevice.
> > >
> > > +If the subdev device node has been registered in read-only mode calls to
> > > +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
> > > +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > > +variable is set to ``-EPERM``.
> > >
> > >  Types of selection targets
> > >  --------------------------
> > > @@ -123,3 +127,7 @@ EINVAL
> > >      ``pad`` references a non-existing pad, the ``which`` field
> > >      references a non-existing format, or the selection target is not
> > >      supported on the given subdev pad.
> > > +
> > > +EPERM
> > > +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
> > > +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> >
> > --
> > Regards,
> >
> > Sakari Ailus

-- 
Sakari Ailus

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Jacopo Mondi]

Hi

On Sat, Apr 04, 2020 at 04:35:45AM +0300, Laurent Pinchart wrote:
> Hi Hans,
>
> On Wed, Apr 01, 2020 at 01:54:13PM +0200, Hans Verkuil wrote:
> > On 4/1/20 1:46 PM, Laurent Pinchart wrote:
> > > On Wed, Apr 01, 2020 at 01:19:00PM +0200, Hans Verkuil wrote:
> > >> On 3/27/20 11:35 PM, Jacopo Mondi wrote:
> > >>> Document a new kapi function to register subdev device nodes in read only
> > >>
> > >> kAPI
> > >>
> > >>> mode and for each affected ioctl report how access is restricted.
> > >>>
> > >>> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> > >>> ---
> > >>>  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
> > >>>  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
> > >>>  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
> > >>>  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
> > >>>  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
> > >>>  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
> > >>>  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
> > >>>  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
> > >>>  8 files changed, 94 insertions(+)
> > >>>
> > >>> diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
> > >>> index 41ccb3e5c707..6506a673e6a1 100644
> > >>> --- a/Documentation/media/kapi/v4l2-subdev.rst
> > >>> +++ b/Documentation/media/kapi/v4l2-subdev.rst
> > >>> @@ -332,6 +332,50 @@ Private ioctls
> > >>>  	All ioctls not in the above list are passed directly to the sub-device
> > >>>  	driver through the core::ioctl operation.
> > >>>
> > >>> +Read-only sub-device userspace API
> > >>> +----------------------------------
> > >>> +
> > >>> +Bridge drivers that control their connected subdevices through direct calls to
> > >>> +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
> > >>> +want userspace to be able to change the same parameters through the subdevice
> > >>> +device node and thus do not usually register any.
> > >>> +
> > >>> +It is sometimes useful to report to userspace the current subdevice
> > >>> +configuration through a read-only API, that does not permit applications to
> > >>> +change to the device parameters but allows interfacing to the subdevice device
> > >>> +node to inspect them.
> > >>> +
> > >>> +For instance, to implement cameras based on computational photography, userspace
> > >>> +needs to know the detailed camera sensor configuration (in terms of skipping,
> > >>> +binning, cropping and scaling) for each supported output resolution. To support
> > >>> +such use cases, bridge drivers may expose the subdevice operations to userspace
> > >>> +through a read-only API.
> > >>> +
> > >>> +To create a read-only device node for all the subdevices registered with the
> > >>> +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
> > >>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> > >>
> > >> Should we add something about creating a /dev/media device as well? It's basically
> > >> required for this functionality.
> > >
> > > I'm not opposed to that, but I don't think this should be specific to
> > > the read-only API, as it's a shared requirement with thr R/W API. The
> > > previous section, "V4L2 sub-device userspace API", doesn't mention media
> > > devices.
> >
> > True.
> >
> > >> I think it might be a good idea to put v4l2_device_register_ro_subdev_nodes()
> > >> under #ifdef CONFIG_MEDIA_CONTROLLER so that this config *has* to be set in order
> > >> to be able to call this function. Or possibly have an explicit test in
> > >> __v4l2_device_register_subdev_nodes for the presence of a media device if
> > >> read_only is true.
> > >
> > > VIDEO_V4L2_SUBDEV_API depends on MEDIA_CONTROLLER, but only part of that
> > > actually depends on MEDIA_CONTROLLER in the code. I'd vote to simplify
> > > this and make MEDIA_CONTROLLER a requirement for any userspace access
> > > from userspace.
> >
> > I agree.
>
> Does that mean we should rework it as a prerequisite for this series, as
> part of the series, or separately ?

I would, for the moment, make v4l2_device_register_ro_subdev_nodes and
v4l2_device_register_subdev_nodes dependendent on
VIDEO_V4L2_SUBDEV_API, so that they're only available to drivers
actually wanting userspace access. Then when moving everything to
MEDIA_CONTROLLER, they can be moved to.

However, this is not clear to me
https://elixir.bootlin.com/linux/latest/source/drivers/media/v4l2-core/v4l2-subdev.c#L338

What is the reason to have some of the subdev ioctls protected by
VIDEO_V4L2_SUBDEV_API, while the v4l2-control related ones are not ?

Thanks
   j

>
> > >>> +
> > >>> +Access to the following ioctls for userspace applications is restricted on
> > >>> +sub-device device nodes registered with
> > >>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> > >>> +
> > >>> +``VIDIOC_SUBDEV_S_FMT``,
> > >>> +``VIDIOC_SUBDEV_S_CROP``,
> > >>> +``VIDIOC_SUBDEV_S_SELECTION``:
> > >>> +
> > >>> +	These ioctls are only allowed on a read-only subdevice device node
> > >>> +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
> > >>> +	formats and selection rectangles.
> > >>> +
> > >>> +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
> > >>> +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
> > >>> +``VIDIOC_SUBDEV_S_STD``:
> > >>> +
> > >>> +	These ioctls are not allowed on a read-only subdevice node.
> > >>> +
> > >>> +In case the ioclt is not allowed, or the format to modify is set to
> > >>> +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
> > >>> +the errno variable is set to ``-EPERM``.
> > >>>
> > >>>  I2C sub-device drivers
> > >>>  ----------------------
> > >>> diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
> > >>> index 029bb2d9928a..6082f9c2f8f4 100644
> > >>> --- a/Documentation/media/uapi/v4l/dev-subdev.rst
> > >>> +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
> > >>> @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
> > >>>  Sub-device character device nodes, conventionally named
> > >>>  ``/dev/v4l-subdev*``, use major number 81.
> > >>>
> > >>> +Drivers may opt to limit the sub-device character devices to only expose
> > >>> +operations that don't modify the device state. In such a case the sub-devices
> > >>
> > >> don't -> do not
> > >>
> > >> ("don't" is a bit too informal)
> > >>
> > >>> +are referred to as ``read-only`` in the rest of this documentation, and the
> > >>> +related restrictions are documented in individual ioctls.
> > >>> +
> > >>>
> > >>>  Controls
> > >>>  ========
> > >>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > >>> index e36dd2622857..611f94e4510a 100644
> > >>> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > >>> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > >>> @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
> > >>>  structure as argument. If the ioctl is not supported or the timing
> > >>>  values are not correct, the driver returns ``EINVAL`` error code.
> > >>>
> > >>> +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
> > >>> +registered in read-only mode is not allowed. An error is returned and the errno
> > >>> +variable is set to ``-EPERM``.
> > >>> +
> > >>>  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
> > >>>  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
> > >>>  the current input or output does not support DV timings (e.g. if
> > >>> @@ -81,6 +85,8 @@ ENODATA
> > >>>  EBUSY
> > >>>      The device is busy and therefore can not change the timings.
> > >>>
> > >>> +EPERM
> > >>> +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
> > >>>
> > >>>  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
> > >>>
> > >>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > >>> index e633e42e3910..e220b38b859f 100644
> > >>> --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > >>> +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > >>> @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
> > >>>  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
> > >>>  returned.
> > >>>
> > >>> +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
> > >>> +in read-only mode is not allowed. An error is returned and the errno variable is
> > >>> +set to ``-EPERM``.
> > >>>
> > >>>  Return Value
> > >>>  ============
> > >>> @@ -79,3 +82,6 @@ EINVAL
> > >>>
> > >>>  ENODATA
> > >>>      Standard video timings are not supported for this input or output.
> > >>> +
> > >>> +EPERM
> > >>> +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
> > >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > >>> index 632ee053accc..62f5d9870ca7 100644
> > >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > >>> @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
> > >>>  applications querying the same sub-device would thus not interact with
> > >>>  each other.
> > >>>
> > >>> +If the subdev device node has been registered in read-only mode calls to
> > >>
> > >> mode calls -> mode, calls
> > >>
> > >>> +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
> > >>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > >>> +variable is set to ``-EPERM``.
> > >>> +
> > >>>  Drivers must not return an error solely because the requested crop
> > >>>  rectangle doesn't match the device capabilities. They must instead
> > >>>  modify the rectangle to match what the hardware can provide. The
> > >>> @@ -123,3 +128,7 @@ EINVAL
> > >>>      references a non-existing pad, the ``which`` field references a
> > >>>      non-existing format, or cropping is not supported on the given
> > >>>      subdev pad.
> > >>> +
> > >>> +EPERM
> > >>> +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
> > >>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> > >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > >>> index 472577bd1745..3a2f64bb00e7 100644
> > >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > >>> @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
> > >>>  a low-pass noise filter might crop pixels at the frame boundaries,
> > >>>  modifying its output frame size.
> > >>>
> > >>> +If the subdev device node has been registered in read-only mode calls to
> > >>
> > >> ditto.
> > >>
> > >>> +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
> > >>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > >>> +variable is set to ``-EPERM``.
> > >>> +
> > >>>  Drivers must not return an error solely because the requested format
> > >>>  doesn't match the device capabilities. They must instead modify the
> > >>>  format to match what the hardware can provide. The modified format
> > >>> @@ -146,6 +151,9 @@ EINVAL
> > >>>      ``pad`` references a non-existing pad, or the ``which`` field
> > >>>      references a non-existing format.
> > >>>
> > >>> +EPERM
> > >>> +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
> > >>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> > >>>
> > >>>  ============
> > >>>
> > >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > >>> index 4b1b4bc78bfe..34aa39096e3d 100644
> > >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > >>> @@ -65,6 +65,10 @@ struct
> > >>>  contains the current frame interval as would be returned by a
> > >>>  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
> > >>>
> > >>> +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
> > >>> +registered in read-only mode is not allowed. An error is returned and the errno
> > >>> +variable is set to ``-EPERM``.
> > >>> +
> > >>>  Drivers must not return an error solely because the requested interval
> > >>>  doesn't match the device capabilities. They must instead modify the
> > >>>  interval to match what the hardware can provide. The modified interval
> > >>> @@ -118,3 +122,7 @@ EINVAL
> > >>>      :c:type:`v4l2_subdev_frame_interval`
> > >>>      ``pad`` references a non-existing pad, or the pad doesn't support
> > >>>      frame intervals.
> > >>> +
> > >>> +EPERM
> > >>> +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
> > >>> +    subdevice.
> > >>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > >>> index fc73d27e6d74..abd046cef612 100644
> > >>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > >>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > >>> @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
> > >>>  See :ref:`subdev` for more information on how each selection target
> > >>>  affects the image processing pipeline inside the subdevice.
> > >>>
> > >>> +If the subdev device node has been registered in read-only mode calls to
> > >>
> > >> ditto
> > >>
> > >>> +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
> > >>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > >>> +variable is set to ``-EPERM``.
> > >>>
> > >>>  Types of selection targets
> > >>>  --------------------------
> > >>> @@ -123,3 +127,7 @@ EINVAL
> > >>>      ``pad`` references a non-existing pad, the ``which`` field
> > >>>      references a non-existing format, or the selection target is not
> > >>>      supported on the given subdev pad.
> > >>> +
> > >>> +EPERM
> > >>> +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
> > >>> +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
>
> --
> Regards,
>
> Laurent Pinchart

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Laurent Pinchart]

Hi Jacopo,

On Mon, Apr 06, 2020 at 01:07:32PM +0200, Jacopo Mondi wrote:
> On Sat, Apr 04, 2020 at 04:35:45AM +0300, Laurent Pinchart wrote:
> > On Wed, Apr 01, 2020 at 01:54:13PM +0200, Hans Verkuil wrote:
> >> On 4/1/20 1:46 PM, Laurent Pinchart wrote:
> >>> On Wed, Apr 01, 2020 at 01:19:00PM +0200, Hans Verkuil wrote:
> >>>> On 3/27/20 11:35 PM, Jacopo Mondi wrote:
> >>>>> Document a new kapi function to register subdev device nodes in read only
> >>>>
> >>>> kAPI
> >>>>
> >>>>> mode and for each affected ioctl report how access is restricted.
> >>>>>
> >>>>> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> >>>>> ---
> >>>>>  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
> >>>>>  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
> >>>>>  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
> >>>>>  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
> >>>>>  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
> >>>>>  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
> >>>>>  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
> >>>>>  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
> >>>>>  8 files changed, 94 insertions(+)
> >>>>>
> >>>>> diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
> >>>>> index 41ccb3e5c707..6506a673e6a1 100644
> >>>>> --- a/Documentation/media/kapi/v4l2-subdev.rst
> >>>>> +++ b/Documentation/media/kapi/v4l2-subdev.rst
> >>>>> @@ -332,6 +332,50 @@ Private ioctls
> >>>>>  	All ioctls not in the above list are passed directly to the sub-device
> >>>>>  	driver through the core::ioctl operation.
> >>>>>
> >>>>> +Read-only sub-device userspace API
> >>>>> +----------------------------------
> >>>>> +
> >>>>> +Bridge drivers that control their connected subdevices through direct calls to
> >>>>> +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
> >>>>> +want userspace to be able to change the same parameters through the subdevice
> >>>>> +device node and thus do not usually register any.
> >>>>> +
> >>>>> +It is sometimes useful to report to userspace the current subdevice
> >>>>> +configuration through a read-only API, that does not permit applications to
> >>>>> +change to the device parameters but allows interfacing to the subdevice device
> >>>>> +node to inspect them.
> >>>>> +
> >>>>> +For instance, to implement cameras based on computational photography, userspace
> >>>>> +needs to know the detailed camera sensor configuration (in terms of skipping,
> >>>>> +binning, cropping and scaling) for each supported output resolution. To support
> >>>>> +such use cases, bridge drivers may expose the subdevice operations to userspace
> >>>>> +through a read-only API.
> >>>>> +
> >>>>> +To create a read-only device node for all the subdevices registered with the
> >>>>> +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
> >>>>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> >>>>
> >>>> Should we add something about creating a /dev/media device as well? It's basically
> >>>> required for this functionality.
> >>>
> >>> I'm not opposed to that, but I don't think this should be specific to
> >>> the read-only API, as it's a shared requirement with thr R/W API. The
> >>> previous section, "V4L2 sub-device userspace API", doesn't mention media
> >>> devices.
> >>
> >> True.
> >>
> >>>> I think it might be a good idea to put v4l2_device_register_ro_subdev_nodes()
> >>>> under #ifdef CONFIG_MEDIA_CONTROLLER so that this config *has* to be set in order
> >>>> to be able to call this function. Or possibly have an explicit test in
> >>>> __v4l2_device_register_subdev_nodes for the presence of a media device if
> >>>> read_only is true.
> >>>
> >>> VIDEO_V4L2_SUBDEV_API depends on MEDIA_CONTROLLER, but only part of that
> >>> actually depends on MEDIA_CONTROLLER in the code. I'd vote to simplify
> >>> this and make MEDIA_CONTROLLER a requirement for any userspace access
> >>> from userspace.
> >>
> >> I agree.
> >
> > Does that mean we should rework it as a prerequisite for this series, as
> > part of the series, or separately ?
> 
> I would, for the moment, make v4l2_device_register_ro_subdev_nodes and
> v4l2_device_register_subdev_nodes dependendent on
> VIDEO_V4L2_SUBDEV_API, so that they're only available to drivers
> actually wanting userspace access. Then when moving everything to
> MEDIA_CONTROLLER, they can be moved to.
> 
> However, this is not clear to me
> https://elixir.bootlin.com/linux/latest/source/drivers/media/v4l2-core/v4l2-subdev.c#L338
> 
> What is the reason to have some of the subdev ioctls protected by
> VIDEO_V4L2_SUBDEV_API, while the v4l2-control related ones are not ?

I'd say historical mistake :-) I think we can move everything under
VIDEO_V4L2_SUBDEV_API.

> >>>>> +
> >>>>> +Access to the following ioctls for userspace applications is restricted on
> >>>>> +sub-device device nodes registered with
> >>>>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> >>>>> +
> >>>>> +``VIDIOC_SUBDEV_S_FMT``,
> >>>>> +``VIDIOC_SUBDEV_S_CROP``,
> >>>>> +``VIDIOC_SUBDEV_S_SELECTION``:
> >>>>> +
> >>>>> +	These ioctls are only allowed on a read-only subdevice device node
> >>>>> +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
> >>>>> +	formats and selection rectangles.
> >>>>> +
> >>>>> +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
> >>>>> +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
> >>>>> +``VIDIOC_SUBDEV_S_STD``:
> >>>>> +
> >>>>> +	These ioctls are not allowed on a read-only subdevice node.
> >>>>> +
> >>>>> +In case the ioclt is not allowed, or the format to modify is set to
> >>>>> +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
> >>>>> +the errno variable is set to ``-EPERM``.
> >>>>>
> >>>>>  I2C sub-device drivers
> >>>>>  ----------------------
> >>>>> diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
> >>>>> index 029bb2d9928a..6082f9c2f8f4 100644
> >>>>> --- a/Documentation/media/uapi/v4l/dev-subdev.rst
> >>>>> +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
> >>>>> @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
> >>>>>  Sub-device character device nodes, conventionally named
> >>>>>  ``/dev/v4l-subdev*``, use major number 81.
> >>>>>
> >>>>> +Drivers may opt to limit the sub-device character devices to only expose
> >>>>> +operations that don't modify the device state. In such a case the sub-devices
> >>>>
> >>>> don't -> do not
> >>>>
> >>>> ("don't" is a bit too informal)
> >>>>
> >>>>> +are referred to as ``read-only`` in the rest of this documentation, and the
> >>>>> +related restrictions are documented in individual ioctls.
> >>>>> +
> >>>>>
> >>>>>  Controls
> >>>>>  ========
> >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> >>>>> index e36dd2622857..611f94e4510a 100644
> >>>>> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> >>>>> @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
> >>>>>  structure as argument. If the ioctl is not supported or the timing
> >>>>>  values are not correct, the driver returns ``EINVAL`` error code.
> >>>>>
> >>>>> +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
> >>>>> +registered in read-only mode is not allowed. An error is returned and the errno
> >>>>> +variable is set to ``-EPERM``.
> >>>>> +
> >>>>>  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
> >>>>>  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
> >>>>>  the current input or output does not support DV timings (e.g. if
> >>>>> @@ -81,6 +85,8 @@ ENODATA
> >>>>>  EBUSY
> >>>>>      The device is busy and therefore can not change the timings.
> >>>>>
> >>>>> +EPERM
> >>>>> +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
> >>>>>
> >>>>>  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
> >>>>>
> >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> >>>>> index e633e42e3910..e220b38b859f 100644
> >>>>> --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
> >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> >>>>> @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
> >>>>>  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
> >>>>>  returned.
> >>>>>
> >>>>> +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
> >>>>> +in read-only mode is not allowed. An error is returned and the errno variable is
> >>>>> +set to ``-EPERM``.
> >>>>>
> >>>>>  Return Value
> >>>>>  ============
> >>>>> @@ -79,3 +82,6 @@ EINVAL
> >>>>>
> >>>>>  ENODATA
> >>>>>      Standard video timings are not supported for this input or output.
> >>>>> +
> >>>>> +EPERM
> >>>>> +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
> >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> >>>>> index 632ee053accc..62f5d9870ca7 100644
> >>>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> >>>>> @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
> >>>>>  applications querying the same sub-device would thus not interact with
> >>>>>  each other.
> >>>>>
> >>>>> +If the subdev device node has been registered in read-only mode calls to
> >>>>
> >>>> mode calls -> mode, calls
> >>>>
> >>>>> +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
> >>>>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> >>>>> +variable is set to ``-EPERM``.
> >>>>> +
> >>>>>  Drivers must not return an error solely because the requested crop
> >>>>>  rectangle doesn't match the device capabilities. They must instead
> >>>>>  modify the rectangle to match what the hardware can provide. The
> >>>>> @@ -123,3 +128,7 @@ EINVAL
> >>>>>      references a non-existing pad, the ``which`` field references a
> >>>>>      non-existing format, or cropping is not supported on the given
> >>>>>      subdev pad.
> >>>>> +
> >>>>> +EPERM
> >>>>> +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
> >>>>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> >>>>> index 472577bd1745..3a2f64bb00e7 100644
> >>>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> >>>>> @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
> >>>>>  a low-pass noise filter might crop pixels at the frame boundaries,
> >>>>>  modifying its output frame size.
> >>>>>
> >>>>> +If the subdev device node has been registered in read-only mode calls to
> >>>>
> >>>> ditto.
> >>>>
> >>>>> +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
> >>>>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> >>>>> +variable is set to ``-EPERM``.
> >>>>> +
> >>>>>  Drivers must not return an error solely because the requested format
> >>>>>  doesn't match the device capabilities. They must instead modify the
> >>>>>  format to match what the hardware can provide. The modified format
> >>>>> @@ -146,6 +151,9 @@ EINVAL
> >>>>>      ``pad`` references a non-existing pad, or the ``which`` field
> >>>>>      references a non-existing format.
> >>>>>
> >>>>> +EPERM
> >>>>> +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
> >>>>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> >>>>>
> >>>>>  ============
> >>>>>
> >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> >>>>> index 4b1b4bc78bfe..34aa39096e3d 100644
> >>>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> >>>>> @@ -65,6 +65,10 @@ struct
> >>>>>  contains the current frame interval as would be returned by a
> >>>>>  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
> >>>>>
> >>>>> +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
> >>>>> +registered in read-only mode is not allowed. An error is returned and the errno
> >>>>> +variable is set to ``-EPERM``.
> >>>>> +
> >>>>>  Drivers must not return an error solely because the requested interval
> >>>>>  doesn't match the device capabilities. They must instead modify the
> >>>>>  interval to match what the hardware can provide. The modified interval
> >>>>> @@ -118,3 +122,7 @@ EINVAL
> >>>>>      :c:type:`v4l2_subdev_frame_interval`
> >>>>>      ``pad`` references a non-existing pad, or the pad doesn't support
> >>>>>      frame intervals.
> >>>>> +
> >>>>> +EPERM
> >>>>> +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
> >>>>> +    subdevice.
> >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> >>>>> index fc73d27e6d74..abd046cef612 100644
> >>>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> >>>>> @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
> >>>>>  See :ref:`subdev` for more information on how each selection target
> >>>>>  affects the image processing pipeline inside the subdevice.
> >>>>>
> >>>>> +If the subdev device node has been registered in read-only mode calls to
> >>>>
> >>>> ditto
> >>>>
> >>>>> +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
> >>>>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> >>>>> +variable is set to ``-EPERM``.
> >>>>>
> >>>>>  Types of selection targets
> >>>>>  --------------------------
> >>>>> @@ -123,3 +127,7 @@ EINVAL
> >>>>>      ``pad`` references a non-existing pad, the ``which`` field
> >>>>>      references a non-existing format, or the selection target is not
> >>>>>      supported on the given subdev pad.
> >>>>> +
> >>>>> +EPERM
> >>>>> +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
> >>>>> +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.

-- 
Regards,

Laurent Pinchart

Re: [v2 2/3] Documentation: media: Document read-only subdevice

[Jacopo Mondi]

Hi Laurent,

On Mon, Apr 06, 2020 at 03:39:35PM +0300, Laurent Pinchart wrote:
> Hi Jacopo,
>
> On Mon, Apr 06, 2020 at 01:07:32PM +0200, Jacopo Mondi wrote:
> > On Sat, Apr 04, 2020 at 04:35:45AM +0300, Laurent Pinchart wrote:
> > > On Wed, Apr 01, 2020 at 01:54:13PM +0200, Hans Verkuil wrote:
> > >> On 4/1/20 1:46 PM, Laurent Pinchart wrote:
> > >>> On Wed, Apr 01, 2020 at 01:19:00PM +0200, Hans Verkuil wrote:
> > >>>> On 3/27/20 11:35 PM, Jacopo Mondi wrote:
> > >>>>> Document a new kapi function to register subdev device nodes in read only
> > >>>>
> > >>>> kAPI
> > >>>>
> > >>>>> mode and for each affected ioctl report how access is restricted.
> > >>>>>
> > >>>>> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> > >>>>> ---
> > >>>>>  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
> > >>>>>  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
> > >>>>>  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
> > >>>>>  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
> > >>>>>  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
> > >>>>>  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
> > >>>>>  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
> > >>>>>  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
> > >>>>>  8 files changed, 94 insertions(+)
> > >>>>>
> > >>>>> diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
> > >>>>> index 41ccb3e5c707..6506a673e6a1 100644
> > >>>>> --- a/Documentation/media/kapi/v4l2-subdev.rst
> > >>>>> +++ b/Documentation/media/kapi/v4l2-subdev.rst
> > >>>>> @@ -332,6 +332,50 @@ Private ioctls
> > >>>>>  	All ioctls not in the above list are passed directly to the sub-device
> > >>>>>  	driver through the core::ioctl operation.
> > >>>>>
> > >>>>> +Read-only sub-device userspace API
> > >>>>> +----------------------------------
> > >>>>> +
> > >>>>> +Bridge drivers that control their connected subdevices through direct calls to
> > >>>>> +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
> > >>>>> +want userspace to be able to change the same parameters through the subdevice
> > >>>>> +device node and thus do not usually register any.
> > >>>>> +
> > >>>>> +It is sometimes useful to report to userspace the current subdevice
> > >>>>> +configuration through a read-only API, that does not permit applications to
> > >>>>> +change to the device parameters but allows interfacing to the subdevice device
> > >>>>> +node to inspect them.
> > >>>>> +
> > >>>>> +For instance, to implement cameras based on computational photography, userspace
> > >>>>> +needs to know the detailed camera sensor configuration (in terms of skipping,
> > >>>>> +binning, cropping and scaling) for each supported output resolution. To support
> > >>>>> +such use cases, bridge drivers may expose the subdevice operations to userspace
> > >>>>> +through a read-only API.
> > >>>>> +
> > >>>>> +To create a read-only device node for all the subdevices registered with the
> > >>>>> +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
> > >>>>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> > >>>>
> > >>>> Should we add something about creating a /dev/media device as well? It's basically
> > >>>> required for this functionality.
> > >>>
> > >>> I'm not opposed to that, but I don't think this should be specific to
> > >>> the read-only API, as it's a shared requirement with thr R/W API. The
> > >>> previous section, "V4L2 sub-device userspace API", doesn't mention media
> > >>> devices.
> > >>
> > >> True.
> > >>
> > >>>> I think it might be a good idea to put v4l2_device_register_ro_subdev_nodes()
> > >>>> under #ifdef CONFIG_MEDIA_CONTROLLER so that this config *has* to be set in order
> > >>>> to be able to call this function. Or possibly have an explicit test in
> > >>>> __v4l2_device_register_subdev_nodes for the presence of a media device if
> > >>>> read_only is true.
> > >>>
> > >>> VIDEO_V4L2_SUBDEV_API depends on MEDIA_CONTROLLER, but only part of that
> > >>> actually depends on MEDIA_CONTROLLER in the code. I'd vote to simplify
> > >>> this and make MEDIA_CONTROLLER a requirement for any userspace access
> > >>> from userspace.
> > >>
> > >> I agree.
> > >
> > > Does that mean we should rework it as a prerequisite for this series, as
> > > part of the series, or separately ?
> >
> > I would, for the moment, make v4l2_device_register_ro_subdev_nodes and
> > v4l2_device_register_subdev_nodes dependendent on
> > VIDEO_V4L2_SUBDEV_API, so that they're only available to drivers
> > actually wanting userspace access. Then when moving everything to
> > MEDIA_CONTROLLER, they can be moved to.
> >
> > However, this is not clear to me
> > https://elixir.bootlin.com/linux/latest/source/drivers/media/v4l2-core/v4l2-subdev.c#L338
> >
> > What is the reason to have some of the subdev ioctls protected by
> > VIDEO_V4L2_SUBDEV_API, while the v4l2-control related ones are not ?
>
> I'd say historical mistake :-) I think we can move everything under
> VIDEO_V4L2_SUBDEV_API.
>

Good, I was afraid that limiting the ability to register subdevices to
drivers claiming support for VIDEO_V4L2_SUBDEV_API only would break
use cases that depends on the ability to set controls on a subdevice
device node without claming subdevice API support (which seems anyway
wrong to me).

I will send a new versio making resitration of subdevice devnodes
dependent on V4L2_SUBDEV_API then.

Thanks
  j

> > >>>>> +
> > >>>>> +Access to the following ioctls for userspace applications is restricted on
> > >>>>> +sub-device device nodes registered with
> > >>>>> +:c:func:`v4l2_device_register_ro_subdev_nodes`.
> > >>>>> +
> > >>>>> +``VIDIOC_SUBDEV_S_FMT``,
> > >>>>> +``VIDIOC_SUBDEV_S_CROP``,
> > >>>>> +``VIDIOC_SUBDEV_S_SELECTION``:
> > >>>>> +
> > >>>>> +	These ioctls are only allowed on a read-only subdevice device node
> > >>>>> +	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
> > >>>>> +	formats and selection rectangles.
> > >>>>> +
> > >>>>> +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
> > >>>>> +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
> > >>>>> +``VIDIOC_SUBDEV_S_STD``:
> > >>>>> +
> > >>>>> +	These ioctls are not allowed on a read-only subdevice node.
> > >>>>> +
> > >>>>> +In case the ioclt is not allowed, or the format to modify is set to
> > >>>>> +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
> > >>>>> +the errno variable is set to ``-EPERM``.
> > >>>>>
> > >>>>>  I2C sub-device drivers
> > >>>>>  ----------------------
> > >>>>> diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
> > >>>>> index 029bb2d9928a..6082f9c2f8f4 100644
> > >>>>> --- a/Documentation/media/uapi/v4l/dev-subdev.rst
> > >>>>> +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
> > >>>>> @@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
> > >>>>>  Sub-device character device nodes, conventionally named
> > >>>>>  ``/dev/v4l-subdev*``, use major number 81.
> > >>>>>
> > >>>>> +Drivers may opt to limit the sub-device character devices to only expose
> > >>>>> +operations that don't modify the device state. In such a case the sub-devices
> > >>>>
> > >>>> don't -> do not
> > >>>>
> > >>>> ("don't" is a bit too informal)
> > >>>>
> > >>>>> +are referred to as ``read-only`` in the rest of this documentation, and the
> > >>>>> +related restrictions are documented in individual ioctls.
> > >>>>> +
> > >>>>>
> > >>>>>  Controls
> > >>>>>  ========
> > >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > >>>>> index e36dd2622857..611f94e4510a 100644
> > >>>>> --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
> > >>>>> @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_timings`
> > >>>>>  structure as argument. If the ioctl is not supported or the timing
> > >>>>>  values are not correct, the driver returns ``EINVAL`` error code.
> > >>>>>
> > >>>>> +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
> > >>>>> +registered in read-only mode is not allowed. An error is returned and the errno
> > >>>>> +variable is set to ``-EPERM``.
> > >>>>> +
> > >>>>>  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
> > >>>>>  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
> > >>>>>  the current input or output does not support DV timings (e.g. if
> > >>>>> @@ -81,6 +85,8 @@ ENODATA
> > >>>>>  EBUSY
> > >>>>>      The device is busy and therefore can not change the timings.
> > >>>>>
> > >>>>> +EPERM
> > >>>>> +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
> > >>>>>
> > >>>>>  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
> > >>>>>
> > >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > >>>>> index e633e42e3910..e220b38b859f 100644
> > >>>>> --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
> > >>>>> @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
> > >>>>>  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
> > >>>>>  returned.
> > >>>>>
> > >>>>> +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
> > >>>>> +in read-only mode is not allowed. An error is returned and the errno variable is
> > >>>>> +set to ``-EPERM``.
> > >>>>>
> > >>>>>  Return Value
> > >>>>>  ============
> > >>>>> @@ -79,3 +82,6 @@ EINVAL
> > >>>>>
> > >>>>>  ENODATA
> > >>>>>      Standard video timings are not supported for this input or output.
> > >>>>> +
> > >>>>> +EPERM
> > >>>>> +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
> > >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > >>>>> index 632ee053accc..62f5d9870ca7 100644
> > >>>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
> > >>>>> @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-device file handle. Two
> > >>>>>  applications querying the same sub-device would thus not interact with
> > >>>>>  each other.
> > >>>>>
> > >>>>> +If the subdev device node has been registered in read-only mode calls to
> > >>>>
> > >>>> mode calls -> mode, calls
> > >>>>
> > >>>>> +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
> > >>>>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > >>>>> +variable is set to ``-EPERM``.
> > >>>>> +
> > >>>>>  Drivers must not return an error solely because the requested crop
> > >>>>>  rectangle doesn't match the device capabilities. They must instead
> > >>>>>  modify the rectangle to match what the hardware can provide. The
> > >>>>> @@ -123,3 +128,7 @@ EINVAL
> > >>>>>      references a non-existing pad, the ``which`` field references a
> > >>>>>      non-existing format, or cropping is not supported on the given
> > >>>>>      subdev pad.
> > >>>>> +
> > >>>>> +EPERM
> > >>>>> +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
> > >>>>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> > >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > >>>>> index 472577bd1745..3a2f64bb00e7 100644
> > >>>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
> > >>>>> @@ -78,6 +78,11 @@ current links configuration or sub-device controls value. For instance,
> > >>>>>  a low-pass noise filter might crop pixels at the frame boundaries,
> > >>>>>  modifying its output frame size.
> > >>>>>
> > >>>>> +If the subdev device node has been registered in read-only mode calls to
> > >>>>
> > >>>> ditto.
> > >>>>
> > >>>>> +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
> > >>>>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > >>>>> +variable is set to ``-EPERM``.
> > >>>>> +
> > >>>>>  Drivers must not return an error solely because the requested format
> > >>>>>  doesn't match the device capabilities. They must instead modify the
> > >>>>>  format to match what the hardware can provide. The modified format
> > >>>>> @@ -146,6 +151,9 @@ EINVAL
> > >>>>>      ``pad`` references a non-existing pad, or the ``which`` field
> > >>>>>      references a non-existing format.
> > >>>>>
> > >>>>> +EPERM
> > >>>>> +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
> > >>>>> +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
> > >>>>>
> > >>>>>  ============
> > >>>>>
> > >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > >>>>> index 4b1b4bc78bfe..34aa39096e3d 100644
> > >>>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
> > >>>>> @@ -65,6 +65,10 @@ struct
> > >>>>>  contains the current frame interval as would be returned by a
> > >>>>>  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
> > >>>>>
> > >>>>> +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
> > >>>>> +registered in read-only mode is not allowed. An error is returned and the errno
> > >>>>> +variable is set to ``-EPERM``.
> > >>>>> +
> > >>>>>  Drivers must not return an error solely because the requested interval
> > >>>>>  doesn't match the device capabilities. They must instead modify the
> > >>>>>  interval to match what the hardware can provide. The modified interval
> > >>>>> @@ -118,3 +122,7 @@ EINVAL
> > >>>>>      :c:type:`v4l2_subdev_frame_interval`
> > >>>>>      ``pad`` references a non-existing pad, or the pad doesn't support
> > >>>>>      frame intervals.
> > >>>>> +
> > >>>>> +EPERM
> > >>>>> +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
> > >>>>> +    subdevice.
> > >>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > >>>>> index fc73d27e6d74..abd046cef612 100644
> > >>>>> --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > >>>>> +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
> > >>>>> @@ -53,6 +53,10 @@ function of the crop API, and more, are supported by the selections API.
> > >>>>>  See :ref:`subdev` for more information on how each selection target
> > >>>>>  affects the image processing pipeline inside the subdevice.
> > >>>>>
> > >>>>> +If the subdev device node has been registered in read-only mode calls to
> > >>>>
> > >>>> ditto
> > >>>>
> > >>>>> +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
> > >>>>> +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
> > >>>>> +variable is set to ``-EPERM``.
> > >>>>>
> > >>>>>  Types of selection targets
> > >>>>>  --------------------------
> > >>>>> @@ -123,3 +127,7 @@ EINVAL
> > >>>>>      ``pad`` references a non-existing pad, the ``which`` field
> > >>>>>      references a non-existing format, or the selection target is not
> > >>>>>      supported on the given subdev pad.
> > >>>>> +
> > >>>>> +EPERM
> > >>>>> +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
> > >>>>> +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
>
> --
> Regards,
>
> Laurent Pinchart