Lines Matching +full:single +full:- +full:link
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
7 Sub-device Interface
14 components as software blocks called sub-devices.
16 V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
18 media entities. Applications will be able to enumerate the sub-devices
22 In addition to make sub-devices discoverable, drivers can also choose to
24 sub-device driver and the V4L2 device driver support this, sub-devices
27 - query, read and write sub-devices controls
29 - subscribe and unsubscribe to events and retrieve them
31 - negotiate image formats on individual pads
33 - inspect and modify internal data routing between pads of the same entity
35 Sub-device character device nodes, conventionally named
36 ``/dev/v4l-subdev*``, use major number 81.
38 Drivers may opt to limit the sub-device character devices to only expose
39 operations that do not modify the device state. In such a case the sub-devices
40 are referred to as ``read-only`` in the rest of this documentation, and the
47 Most V4L2 controls are implemented by sub-device hardware. Drivers
49 Applications can control all sub-devices through a single interface.
56 single device, all but one of the identical controls are hidden.
58 Applications can access those hidden controls through the sub-device
62 sub-device.
71 V4L2 sub-devices can notify applications of events as described in
74 the sub-device. Depending on the driver, those events might also be
78 .. _pad-level-formats:
80 Pad-level Formats
85 Pad-level formats are only applicable to very complex devices that
86 need to expose low-level format configuration to user space. Generic
104 :ref:`pipeline-scaling`, where image scaling can be performed on both
108 .. _pipeline-scaling:
110 .. kernel-figure:: pipeline.dot
126 Drivers that implement the :ref:`media API <media-controller-intro>`
127 can expose pad-level image format configuration to applications. When
131 negotiate formats on a per-pad basis.
139 Pad-level image format configuration support can be tested by calling
141 0. If the driver returns an ``EINVAL`` error code pad-level format
142 configuration is not supported by the sub-device.
146 ------------------
165 the sub-device file handles. A
167 the last try format set *on the same sub-device file handle*. Several
168 applications querying the same sub-device at the same time will thus not
182 to an :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` call as-is
186 Drivers automatically propagate formats inside sub-devices. When a try
188 the same sub-device can be modified by the driver. Drivers are free to
192 - Formats should be propagated from sink pads to source pads. Modifying
196 - Sub-devices that scale frames using variable scaling factors should
202 propagating them from one sub-device file handle to another.
203 Applications must then take care to configure both ends of every link
205 a link are guaranteed to be compatible. Drivers are free to accept
208 :ref:`sample-pipeline-config` shows a sample configuration sequence
209 for the pipeline described in :ref:`pipeline-scaling` (table columns
221 .. _sample-pipeline-config:
223 .. flat-table:: Sample Pipeline Configuration
224 :header-rows: 1
225 :stub-columns: 0
228 * -
229 - Sensor/0
232 - Frontend/0
235 - Frontend/1
238 - Scaler/0
241 - Scaler/0
244 - Scaler/1
247 * - Initial state
248 - 2048x1536
251 - (default)
252 - (default)
253 - (default)
254 - (default)
255 - (default)
256 * - Configure frontend sink format
257 - 2048x1536
260 - *2048x1536*
263 - *2046x1534*
266 - (default)
267 - (default)
268 - (default)
269 * - Configure scaler sink format
270 - 2048x1536
273 - 2048x1536
276 - 2046x1534
279 - *2046x1534*
282 - *0,0/2046x1534*
283 - *2046x1534*
286 * - Configure scaler sink compose selection
287 - 2048x1536
290 - 2048x1536
293 - 2046x1534
296 - 2046x1534
299 - *0,0/1280x960*
300 - *1280x960*
335 be applied as-is by the driver without being modified.
338 .. _v4l2-subdev-selections:
341 ---------------------------------------------
343 Many sub-devices support cropping frames on their input or output pads
355 selection targets :ref:`v4l2-selections-common`.
358 The pad format represents the image size as received by the sub-device
360 represents the sub-image that will be transmitted further inside the
361 sub-device for processing.
385 the image size either up or down. :ref:`v4l2-selection-flags`
389 --------------------------
406 pixel array is not rectangular but cross-shaped or round. The maximum
410 .. _format-propagation:
413 ---------------------------------------------
426 rectangle, which refers to the sink compose bounds rectangle --- if it
457 .. _subdev-image-processing-crop:
459 .. kernel-figure:: subdev-image-processing-crop.svg
460 :alt: subdev-image-processing-crop.svg
467 pad. Now the actual crop rectangle can be set on the sink pad --- the
474 .. _subdev-image-processing-scaling-multi-source:
476 .. kernel-figure:: subdev-image-processing-scaling-multi-source.svg
477 :alt: subdev-image-processing-scaling-multi-source.svg
490 .. _subdev-image-processing-full:
492 .. kernel-figure:: subdev-image-processing-full.svg
493 :alt: subdev-image-processing-full.svg
508 subdev-formats
510 .. _subdev-routing:
515 Simple V4L2 sub-devices do not support multiple, unrelated video streams,
516 and only a single stream can pass through a media link and a media pad.
518 single stream. A subdev can do stream processing and split a stream into
520 subdev are still a single stream per pad.
522 Some hardware, e.g. MIPI CSI-2, support multiplexed streams, that is, multiple
524 link connecting a transmitter source pad with a sink pad on the receiver. For
527 by a media link which connects the single sensor's source pad with the receiver
528 sink pad. The stream-aware receiver will de-multiplex the streams received on
533 non-multiplexed subdev drivers. However, if the driver at the sink end of a link
538 ---------------------
542 receiver and demultiplexer in a SoC). Each media link carries all the enabled
543 streams from one end of the link to the other, and sub-devices have routing
547 A stream ID is a media pad-local identifier for a stream. Streams IDs of
548 the same stream must be equal on both ends of a link. In other words,
550 link, but another stream ID can be used for the same stream at the other side
551 of the sub-device.
554 sub-device and a (pad, stream) pair. For sub-devices that do not support
558 -----------------------------------------------------------
560 The addition of streams to the V4L2 sub-device interface moves the sub-device
564 the same as without streams (see :ref:`format-propagation`).
566 Instead of the sub-device wide merging of streams from all sink pads
570 stream on a source pad, however, only a single route is allowed.
577 ------------------------------
579 Different kinds of sub-devices have differing behaviour for route activation,
592 respect to routing. Typically any route between the sub-device's sink and source
595 and user-created routes are fully replaced when ``VIDIOC_SUBDEV_S_ROUTING`` is
596 called on the sub-device. Such newly created routes have the device's default
600 -------------------
602 The configuration of the streams is done individually for each sub-device and
603 the validity of the streams between sub-devices is validated when the pipeline
608 1. Set up links. Connect the pads between sub-devices using the
612 routing table for the sub-device using :ref:`VIDIOC_SUBDEV_S_ROUTING
614 reset formats and selections in the sub-device to default values.
617 configured separately as documented for plain sub-devices in
618 :ref:`format-propagation`. The stream ID is set to the same stream ID
623 ---------------------------------
627 - Two identical sensors (Sensor A and Sensor B). Each sensor has a single source
630 - Multiplexer bridge (Bridge). The bridge has two sink pads, connected to the
633 - Receiver in the SoC (Receiver). The receiver has a single sink pad (pad 0),
634 connected to the bridge, and two source pads (pads 1-2), going to the DMA
637 - DMA Engines in the SoC (DMA Engine), one for each stream. Each DMA engine is
638 connected to a single source pad in the receiver.
640 The sensors, the bridge and the receiver are modeled as V4L2 sub-devices,
641 exposed to userspace via /dev/v4l-subdevX device nodes. The DMA engines are
648 not differ from normal non-multiplexed media controller setup.
652 .. flat-table:: Bridge routing table
653 :header-rows: 1
655 * - Sink Pad/Stream
656 - Source Pad/Stream
657 - Routing Flags
658 - Comments
659 * - 0/0
660 - 2/0
661 - V4L2_SUBDEV_ROUTE_FL_ACTIVE
662 - Pixel data stream from Sensor A
663 * - 1/0
664 - 2/1
665 - V4L2_SUBDEV_ROUTE_FL_ACTIVE
666 - Pixel data stream from Sensor B
668 .. flat-table:: Receiver routing table
669 :header-rows: 1
671 * - Sink Pad/Stream
672 - Source Pad/Stream
673 - Routing Flags
674 - Comments
675 * - 0/0
676 - 1/0
677 - V4L2_SUBDEV_ROUTE_FL_ACTIVE
678 - Pixel data stream from Sensor A
679 * - 0/1
680 - 2/0
681 - V4L2_SUBDEV_ROUTE_FL_ACTIVE
682 - Pixel data stream from Sensor B
694 stream endpoint in each sub-device.