Skip to contentSkip to conversation

Update streaming related documentation

PATCH Superseded Sakari Ailus 4 participants 8 messages Sep 17, 2024 – Sep 20, 2024

Subsystems (2)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Sakari Ailus

author maintainer
#0 lore raw

v2 cover Update streaming related documentation

Hi folks,

This set updates streaming starting and stopping related documentation.

since v1:

- Document the use of v4l2_subdev_{en,dis}able_streams() and setting the streams_mask for drivers that do not support streams.

Sakari Ailus (3):
media: Documentation: Deprecate s_stream video op, update docs
media: Documentation: Update {enable,disable}_streams documentation
media: Documentation: Improve v4l2_subdev_{en,dis}able_streams
documentation

 .../driver-api/media/camera-sensor.rst          |  8 ++++----
 Documentation/driver-api/media/tx-rx.rst        | 13 ++++++++-----
 include/media/v4l2-subdev.h                     | 17 +++++++++++++++--
 3 files changed, 27 insertions(+), 11 deletions(-)
Signature · 1 line
2.39.5
author maintainer
#1 lore raw

PATCH v2 1/3 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         | 13 ++++++++-----
 include/media/v4l2-subdev.h                      |  5 +++--
 3 files changed, 15 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 +8 -5
index 29d66a47b56e..dd09484df1d3 100644
@@ -49,11 +49,14 @@ 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. These callbacks may not be
+called directly, but by using ``v4l2_subdev_enable_streams()`` and
+``v4l2_subdev_disable_streams()``.
 
 
 CSI-2 transmitter drivers
@@ -127,7 +130,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
#2 lore raw

Re: [PATCH v2 1/3] media: Documentation: Deprecate s_stream video op, update docs

Hi Sakari,

Quoted 2 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

s/straems/streams/

Quoted 2 lines

deprecated and update the related documentation.>

This is a good opportunity for me to thank you for keeping the documentation up to date.

Quoted 73 lines
---
 Documentation/driver-api/media/camera-sensor.rst |  8 ++++----
 Documentation/driver-api/media/tx-rx.rst         | 13 ++++++++-----
 include/media/v4l2-subdev.h                      |  5 +++--
 3 files changed, 15 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 +8 -5
index 29d66a47b56e..dd09484df1d3 100644
@@ -49,11 +49,14 @@ 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. These callbacks may not be
+called directly, but by using ``v4l2_subdev_enable_streams()`` and
+``v4l2_subdev_disable_streams()``.
 
 
 CSI-2 transmitter drivers
@@ -127,7 +130,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,

Benjamin
#3 lore raw

Re: [PATCH v2 1/3] media: Documentation: Deprecate s_stream video op, update docs

Hi Benjamin,

Quoted 7 lines · Benjamin Mugnier

Hi Sakari,

Quoted 2 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

s/straems/streams/

Fixed in v3.

Quoted 6 lines
Quoted 3 lines

deprecated and update the related documentation.>

This is a good opportunity for me to thank you for keeping the documentation up to date.

Thanks! :-)

Signature · 3 lines
Kind regards,

Sakari Ailus
author maintainer
#4 lore raw

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

In reply to 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.

---
 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
author maintainer
#5 lore raw

PATCH v2 3/3 media: Documentation: Improve v4l2_subdev_{en,dis}able_streams documentation

In reply to Sakari Ailus

Document that callers of v4l2_subdev_{en,dis}able_streams() need to set the mask to BIT_ULL(0).

---
 include/media/v4l2-subdev.h | 4 ++++
 1 file changed, 4 insertions(+)
include/media/v4l2-subdev.h +4 -0
index 67a6e6ec58b8..6f207b9bc459 100644
@@ -1685,6 +1685,8 @@ int v4l2_subdev_routing_validate(struct v4l2_subdev *sd,
  * function implements a best-effort compatibility by calling the .s_stream()
  * operation, limited to subdevs that have a single source pad.
  *
+ * Drivers that are not stream-aware shall set @streams_mask to BIT_ULL(0).
+ *
  * Return:
  * * 0: Success
  * * -EALREADY: One of the streams in streams_mask is already enabled
@@ -1715,6 +1717,8 @@ int v4l2_subdev_enable_streams(struct v4l2_subdev *sd, u32 pad,
  * function implements a best-effort compatibility by calling the .s_stream()
  * operation, limited to subdevs that have a single source pad.
  *
+ * Drivers that are not stream-aware shall set @streams_mask to BIT_ULL(0).
+ *
  * Return:
  * * 0: Success
  * * -EALREADY: One of the streams in streams_mask is not enabled
Signature · 1 line
2.39.5
Reviewed-by on the v2 series
#6 lore raw
In reply to Sakari Ailus
Quoted 15 lines · Sakari Ailus

Hi folks,

This set updates streaming starting and stopping related documentation.

since v1:

- Document the use of v4l2_subdev_{en,dis}able_streams() and setting the streams_mask for drivers that do not support streams.

Sakari Ailus (3):
media: Documentation: Deprecate s_stream video op, update docs
media: Documentation: Update {enable,disable}_streams documentation
media: Documentation: Improve v4l2_subdev_{en,dis}able_streams
documentation

Quoted 5 lines
  .../driver-api/media/camera-sensor.rst          |  8 ++++----
  Documentation/driver-api/media/tx-rx.rst        | 13 ++++++++-----
  include/media/v4l2-subdev.h                     | 17 +++++++++++++++--
  3 files changed, 27 insertions(+), 11 deletions(-)

Still missing addressing [email protected] comments, but with those fixed:

Tomi

#7 lore raw

Huomenta,

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

Hi folks,

This set updates streaming starting and stopping related documentation.

since v1:

- Document the use of v4l2_subdev_{en,dis}able_streams() and setting the streams_mask for drivers that do not support streams.

Sakari Ailus (3):
media: Documentation: Deprecate s_stream video op, update docs
media: Documentation: Update {enable,disable}_streams documentation
media: Documentation: Improve v4l2_subdev_{en,dis}able_streams
documentation

Quoted 5 lines
  .../driver-api/media/camera-sensor.rst          |  8 ++++----
  Documentation/driver-api/media/tx-rx.rst        | 13 ++++++++-----
  include/media/v4l2-subdev.h                     | 17 +++++++++++++++--
  3 files changed, 27 insertions(+), 11 deletions(-)
Quoted 4 lines

Still missing addressing [email protected] comments, but with those fixed:

Thanks! I'll add these while applying / v4 if needed.

Signature · 3 lines
Terveisin,

Sakari Ailus