[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.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 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(-)

Hi Sakari,

On 9/17/24 17:02, Sakari Ailus wrote:
> 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/

> deprecated and update the related documentation.>
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>

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

> ---
>  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(-)
> 
> diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
> index b4920b34cebc..c290833165e6 100644
> --- a/Documentation/driver-api/media/camera-sensor.rst
> +++ b/Documentation/driver-api/media/camera-sensor.rst
> @@ -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
> diff --git a/Documentation/driver-api/media/tx-rx.rst b/Documentation/driver-api/media/tx-rx.rst
> index 29d66a47b56e..dd09484df1d3 100644
> --- a/Documentation/driver-api/media/tx-rx.rst
> +++ b/Documentation/driver-api/media/tx-rx.rst
> @@ -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
> diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
> index 8daa0929865c..3cc6b4a5935f 100644
> --- a/include/media/v4l2-subdev.h
> +++ b/include/media/v4l2-subdev.h
> @@ -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.
>   *

Hi Benjamin,

On Thu, Sep 19, 2024 at 03:03:27PM +0200, Benjamin Mugnier wrote:
> Hi Sakari,
> 
> On 9/17/24 17:02, Sakari Ailus wrote:
> > 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.

> 
> > deprecated and update the related documentation.>
> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> 
> This is a good opportunity for me to thank you for keeping the
> documentation up to date.

Thanks! :-)