Skip to contentSkip to conversation

media: Documentation: Deprecate s_stream video op, update docs

PATCH Superseded Sakari Ailus 3 participants 11 messages Sep 17, 2024

Subsystems (2)

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Sakari Ailus

author maintainer
#0 lore raw

PATCH 1/2 media: Documentation: Deprecate s_stream video op, update docs

The scope of the s_stream video operation is now fully supported by {enable,disable}_straems. Explicitly document the s_stream() op as deprecated and update the related documentation.

---
 Documentation/driver-api/media/camera-sensor.rst |  8 ++++----
 Documentation/driver-api/media/tx-rx.rst         | 11 ++++++-----
 include/media/v4l2-subdev.h                      |  5 +++--
 3 files changed, 13 insertions(+), 11 deletions(-)
Documentation/driver-api/media/camera-sensor.rst +4 -4
index b4920b34cebc..c290833165e6 100644
@@ -81,10 +81,10 @@ restart when the system is resumed. This requires coordination between the
 camera sensor and the rest of the camera pipeline. Bridge drivers are
 responsible for this coordination, and instruct camera sensors to stop and
 restart streaming by calling the appropriate subdev operations
-(``.s_stream()``, ``.enable_streams()`` or ``.disable_streams()``). Camera
-sensor drivers shall therefore **not** keep track of the streaming state to
-stop streaming in the PM suspend handler and restart it in the resume handler.
-Drivers should in general not implement the system PM handlers.
+(``.enable_streams()`` or ``.disable_streams()``). Camera sensor drivers shall
+therefore **not** keep track of the streaming state to stop streaming in the PM
+suspend handler and restart it in the resume handler. Drivers should in general
+not implement the system PM handlers.
 
 Camera sensor drivers shall **not** implement the subdev ``.s_power()``
 operation, as it is deprecated. While this operation is implemented in some
Documentation/driver-api/media/tx-rx.rst +6 -5
index 29d66a47b56e..a339df61fca8 100644
@@ -49,11 +49,12 @@ Link frequency
 The :ref:`V4L2_CID_LINK_FREQ <v4l2-cid-link-freq>` control is used to tell the
 receiver the frequency of the bus (i.e. it is not the same as the symbol rate).
 
-``.s_stream()`` callback
-^^^^^^^^^^^^^^^^^^^^^^^^
+``.enable_streams()`` and ``.disable_streams()`` callbacks
+^^^^^^^^^^^^^^^^^^^^^^^^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The struct struct v4l2_subdev_video_ops->s_stream() callback is used by the
-receiver driver to control the transmitter driver's streaming state.
+The struct v4l2_subdev_pad_ops->enable_streams() and struct
+v4l2_subdev_pad_ops->disable_streams() callbacks are used by the receiver driver
+to control the transmitter driver's streaming state.
 
 
 CSI-2 transmitter drivers
@@ -127,7 +128,7 @@ Stopping the transmitter
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 A transmitter stops sending the stream of images as a result of
-calling the ``.s_stream()`` callback. Some transmitters may stop the
+calling the ``.disable_streams()`` callback. Some transmitters may stop the
 stream at a frame boundary whereas others stop immediately,
 effectively leaving the current frame unfinished. The receiver driver
 should not make assumptions either way, but function properly in both
