target/linux/bcm27xx/patches-5.4/950-0645-Documentation-media-Document-read-only-subdevice.patch

   1 From c1a630e792140b4791bad84974e31b4a1cf09b1b Mon Sep 17 00:00:00 2001
   2 From: Jacopo Mondi <jacopo@jmondi.org>
   3 Date: Tue, 7 Apr 2020 17:21:56 +0200
   4 Subject: [PATCH] Documentation: media: Document read-only subdevice
   5
   6 Document a new kAPI function to register subdev device nodes in read only
   7 mode and for each affected ioctl report how access is restricted.
   8
   9 Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
  10 Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
  11 ---
  12  Documentation/media/kapi/v4l2-subdev.rst      | 44 +++++++++++++++++++
  13  Documentation/media/uapi/v4l/dev-subdev.rst   |  5 +++
  14  .../media/uapi/v4l/vidioc-g-dv-timings.rst    |  6 +++
  15  Documentation/media/uapi/v4l/vidioc-g-std.rst |  6 +++
  16  .../media/uapi/v4l/vidioc-subdev-g-crop.rst   |  9 ++++
  17  .../media/uapi/v4l/vidioc-subdev-g-fmt.rst    |  8 ++++
  18  .../v4l/vidioc-subdev-g-frame-interval.rst    |  8 ++++
  19  .../uapi/v4l/vidioc-subdev-g-selection.rst    |  8 ++++
  20  8 files changed, 94 insertions(+)
  21
  22 --- a/Documentation/media/kapi/v4l2-subdev.rst
  23 +++ b/Documentation/media/kapi/v4l2-subdev.rst
  24 @@ -332,6 +332,50 @@ Private ioctls
  25         All ioctls not in the above list are passed directly to the sub-device
  26         driver through the core::ioctl operation.
  27
  28 +Read-only sub-device userspace API
  29 +----------------------------------
  30 +
  31 +Bridge drivers that control their connected subdevices through direct calls to
  32 +the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
  33 +want userspace to be able to change the same parameters through the subdevice
  34 +device node and thus do not usually register any.
  35 +
  36 +It is sometimes useful to report to userspace the current subdevice
  37 +configuration through a read-only API, that does not permit applications to
  38 +change to the device parameters but allows interfacing to the subdevice device
  39 +node to inspect them.
  40 +
  41 +For instance, to implement cameras based on computational photography, userspace
  42 +needs to know the detailed camera sensor configuration (in terms of skipping,
  43 +binning, cropping and scaling) for each supported output resolution. To support
  44 +such use cases, bridge drivers may expose the subdevice operations to userspace
  45 +through a read-only API.
  46 +
  47 +To create a read-only device node for all the subdevices registered with the
  48 +``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
  49 +:c:func:`v4l2_device_register_ro_subdev_nodes`.
  50 +
  51 +Access to the following ioctls for userspace applications is restricted on
  52 +sub-device device nodes registered with
  53 +:c:func:`v4l2_device_register_ro_subdev_nodes`.
  54 +
  55 +``VIDIOC_SUBDEV_S_FMT``,
  56 +``VIDIOC_SUBDEV_S_CROP``,
  57 +``VIDIOC_SUBDEV_S_SELECTION``:
  58 +
  59 +       These ioctls are only allowed on a read-only subdevice device node
  60 +       for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
  61 +       formats and selection rectangles.
  62 +
  63 +``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
  64 +``VIDIOC_SUBDEV_S_DV_TIMINGS``,
  65 +``VIDIOC_SUBDEV_S_STD``:
  66 +
  67 +       These ioctls are not allowed on a read-only subdevice node.
  68 +
  69 +In case the ioctl is not allowed, or the format to modify is set to
  70 +``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
  71 +the errno variable is set to ``-EPERM``.
  72
  73  I2C sub-device drivers
  74  ----------------------
  75 --- a/Documentation/media/uapi/v4l/dev-subdev.rst
  76 +++ b/Documentation/media/uapi/v4l/dev-subdev.rst
  77 @@ -39,6 +39,11 @@ will feature a character device node on
  78  Sub-device character device nodes, conventionally named
  79  ``/dev/v4l-subdev*``, use major number 81.
  80
  81 +Drivers may opt to limit the sub-device character devices to only expose
  82 +operations that do not modify the device state. In such a case the sub-devices
  83 +are referred to as ``read-only`` in the rest of this documentation, and the
  84 +related restrictions are documented in individual ioctls.
  85 +
  86
  87  Controls
  88  ========
  89 --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
  90 +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
  91 @@ -57,6 +57,10 @@ pointer to the struct :c:type:`v4l2_dv_t
  92  structure as argument. If the ioctl is not supported or the timing
  93  values are not correct, the driver returns ``EINVAL`` error code.
  94
  95 +Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
  96 +registered in read-only mode is not allowed. An error is returned and the errno
  97 +variable is set to ``-EPERM``.
  98 +
  99  The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
 100  the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
 101  the current input or output does not support DV timings (e.g. if
 102 @@ -81,6 +85,8 @@ ENODATA
 103  EBUSY
 104      The device is busy and therefore can not change the timings.
 105
 106 +EPERM
 107 +    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.
 108
 109  .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 110
 111 --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst
 112 +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
 113 @@ -66,6 +66,9 @@ video timings (e.g. if :ref:`VIDIOC_ENUM
 114  does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
 115  returned.
 116
 117 +Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
 118 +in read-only mode is not allowed. An error is returned and the errno variable is
 119 +set to ``-EPERM``.
 120
 121  Return Value
 122  ============
 123 @@ -79,3 +82,6 @@ EINVAL
 124
 125  ENODATA
 126      Standard video timings are not supported for this input or output.
 127 +
 128 +EPERM
 129 +    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
 130 --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
 131 +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
 132 @@ -73,6 +73,11 @@ crop rectangles and stored in the sub-de
 133  applications querying the same sub-device would thus not interact with
 134  each other.
 135
 136 +If the subdev device node has been registered in read-only mode, calls to
 137 +``VIDIOC_SUBDEV_S_CROP`` are only valid if the ``which`` field is set to
 138 +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
 139 +variable is set to ``-EPERM``.
 140 +
 141  Drivers must not return an error solely because the requested crop
 142  rectangle doesn't match the device capabilities. They must instead
 143  modify the rectangle to match what the hardware can provide. The
 144 @@ -123,3 +128,7 @@ EINVAL
 145      references a non-existing pad, the ``which`` field references a
 146      non-existing format, or cropping is not supported on the given
 147      subdev pad.
 148 +
 149 +EPERM
 150 +    The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice
 151 +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
 152 --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
 153 +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
 154 @@ -78,6 +78,11 @@ current links configuration or sub-devic
 155  a low-pass noise filter might crop pixels at the frame boundaries,
 156  modifying its output frame size.
 157
 158 +If the subdev device node has been registered in read-only mode, calls to
 159 +``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
 160 +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
 161 +variable is set to ``-EPERM``.
 162 +
 163  Drivers must not return an error solely because the requested format
 164  doesn't match the device capabilities. They must instead modify the
 165  format to match what the hardware can provide. The modified format
 166 @@ -146,6 +151,9 @@ EINVAL
 167      ``pad`` references a non-existing pad, or the ``which`` field
 168      references a non-existing format.
 169
 170 +EPERM
 171 +    The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
 172 +    and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
 173
 174  ============
 175
 176 --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
 177 +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
 178 @@ -65,6 +65,10 @@ struct
 179  contains the current frame interval as would be returned by a
 180  ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
 181
 182 +Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
 183 +registered in read-only mode is not allowed. An error is returned and the errno
 184 +variable is set to ``-EPERM``.
 185 +
 186  Drivers must not return an error solely because the requested interval
 187  doesn't match the device capabilities. They must instead modify the
 188  interval to match what the hardware can provide. The modified interval
 189 @@ -118,3 +122,7 @@ EINVAL
 190      :c:type:`v4l2_subdev_frame_interval`
 191      ``pad`` references a non-existing pad, or the pad doesn't support
 192      frame intervals.
 193 +
 194 +EPERM
 195 +    The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
 196 +    subdevice.
 197 --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
 198 +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
 199 @@ -53,6 +53,10 @@ function of the crop API, and more, are
 200  See :ref:`subdev` for more information on how each selection target
 201  affects the image processing pipeline inside the subdevice.
 202
 203 +If the subdev device node has been registered in read-only mode, calls to
 204 +``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
 205 +``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
 206 +variable is set to ``-EPERM``.
 207
 208  Types of selection targets
 209  --------------------------
 210 @@ -123,3 +127,7 @@ EINVAL
 211      ``pad`` references a non-existing pad, the ``which`` field
 212      references a non-existing format, or the selection target is not
 213      supported on the given subdev pad.
 214 +
 215 +EPERM
 216 +    The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
 217 +    subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.