media: Documentation: media: Document read-only subdevice
Document a new kAPI function to register subdev device nodes in read only mode and for each affected ioctl report how access is restricted. Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
This commit is contained in:
parent
18200e9e24
commit
3fb0ee8b3b
|
@ -332,6 +332,50 @@ Private ioctls
|
||||||
All ioctls not in the above list are passed directly to the sub-device
|
All ioctls not in the above list are passed directly to the sub-device
|
||||||
driver through the core::ioctl operation.
|
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 ioctl 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
|
I2C sub-device drivers
|
||||||
----------------------
|
----------------------
|
||||||
|
|
|
@ -39,6 +39,11 @@ will feature a character device node on which ioctls can be called to
|
||||||
Sub-device character device nodes, conventionally named
|
Sub-device character device nodes, conventionally named
|
||||||
``/dev/v4l-subdev*``, use major number 81.
|
``/dev/v4l-subdev*``, use major number 81.
|
||||||
|
|
||||||
|
Drivers may opt to limit the sub-device character devices to only expose
|
||||||
|
operations that do not 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
|
Controls
|
||||||
========
|
========
|
||||||
|
|
|
@ -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
|
structure as argument. If the ioctl is not supported or the timing
|
||||||
values are not correct, the driver returns ``EINVAL`` error code.
|
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 ``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 formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
|
||||||
the current input or output does not support DV timings (e.g. if
|
the current input or output does not support DV timings (e.g. if
|
||||||
|
@ -81,6 +85,8 @@ ENODATA
|
||||||
EBUSY
|
EBUSY
|
||||||
The device is busy and therefore can not change the timings.
|
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}|
|
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
|
||||||
|
|
||||||
|
|
|
@ -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
|
does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
|
||||||
returned.
|
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
|
Return Value
|
||||||
============
|
============
|
||||||
|
@ -79,3 +82,6 @@ EINVAL
|
||||||
|
|
||||||
ENODATA
|
ENODATA
|
||||||
Standard video timings are not supported for this input or output.
|
Standard video timings are not supported for this input or output.
|
||||||
|
|
||||||
|
EPERM
|
||||||
|
``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.
|
||||||
|
|
|
@ -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
|
applications querying the same sub-device would thus not interact with
|
||||||
each other.
|
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
|
Drivers must not return an error solely because the requested crop
|
||||||
rectangle doesn't match the device capabilities. They must instead
|
rectangle doesn't match the device capabilities. They must instead
|
||||||
modify the rectangle to match what the hardware can provide. The
|
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
|
references a non-existing pad, the ``which`` field references a
|
||||||
non-existing format, or cropping is not supported on the given
|
non-existing format, or cropping is not supported on the given
|
||||||
subdev pad.
|
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``.
|
||||||
|
|
|
@ -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,
|
a low-pass noise filter might crop pixels at the frame boundaries,
|
||||||
modifying its output frame size.
|
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
|
Drivers must not return an error solely because the requested format
|
||||||
doesn't match the device capabilities. They must instead modify the
|
doesn't match the device capabilities. They must instead modify the
|
||||||
format to match what the hardware can provide. The modified format
|
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
|
``pad`` references a non-existing pad, or the ``which`` field
|
||||||
references a non-existing format.
|
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``.
|
||||||
|
|
||||||
============
|
============
|
||||||
|
|
||||||
|
|
|
@ -65,6 +65,10 @@ struct
|
||||||
contains the current frame interval as would be returned by a
|
contains the current frame interval as would be returned by a
|
||||||
``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
|
``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
|
Drivers must not return an error solely because the requested interval
|
||||||
doesn't match the device capabilities. They must instead modify the
|
doesn't match the device capabilities. They must instead modify the
|
||||||
interval to match what the hardware can provide. The modified interval
|
interval to match what the hardware can provide. The modified interval
|
||||||
|
@ -118,3 +122,7 @@ EINVAL
|
||||||
:c:type:`v4l2_subdev_frame_interval`
|
:c:type:`v4l2_subdev_frame_interval`
|
||||||
``pad`` references a non-existing pad, or the pad doesn't support
|
``pad`` references a non-existing pad, or the pad doesn't support
|
||||||
frame intervals.
|
frame intervals.
|
||||||
|
|
||||||
|
EPERM
|
||||||
|
The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
|
||||||
|
subdevice.
|
||||||
|
|
|
@ -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
|
See :ref:`subdev` for more information on how each selection target
|
||||||
affects the image processing pipeline inside the subdevice.
|
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
|
Types of selection targets
|
||||||
--------------------------
|
--------------------------
|
||||||
|
@ -123,3 +127,7 @@ EINVAL
|
||||||
``pad`` references a non-existing pad, the ``which`` field
|
``pad`` references a non-existing pad, the ``which`` field
|
||||||
references a non-existing format, or the selection target is not
|
references a non-existing format, or the selection target is not
|
||||||
supported on the given subdev pad.
|
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``.
|
||||||
|
|
Loading…
Reference in a new issue