include/media/v4l2-subdev.h +3 -2
index 8daa0929865c..3cc6b4a5935f 100644
@@ -450,8 +450,9 @@ enum v4l2_subdev_pre_streamon_flags {
  *	already started or stopped subdev. Also see call_s_stream wrapper in
  *	v4l2-subdev.c.
  *
- *	New drivers should instead implement &v4l2_subdev_pad_ops.enable_streams
- *	and &v4l2_subdev_pad_ops.disable_streams operations, and use
+ *	This callback is DEPRECATED. New drivers should instead implement
+ *	&v4l2_subdev_pad_ops.enable_streams and
+ *	&v4l2_subdev_pad_ops.disable_streams operations, and use
  *	v4l2_subdev_s_stream_helper for the &v4l2_subdev_video_ops.s_stream
  *	operation to support legacy users.
  *
Signature · 1 line
2.39.5
author maintainer
#1 lore raw

PATCH 2/2 media: Documentation: Update {enable,disable}_streams documentation

Document the expected {enable,disable}_streams callback behaviour for drivers that are stream-unaware i.e. don't specify the V4L2_SUBDEV_CAP_STREAMS sub-device capability flat. In this specific case, the mask argument can be ignored.

---
 include/media/v4l2-subdev.h | 8 ++++++++
 1 file changed, 8 insertions(+)
include/media/v4l2-subdev.h +8 -0
index 3cc6b4a5935f..67a6e6ec58b8 100644
@@ -834,11 +834,19 @@ struct v4l2_subdev_state {
  *	v4l2_subdev_init_finalize() at initialization time). Do not call
  *	directly, use v4l2_subdev_enable_streams() instead.
  *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to
+ *	be concerned with the mask argument.
+ *
  * @disable_streams: Disable the streams defined in streams_mask on the given
  *	source pad. Subdevs that implement this operation must use the active
  *	state management provided by the subdev core (enabled through a call to
  *	v4l2_subdev_init_finalize() at initialization time). Do not call
  *	directly, use v4l2_subdev_disable_streams() instead.
+ *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to
+ *	be concerned with the mask argument.
  */
 struct v4l2_subdev_pad_ops {
 	int (*enum_mbus_code)(struct v4l2_subdev *sd,
Signature · 1 line
2.39.5
#2 lore raw

Re: [PATCH 2/2] media: Documentation: Update {enable,disable}_streams documentation

Quoted 4 lines · Sakari Ailus

Document the expected {enable,disable}_streams callback behaviour for drivers that are stream-unaware i.e. don't specify the V4L2_SUBDEV_CAP_STREAMS sub-device capability flat. In this specific case, the mask argument can be ignored.

Wouldn't it be better to use BIT(0) in that case to simplifiy interoperability with stream-aware devices ?

Quoted 29 lines
---
 include/media/v4l2-subdev.h | 8 ++++++++
 1 file changed, 8 insertions(+)
include/media/v4l2-subdev.h +8 -0
index 3cc6b4a5935f..67a6e6ec58b8 100644
@@ -834,11 +834,19 @@ struct v4l2_subdev_state {
  *	v4l2_subdev_init_finalize() at initialization time). Do not call
  *	directly, use v4l2_subdev_enable_streams() instead.
  *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to
+ *	be concerned with the mask argument.
+ *
  * @disable_streams: Disable the streams defined in streams_mask on the given
  *	source pad. Subdevs that implement this operation must use the active
  *	state management provided by the subdev core (enabled through a call to
  *	v4l2_subdev_init_finalize() at initialization time). Do not call
  *	directly, use v4l2_subdev_disable_streams() instead.
+ *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to
+ *	be concerned with the mask argument.
  */
 struct v4l2_subdev_pad_ops {
 	int (*enum_mbus_code)(struct v4l2_subdev *sd,
Signature · 3 lines
Regards,

Laurent Pinchart
#3 lore raw

Re: [PATCH 2/2] media: Documentation: Update {enable,disable}_streams documentation

Quoted 8 lines · Laurent Pinchart
Quoted 4 lines · Sakari Ailus

Document the expected {enable,disable}_streams callback behaviour for drivers that are stream-unaware i.e. don't specify the V4L2_SUBDEV_CAP_STREAMS sub-device capability flat. In this specific case, the mask argument can be ignored.

Wouldn't it be better to use BIT(0) in that case to simplifiy interoperability with stream-aware devices ?

The caller has to set BIT(0), but I think here the documentation is about the callee.

If the driver is not stream aware and implements the callbacks, it will get BIT(0) as the mask parameter (do we enforce this?), but as there's nothing it can do with the parameter it "does not need to be concerned with the mask argument".

Tomi

Quoted 30 lines
Quoted 29 lines
---
  include/media/v4l2-subdev.h | 8 ++++++++
  1 file changed, 8 insertions(+)
include/media/v4l2-subdev.h +8 -0
index 3cc6b4a5935f..67a6e6ec58b8 100644
@@ -834,11 +834,19 @@ struct v4l2_subdev_state {
   *	v4l2_subdev_init_finalize() at initialization time). Do not call
   *	directly, use v4l2_subdev_enable_streams() instead.
   *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to
+ *	be concerned with the mask argument.
+ *
   * @disable_streams: Disable the streams defined in streams_mask on the given
   *	source pad. Subdevs that implement this operation must use the active
   *	state management provided by the subdev core (enabled through a call to
   *	v4l2_subdev_init_finalize() at initialization time). Do not call
   *	directly, use v4l2_subdev_disable_streams() instead.
+ *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to
+ *	be concerned with the mask argument.
   */
  struct v4l2_subdev_pad_ops {
  	int (*enum_mbus_code)(struct v4l2_subdev *sd,
#4 lore raw

Re: [PATCH 2/2] media: Documentation: Update {enable,disable}_streams documentation

Quoted 10 lines · Tomi Valkeinen
Quoted 8 lines · Laurent Pinchart
Quoted 4 lines · Sakari Ailus

Document the expected {enable,disable}_streams callback behaviour for drivers that are stream-unaware i.e. don't specify the V4L2_SUBDEV_CAP_STREAMS sub-device capability flat. In this specific case, the mask argument can be ignored.

Wouldn't it be better to use BIT(0) in that case to simplifiy interoperability with stream-aware devices ?

Quoted 7 lines

The caller has to set BIT(0), but I think here the documentation is about the callee.

If the driver is not stream aware and implements the callbacks, it will get BIT(0) as the mask parameter (do we enforce this?), but as there's nothing it can do with the parameter it "does not need to be concerned with the mask argument".

Right. I had misunderstood the patch.

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
---
  include/media/v4l2-subdev.h | 8 ++++++++
  1 file changed, 8 insertions(+)
Quoted 10 lines
Quoted 10 lines

include/media/v4l2-subdev.h struct v4l2_subdev_state { · line 838

Quoted 10 lines
include/media/v4l2-subdev.h +2 -0
index 3cc6b4a5935f..67a6e6ec58b8 100644
@@ -834,11 +834,19 @@ struct v4l2_subdev_state {
   *	v4l2_subdev_init_finalize() at initialization time). Do not call
   *	directly, use v4l2_subdev_enable_streams() instead.
   *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to

s/capatility/capability/

Same below.

Quoted 1 line
Quoted 1 line

include/media/v4l2-subdev.h struct v4l2_subdev_state { · line 839

Quoted 1 line
include/media/v4l2-subdev.h +1 -0
+ *	be concerned with the mask argument.

How about "can ignore the mask argument" instead ? I interpreted as "not need to be concerned with" from the point of view of the caller.

Quoted 13 lines
Quoted 13 lines
Quoted 13 lines
include/media/v4l2-subdev.h +5 -0
+ *
   * @disable_streams: Disable the streams defined in streams_mask on the given
   *	source pad. Subdevs that implement this operation must use the active
   *	state management provided by the subdev core (enabled through a call to
   *	v4l2_subdev_init_finalize() at initialization time). Do not call
   *	directly, use v4l2_subdev_disable_streams() instead.
+ *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to
+ *	be concerned with the mask argument.
   */
  struct v4l2_subdev_pad_ops {
  	int (*enum_mbus_code)(struct v4l2_subdev *sd,
Signature · 3 lines
Regards,

Laurent Pinchart
#5 lore raw

Re: [PATCH 2/2] media: Documentation: Update {enable,disable}_streams documentation

Quoted 39 lines · Laurent Pinchart
Quoted 10 lines · Tomi Valkeinen
Quoted 8 lines · Laurent Pinchart
Quoted 4 lines · Sakari Ailus

Document the expected {enable,disable}_streams callback behaviour for drivers that are stream-unaware i.e. don't specify the V4L2_SUBDEV_CAP_STREAMS sub-device capability flat. In this specific case, the mask argument can be ignored.

Wouldn't it be better to use BIT(0) in that case to simplifiy interoperability with stream-aware devices ?

Quoted 7 lines

The caller has to set BIT(0), but I think here the documentation is about the callee.

If the driver is not stream aware and implements the callbacks, it will get BIT(0) as the mask parameter (do we enforce this?), but as there's nothing it can do with the parameter it "does not need to be concerned with the mask argument".

Right. I had misunderstood the patch.

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
---
   include/media/v4l2-subdev.h | 8 ++++++++
   1 file changed, 8 insertions(+)
Quoted 10 lines
Quoted 10 lines

include/media/v4l2-subdev.h struct v4l2_subdev_state { · line 838

Quoted 10 lines
include/media/v4l2-subdev.h +2 -0
index 3cc6b4a5935f..67a6e6ec58b8 100644
@@ -834,11 +834,19 @@ struct v4l2_subdev_state {
    *	v4l2_subdev_init_finalize() at initialization time). Do not call
    *	directly, use v4l2_subdev_enable_streams() instead.
    *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to

s/capatility/capability/

Quoted 6 lines

Same below.

Quoted 1 line
Quoted 1 line

include/media/v4l2-subdev.h struct v4l2_subdev_state { · line 839

Quoted 1 line
include/media/v4l2-subdev.h +1 -0
+ *	be concerned with the mask argument.

How about "can ignore the mask argument" instead ? I interpreted as "not need to be concerned with" from the point of view of the caller.

Or maybe, to be transparent, "can ignore the mask argument as it is always 1".

Tomi

author maintainer
#6 lore raw

Re: [PATCH 2/2] media: Documentation: Update {enable,disable}_streams documentation

In reply to Laurent Pinchart

Hi Laurent,

Quoted 39 lines · Laurent Pinchart
Quoted 10 lines · Tomi Valkeinen
Quoted 8 lines · Laurent Pinchart
Quoted 4 lines · Sakari Ailus

Document the expected {enable,disable}_streams callback behaviour for drivers that are stream-unaware i.e. don't specify the V4L2_SUBDEV_CAP_STREAMS sub-device capability flat. In this specific case, the mask argument can be ignored.

Wouldn't it be better to use BIT(0) in that case to simplifiy interoperability with stream-aware devices ?

Quoted 7 lines

The caller has to set BIT(0), but I think here the documentation is about the callee.

If the driver is not stream aware and implements the callbacks, it will get BIT(0) as the mask parameter (do we enforce this?), but as there's nothing it can do with the parameter it "does not need to be concerned with the mask argument".

Right. I had misunderstood the patch.

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
---
  include/media/v4l2-subdev.h | 8 ++++++++
  1 file changed, 8 insertions(+)
Quoted 10 lines
Quoted 10 lines

include/media/v4l2-subdev.h struct v4l2_subdev_state { · line 838

Quoted 10 lines
include/media/v4l2-subdev.h +2 -0
index 3cc6b4a5935f..67a6e6ec58b8 100644
@@ -834,11 +834,19 @@ struct v4l2_subdev_state {
   *	v4l2_subdev_init_finalize() at initialization time). Do not call
   *	directly, use v4l2_subdev_enable_streams() instead.
   *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to

s/capatility/capability/

Quoted 6 lines

Same below.

Quoted 1 line
Quoted 1 line

include/media/v4l2-subdev.h struct v4l2_subdev_state { · line 839

Quoted 1 line
include/media/v4l2-subdev.h +1 -0
+ *	be concerned with the mask argument.

How about "can ignore the mask argument" instead ? I interpreted as "not need to be concerned with" from the point of view of the caller.

Sounds good. I'll address these in v3, after waiting a bit for further comments.

Quoted 15 lines
Quoted 14 lines
Quoted 14 lines
Quoted 14 lines
include/media/v4l2-subdev.h +5 -0
+ *
   * @disable_streams: Disable the streams defined in streams_mask on the given
   *	source pad. Subdevs that implement this operation must use the active
   *	state management provided by the subdev core (enabled through a call to
   *	v4l2_subdev_init_finalize() at initialization time). Do not call
   *	directly, use v4l2_subdev_disable_streams() instead.
+ *
+ *	Drivers that support only a single stream without setting the
+ *	V4L2_SUBDEV_CAP_STREAMS sub-device capatility flag do not need to
+ *	be concerned with the mask argument.
   */
  struct v4l2_subdev_pad_ops {
  	int (*enum_mbus_code)(struct v4l2_subdev *sd,
Signature · 3 lines
Kind regards,

Sakari Ailus
author maintainer
#7 lore raw

Re: [PATCH 2/2] media: Documentation: Update {enable,disable}_streams documentation

In reply to Laurent Pinchart

Hi Laurent,

Quoted 8 lines · Laurent Pinchart
Quoted 4 lines · Sakari Ailus

Document the expected {enable,disable}_streams callback behaviour for drivers that are stream-unaware i.e. don't specify the V4L2_SUBDEV_CAP_STREAMS sub-device capability flat. In this specific case, the mask argument can be ignored.

Wouldn't it be better to use BIT(0) in that case to simplifiy interoperability with stream-aware devices ?

That's indeed the current implementation.

Signature · 3 lines
Regards,

Sakari Ailus
#8 lore raw
In reply to Sakari Ailus
Quoted 16 lines · Sakari Ailus

The scope of the s_stream video operation is now fully supported by {enable,disable}_straems. Explicitly document the s_stream() op as deprecated and update the related documentation.

---
  Documentation/driver-api/media/camera-sensor.rst |  8 ++++----
  Documentation/driver-api/media/tx-rx.rst         | 11 ++++++-----
  include/media/v4l2-subdev.h                      |  5 +++--
  3 files changed, 13 insertions(+), 11 deletions(-)
Documentation/driver-api/media/camera-sensor.rst +0 -0
index b4920b34cebc..c290833165e6 100644

Documentation/driver-api/media/camera-sensor.rst restart when the system is resumed. This requires coordination between the · line 84

Quoted 8 lines
Documentation/driver-api/media/camera-sensor.rst +1 -4
@@ -81,10 +81,10 @@ restart when the system is resumed. This requires coordination between the
  camera sensor and the rest of the camera pipeline. Bridge drivers are
  responsible for this coordination, and instruct camera sensors to stop and
  restart streaming by calling the appropriate subdev operations
-(``.s_stream()``, ``.enable_streams()`` or ``.disable_streams()``). Camera
-sensor drivers shall therefore **not** keep track of the streaming state to
-stop streaming in the PM suspend handler and restart it in the resume handler.
-Drivers should in general not implement the system PM handlers.
+(``.enable_streams()`` or ``.disable_streams()``). Camera sensor drivers shall

I didn't go through the docs, but I think we need to make it clear somewhere that v4l2_subdev_enable_streams() and v4l2_subdev_disable_streams() _must_ be used to enable/disable the streaming in the source subdevice, and the related subdev callbacks must not be called directly.

Also, v4l2_subdev_enable_streams() and v4l2_subdev_disable_streams() kernel doc doesn't seem to clarify that if the driver using those functions does not support streams, it should use BIT_ULL(1) as the streams_mask parameter.

Tomi

Quoted 52 lines
Documentation/driver-api/media/camera-sensor.rst +3 -0
+therefore **not** keep track of the streaming state to stop streaming in the PM
+suspend handler and restart it in the resume handler. Drivers should in general
+not implement the system PM handlers.
 
  Camera sensor drivers shall **not** implement the subdev ``.s_power()``
  operation, as it is deprecated. While this operation is implemented in some
Documentation/driver-api/media/tx-rx.rst +6 -5
index 29d66a47b56e..a339df61fca8 100644
@@ -49,11 +49,12 @@ Link frequency
  The :ref:`V4L2_CID_LINK_FREQ <v4l2-cid-link-freq>` control is used to tell the
  receiver the frequency of the bus (i.e. it is not the same as the symbol rate).
 
-``.s_stream()`` callback
-^^^^^^^^^^^^^^^^^^^^^^^^
+``.enable_streams()`` and ``.disable_streams()`` callbacks
+^^^^^^^^^^^^^^^^^^^^^^^^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The struct struct v4l2_subdev_video_ops->s_stream() callback is used by the
-receiver driver to control the transmitter driver's streaming state.
+The struct v4l2_subdev_pad_ops->enable_streams() and struct
+v4l2_subdev_pad_ops->disable_streams() callbacks are used by the receiver driver
+to control the transmitter driver's streaming state.
 
 
  CSI-2 transmitter drivers
@@ -127,7 +128,7 @@ Stopping the transmitter
  ^^^^^^^^^^^^^^^^^^^^^^^^
 
  A transmitter stops sending the stream of images as a result of
-calling the ``.s_stream()`` callback. Some transmitters may stop the
+calling the ``.disable_streams()`` callback. Some transmitters may stop the
  stream at a frame boundary whereas others stop immediately,
  effectively leaving the current frame unfinished. The receiver driver
  should not make assumptions either way, but function properly in both
include/media/v4l2-subdev.h +3 -2
index 8daa0929865c..3cc6b4a5935f 100644
@@ -450,8 +450,9 @@ enum v4l2_subdev_pre_streamon_flags {
   *	already started or stopped subdev. Also see call_s_stream wrapper in
   *	v4l2-subdev.c.
   *
- *	New drivers should instead implement &v4l2_subdev_pad_ops.enable_streams
- *	and &v4l2_subdev_pad_ops.disable_streams operations, and use
+ *	This callback is DEPRECATED. New drivers should instead implement
+ *	&v4l2_subdev_pad_ops.enable_streams and
+ *	&v4l2_subdev_pad_ops.disable_streams operations, and use
   *	v4l2_subdev_s_stream_helper for the &v4l2_subdev_video_ops.s_stream
   *	operation to support legacy users.
   *
Reviewed-by
#9 lore raw
Quoted 23 lines · Tomi Valkeinen
Quoted 22 lines · Sakari Ailus

The scope of the s_stream video operation is now fully supported by {enable,disable}_straems. Explicitly document the s_stream() op as deprecated and update the related documentation.

---
  Documentation/driver-api/media/camera-sensor.rst |  8 ++++----
  Documentation/driver-api/media/tx-rx.rst         | 11 ++++++-----
  include/media/v4l2-subdev.h                      |  5 +++--
  3 files changed, 13 insertions(+), 11 deletions(-)
Documentation/driver-api/media/camera-sensor.rst +0 -3
index b4920b34cebc..c290833165e6 100644
@@ -81,10 +81,10 @@ restart when the system is resumed. This requires coordination between the
  camera sensor and the rest of the camera pipeline. Bridge drivers are
  responsible for this coordination, and instruct camera sensors to stop and
  restart streaming by calling the appropriate subdev operations
-(``.s_stream()``, ``.enable_streams()`` or ``.disable_streams()``). Camera
-sensor drivers shall therefore **not** keep track of the streaming state to
-stop streaming in the PM suspend handler and restart it in the resume handler.
Quoted 8 lines

Documentation/driver-api/media/camera-sensor.rst restart when the system is resumed. This requires coordination between the · line 84

Quoted 2 lines
Documentation/driver-api/media/camera-sensor.rst +1 -1
-Drivers should in general not implement the system PM handlers.
+(``.enable_streams()`` or ``.disable_streams()``). Camera sensor drivers shall

I didn't go through the docs, but I think we need to make it clear somewhere that v4l2_subdev_enable_streams() and v4l2_subdev_disable_streams() _must_ be used to enable/disable the streaming in the source subdevice, and the related subdev callbacks must not be called directly.

include/media/v4l2-subdev.h states

* @enable_streams: Enable the streams defined in streams_mask on the given

 *      source pad. Subdevs that implement this operation must use the active
 *      state management provided by the subdev core (enabled through a call to
 *      v4l2_subdev_init_finalize() at initialization time). Do not call
 *      directly, use v4l2_subdev_enable_streams() instead.

This patch looks good to me.

Quoted 57 lines

Also, v4l2_subdev_enable_streams() and v4l2_subdev_disable_streams() kernel doc doesn't seem to clarify that if the driver using those functions does not support streams, it should use BIT_ULL(1) as the streams_mask parameter.

Quoted 52 lines
Documentation/driver-api/media/camera-sensor.rst +3 -0
+therefore **not** keep track of the streaming state to stop streaming in the PM
+suspend handler and restart it in the resume handler. Drivers should in general
+not implement the system PM handlers.
 
  Camera sensor drivers shall **not** implement the subdev ``.s_power()``
  operation, as it is deprecated. While this operation is implemented in some
Documentation/driver-api/media/tx-rx.rst +6 -5
index 29d66a47b56e..a339df61fca8 100644
@@ -49,11 +49,12 @@ Link frequency
  The :ref:`V4L2_CID_LINK_FREQ <v4l2-cid-link-freq>` control is used to tell the
  receiver the frequency of the bus (i.e. it is not the same as the symbol rate).
 
-``.s_stream()`` callback
-^^^^^^^^^^^^^^^^^^^^^^^^
+``.enable_streams()`` and ``.disable_streams()`` callbacks
+^^^^^^^^^^^^^^^^^^^^^^^^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The struct struct v4l2_subdev_video_ops->s_stream() callback is used by the
-receiver driver to control the transmitter driver's streaming state.
+The struct v4l2_subdev_pad_ops->enable_streams() and struct
+v4l2_subdev_pad_ops->disable_streams() callbacks are used by the receiver driver
+to control the transmitter driver's streaming state.
 
 
  CSI-2 transmitter drivers
@@ -127,7 +128,7 @@ Stopping the transmitter
  ^^^^^^^^^^^^^^^^^^^^^^^^
 
  A transmitter stops sending the stream of images as a result of
-calling the ``.s_stream()`` callback. Some transmitters may stop the
+calling the ``.disable_streams()`` callback. Some transmitters may stop the
  stream at a frame boundary whereas others stop immediately,
  effectively leaving the current frame unfinished. The receiver driver
  should not make assumptions either way, but function properly in both
include/media/v4l2-subdev.h +3 -2
index 8daa0929865c..3cc6b4a5935f 100644
@@ -450,8 +450,9 @@ enum v4l2_subdev_pre_streamon_flags {
   *	already started or stopped subdev. Also see call_s_stream wrapper in
   *	v4l2-subdev.c.
   *
- *	New drivers should instead implement &v4l2_subdev_pad_ops.enable_streams
- *	and &v4l2_subdev_pad_ops.disable_streams operations, and use
+ *	This callback is DEPRECATED. New drivers should instead implement
+ *	&v4l2_subdev_pad_ops.enable_streams and
+ *	&v4l2_subdev_pad_ops.disable_streams operations, and use
   *	v4l2_subdev_s_stream_helper for the &v4l2_subdev_video_ops.s_stream
   *	operation to support legacy users.
   *
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#10 lore raw
In reply to Tomi Valkeinen

Moi,

Quoted 22 lines · Tomi Valkeinen
Quoted 21 lines · Sakari Ailus

The scope of the s_stream video operation is now fully supported by {enable,disable}_straems. Explicitly document the s_stream() op as deprecated and update the related documentation.

---
  Documentation/driver-api/media/camera-sensor.rst |  8 ++++----
  Documentation/driver-api/media/tx-rx.rst         | 11 ++++++-----
  include/media/v4l2-subdev.h                      |  5 +++--
  3 files changed, 13 insertions(+), 11 deletions(-)
Documentation/driver-api/media/camera-sensor.rst +0 -2
index b4920b34cebc..c290833165e6 100644
@@ -81,10 +81,10 @@ restart when the system is resumed. This requires coordination between the
  camera sensor and the rest of the camera pipeline. Bridge drivers are
  responsible for this coordination, and instruct camera sensors to stop and
  restart streaming by calling the appropriate subdev operations
-(``.s_stream()``, ``.enable_streams()`` or ``.disable_streams()``). Camera
-sensor drivers shall therefore **not** keep track of the streaming state to
Quoted 8 lines

Documentation/driver-api/media/camera-sensor.rst restart when the system is resumed. This requires coordination between the · line 84

Quoted 3 lines
Documentation/driver-api/media/camera-sensor.rst +1 -2
-stop streaming in the PM suspend handler and restart it in the resume handler.
-Drivers should in general not implement the system PM handlers.
+(``.enable_streams()`` or ``.disable_streams()``). Camera sensor drivers shall

I didn't go through the docs, but I think we need to make it clear somewhere that v4l2_subdev_enable_streams() and v4l2_subdev_disable_streams() _must_ be used to enable/disable the streaming in the source subdevice, and the related subdev callbacks must not be called directly.

It was in the header but not in tx-rx.rst. I added it there for v2.

Quoted 4 lines

Also, v4l2_subdev_enable_streams() and v4l2_subdev_disable_streams() kernel doc doesn't seem to clarify that if the driver using those functions does not support streams, it should use BIT_ULL(1) as the streams_mask parameter.

BIT_ULL(0)?

I'll add that, too.

Signature · 3 lines
Terveisin,

Sakari Ailus