On 11/01/2023 13:09, Sakari Ailus wrote:
Document how streams interacts with formats and selections.
Update documentation in respect to what is allowed, in particular streams
are only supported via full routes, source-only routes are not supported
right now.
The centerpiece of the API additions are streams. Albeit routes are
configured via S_ROUTING IOCTL that also declares streams, it is streams
that are accessed through other APIs. Thus refer to streams instead of
routes in documentation.
Signed-off-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx>
---
since v1:
- Address Tomi's comments:
- Fix wrong terms (sink vs. source, others)
- Align subdev, subdevice to sub-device consistently
- Improve wording in a number of places
- Rebase on plain v16 streams set (i.e. not additional patches in between)
- Drop a few redundant sentences
See: <URL:https://lore.kernel.org/linux-media/Y76SpkZTxtPvpXtU@xxxxxxxxxxxxxxxxxxxxxx/T/#me8bb137ec1bc7fb20efe8042be04b40753928f1d>
.../userspace-api/media/v4l/dev-subdev.rst | 74 +++++++++++++------
1 file changed, 51 insertions(+), 23 deletions(-)
diff --git a/Documentation/userspace-api/media/v4l/dev-subdev.rst b/Documentation/userspace-api/media/v4l/dev-subdev.rst
index 7d1b8ebd4e173..cf720a257a9bb 100644
--- a/Documentation/userspace-api/media/v4l/dev-subdev.rst
+++ b/Documentation/userspace-api/media/v4l/dev-subdev.rst
@@ -406,6 +406,8 @@ pixel array is not rectangular but cross-shaped or round. The maximum
size may also be smaller than the BOUNDS rectangle.
+.. _format-propagation:
+
Order of configuration and format propagation
---------------------------------------------
@@ -507,12 +509,12 @@ source pads.
Streams, multiplexed media pads and internal routing
----------------------------------------------------
-Commonly V4L2 subdevices support only separate video streams, that is, only a
-single stream can pass through a media link and a media pad. Thus each pad
-contains a format configuration for that single stream. In some cases a subdev
-can do stream processing and split a stream into two or compose two streams
-into one, but the inputs and outputs for the subdev are still a single stream
-per pad.
+Simple V4L2 subdevices do not support multiple, unrelated video streams,
+and only a single stream can pass through a media link and a media pad.
+Thus each pad contains a format and selection configuration for that
+single stream. A subdev can do stream processing and split a stream into
+two or compose two streams into one, but the inputs and outputs for the
+subdev are still a single stream per pad.
Some hardware, e.g. MIPI CSI-2, support multiplexed streams, that is, multiple
data streams are transmitted on the same bus, which is represented by a media
@@ -539,14 +541,35 @@ streams from one end of the link to the other, and subdevices have routing
tables which describe how the incoming streams from sink pads are routed to the
source pads.
-A stream ID (often just "stream") is a media link-local identifier for a stream.
-In other words, a particular stream ID must exist on both sides of a media
+A stream ID is a media pad-local identifier for a stream. Streams IDs of
+the same stream must be equal on both ends of a link. In other words,
+a particular stream ID must exist on both sides of a media
link, but another stream ID can be used for the same stream at the other side
-of the subdevice.
+of the subdevice. The same stream ID is used to refer to the stream on
+both pads of the link on all ioctls operating on pads.
+
+A stream at a specific point in the media pipeline is identified by the
+sub-devdev and a (pad, stream) pair. For subdevices that do not support
"sub-devdev". Also, you have "subdevice" (also in other places in the
text), not "sub-device".
Other than that, looks fine:
Reviewed-by: Tomi Valkeinen <tomi.valkeinen@xxxxxxxxxxxxxxxx>
Tomi
