From 2b455a551f2e428d18086393f54ddf921193f208 Mon Sep 17 00:00:00 2001
From: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Date: Wed, 13 Dec 2023 17:00:07 +0200
Subject: [PATCH] media: docs: uAPI: Clarify error documentation for invalid
'which' value
Invalid values for the 'which' field of structures passed to multiple
subdev ioctls result in an EINVAL error being returned. The
documentation of the corresponding ioctls indicates this with sentences
such as the following:
the ``which`` field references a non-existing format
This is confusing. Clarify the documentation.
Suggested-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
---
.../userspace-api/media/v4l/vidioc-subdev-g-crop.rst | 7 +++----
.../userspace-api/media/v4l/vidioc-subdev-g-fmt.rst | 5 ++---
.../media/v4l/vidioc-subdev-g-frame-interval.rst | 7 +++----
.../userspace-api/media/v4l/vidioc-subdev-g-selection.rst | 7 +++----
4 files changed, 11 insertions(+), 15 deletions(-)
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst
index 1d267f7e79911..92d933631fda8 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst
@@ -118,10 +118,9 @@ EBUSY
``VIDIOC_SUBDEV_S_CROP``
EINVAL
- The struct :c:type:`v4l2_subdev_crop` ``pad``
- references a non-existing pad, the ``which`` field references a
- non-existing format, or cropping is not supported on the given
- subdev pad.
+ The struct :c:type:`v4l2_subdev_crop` ``pad`` references a non-existing pad,
+ the ``which`` field has an unsupported value, 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
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst
index ed253a1e44b70..4a2b4e4f0152f 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst
@@ -140,9 +140,8 @@ EBUSY
fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT``
EINVAL
- The struct :c:type:`v4l2_subdev_format`
- ``pad`` references a non-existing pad, or the ``which`` field
- references a non-existing format.
+ The struct :c:type:`v4l2_subdev_format` ``pad`` references a non-existing
+ pad, or the ``which`` field has an unsupported value.
EPERM
The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst
index 41e0e2c8ecc3f..c8022809ac35f 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst
@@ -117,10 +117,9 @@ EBUSY
``VIDIOC_SUBDEV_S_FRAME_INTERVAL``
EINVAL
- The struct
- :c:type:`v4l2_subdev_frame_interval`
- ``pad`` references a non-existing pad, the ``which`` field references a
- non-existing frame interval, or the pad doesn't support frame intervals.
+ The struct :c:type:`v4l2_subdev_frame_interval` ``pad`` references a
+ non-existing pad, the ``which`` field has an unsupported value, or the pad
+ doesn't support frame intervals.
EPERM
The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst
index 6b629c19168c0..19e6c3e9c06da 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst
@@ -116,10 +116,9 @@ EBUSY
``VIDIOC_SUBDEV_S_SELECTION``
EINVAL
- The struct :c:type:`v4l2_subdev_selection`
- ``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.
+ The struct :c:type:`v4l2_subdev_selection` ``pad`` references a
+ non-existing pad, the ``which`` field has an unsupported value, 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
--
GitLab