As we begin to add support for systems with Media controller pipelines controlled by more than one device driver, it is essential that we precisely define the responsibilities of each component in the stream control and common practices. Specifically, streaming control is done per sub-device and sub-device drivers themselves are responsible for streaming setup in upstream sub-devices. Signed-off-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx> Acked-by: Niklas Söderlund <niklas.soderlund+renesas@xxxxxxxxxxxx> --- Documentation/media/kapi/v4l2-subdev.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst index e1f0b72..45088ad 100644 --- a/Documentation/media/kapi/v4l2-subdev.rst +++ b/Documentation/media/kapi/v4l2-subdev.rst @@ -262,6 +262,35 @@ is called. After all subdevices have been located the .complete() callback is called. When a subdevice is removed from the system the .unbind() method is called. All three callbacks are optional. +Streaming control on Media controller enabled devices +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Starting and stopping the stream are somewhat complex operations that +often require walking the media graph to enable streaming on +sub-devices which the pipeline consists of. This involves interaction +between multiple drivers, sometimes more than two. + +The ``.s_stream()`` op in :c:type:`v4l2_subdev_video_ops` is responsible +for starting and stopping the stream on the sub-device it is called +on. A device driver is only responsible for calling the ``.s_stream()`` ops +of the adjacent sub-devices that are connected to its sink pads +through an enabled link. A driver may not call ``.s_stream()`` op +of any other sub-device further up in the pipeline, for instance. + +This means that a sub-device driver is thus in direct control of +whether the upstream sub-devices start (or stop) streaming before or +after the sub-device itself is set up for streaming. + +.. note:: + + As the ``.s_stream()`` callback is called recursively through the + sub-devices along the pipeline, it is important to keep the + recursion as short as possible. To this end, drivers are encouraged + to avoid recursively calling ``.s_stream()`` internally to reduce + stack usage. Instead, the ``.s_stream()`` op of the directly + connected sub-devices should come from the callback through which + the driver was first called. + V4L2 sub-device userspace API ----------------------------- -- 2.7.4
