Lines Matching +full:sub +full:- +full:bus
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
6 Sub-device Interface
13 components as software blocks called sub-devices.
15 V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
17 media entities. Applications will be able to enumerate the sub-devices
21 In addition to make sub-devices discoverable, drivers can also choose to
23 sub-device driver and the V4L2 device driver support this, sub-devices
26 - query, read and write sub-devices controls
28 - subscribe and unsubscribe to events and retrieve them
30 - negotiate image formats on individual pads
32 - inspect and modify internal data routing between pads of the same entity
34 Sub-device character device nodes, conventionally named
35 ``/dev/v4l-subdev*``, use major number 81.
37 Drivers may opt to limit the sub-device character devices to only expose
38 operations that do not modify the device state. In such a case the sub-devices
39 are referred to as ``read-only`` in the rest of this documentation, and the
46 Most V4L2 controls are implemented by sub-device hardware. Drivers
48 Applications can control all sub-devices through a single interface.
57 Applications can access those hidden controls through the sub-device
61 sub-device.
70 V4L2 sub-devices can notify applications of events as described in
73 the sub-device. Depending on the driver, those events might also be
77 .. _pad-level-formats:
79 Pad-level Formats
84 Pad-level formats are only applicable to very complex devices that
85 need to expose low-level format configuration to user space. Generic
92 combination of media bus data format, frame width and frame height.
103 :ref:`pipeline-scaling`, where image scaling can be performed on both
107 .. _pipeline-scaling:
109 .. kernel-figure:: pipeline.dot
125 Drivers that implement the :ref:`media API <media-controller-intro>`
126 can expose pad-level image format configuration to applications. When
130 negotiate formats on a per-pad basis.
138 Pad-level image format configuration support can be tested by calling
140 0. If the driver returns an ``EINVAL`` error code pad-level format
141 configuration is not supported by the sub-device.
145 ------------------
164 the sub-device file handles. A
166 the last try format set *on the same sub-device file handle*. Several
167 applications querying the same sub-device at the same time will thus not
181 to an :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` call as-is
185 Drivers automatically propagate formats inside sub-devices. When a try
187 the same sub-device can be modified by the driver. Drivers are free to
191 - Formats should be propagated from sink pads to source pads. Modifying
195 - Sub-devices that scale frames using variable scaling factors should
201 propagating them from one sub-device file handle to another.
207 :ref:`sample-pipeline-config` shows a sample configuration sequence
208 for the pipeline described in :ref:`pipeline-scaling` (table columns
220 .. _sample-pipeline-config:
222 .. flat-table:: Sample Pipeline Configuration
223 :header-rows: 1
224 :stub-columns: 0
227 * -
228 - Sensor/0
231 - Frontend/0
234 - Frontend/1
237 - Scaler/0
240 - Scaler/0
243 - Scaler/1
246 * - Initial state
247 - 2048x1536
250 - (default)
251 - (default)
252 - (default)
253 - (default)
254 - (default)
255 * - Configure frontend sink format
256 - 2048x1536
259 - *2048x1536*
262 - *2046x1534*
265 - (default)
266 - (default)
267 - (default)
268 * - Configure scaler sink format
269 - 2048x1536
272 - 2048x1536
275 - 2046x1534
278 - *2046x1534*
281 - *0,0/2046x1534*
282 - *2046x1534*
285 * - Configure scaler sink compose selection
286 - 2048x1536
289 - 2048x1536
292 - 2046x1534
295 - 2046x1534
298 - *0,0/1280x960*
299 - *1280x960*
308 size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the
313 2048x1536 and its media bus code to V4L2_MBUS_FMT_SGRBG_1X8. The
317 2046x1534 and the media bus code to V4L2_MBUS_FMT_SGRBG_1X8 to
318 match the frontend source size and media bus code. The media bus code
334 be applied as-is by the driver without being modified.
337 .. _v4l2-subdev-selections:
340 ---------------------------------------------
342 Many sub-devices support cropping frames on their input or output pads
354 selection targets :ref:`v4l2-selections-common`.
357 The pad format represents the image size as received by the sub-device
359 represents the sub-image that will be transmitted further inside the
360 sub-device for processing.
384 the image size either up or down. :ref:`v4l2-selection-flags`
388 --------------------------
405 pixel array is not rectangular but cross-shaped or round. The maximum
409 .. _format-propagation:
412 ---------------------------------------------
425 rectangle, which refers to the sink compose bounds rectangle --- if it
456 .. _subdev-image-processing-crop:
458 .. kernel-figure:: subdev-image-processing-crop.svg
459 :alt: subdev-image-processing-crop.svg
465 configure it, the user sets the media bus format on the subdev's sink
466 pad. Now the actual crop rectangle can be set on the sink pad --- the
473 .. _subdev-image-processing-scaling-multi-source:
475 .. kernel-figure:: subdev-image-processing-scaling-multi-source.svg
476 :alt: subdev-image-processing-scaling-multi-source.svg
489 .. _subdev-image-processing-full:
491 .. kernel-figure:: subdev-image-processing-full.svg
492 :alt: subdev-image-processing-full.svg
507 subdev-formats
510 ----------------------------------------------------
512 Simple V4L2 sub-devices do not support multiple, unrelated video streams,
519 Some hardware, e.g. MIPI CSI-2, support multiplexed streams, that is, multiple
520 data streams are transmitted on the same bus, which is represented by a media
523 metadata stream, which are transmitted on the multiplexed data bus, represented
525 sink pad. The stream-aware receiver will de-multiplex the streams received on
530 non-multiplexed subdev drivers, but, of course, require a routing configuration
540 streams from one end of the link to the other, and sub-devices have routing
544 A stream ID is a media pad-local identifier for a stream. Streams IDs of
548 of the sub-device.
551 sub-device and a (pad, stream) pair. For sub-devices that do not support
557 The addition of streams to the V4L2 sub-device interface moves the sub-device
561 the same as without streams (see :ref:`format-propagation`).
563 Instead of the sub-device wide merging of streams from all sink pads
576 The configuration of the streams is done individually for each sub-device and
577 the validity of the streams between sub-devices is validated when the pipeline
582 1) Set up links. Connect the pads between sub-devices using the :ref:`Media
586 setting the routing table for the sub-device using
589 sub-device to default values.
592 are configured separately as documented for plain sub-devices in
593 :ref:`format-propagation`. The stream ID is set to the same stream ID
602 - Two identical sensors (Sensor A and Sensor B). Each sensor has a single source
605 - Multiplexer bridge (Bridge). The bridge has two sink pads, connected to the
608 - Receiver in the SoC (Receiver). The receiver has a single sink pad (pad 0),
609 connected to the bridge, and two source pads (pads 1-2), going to the DMA
612 - DMA Engines in the SoC (DMA Engine), one for each stream. Each DMA engine is
615 The sensors, the bridge and the receiver are modeled as V4L2 sub-devices,
616 exposed to userspace via /dev/v4l-subdevX device nodes. The DMA engines are
623 not differ from normal non-multiplexed media controller setup.
627 .. flat-table:: Bridge routing table
628 :header-rows: 1
630 * - Sink Pad/Stream
631 - Source Pad/Stream
632 - Routing Flags
633 - Comments
634 * - 0/0
635 - 2/0
636 - V4L2_SUBDEV_ROUTE_FL_ACTIVE
637 - Pixel data stream from Sensor A
638 * - 1/0
639 - 2/1
640 - V4L2_SUBDEV_ROUTE_FL_ACTIVE
641 - Pixel data stream from Sensor B
643 .. flat-table:: Receiver routing table
644 :header-rows: 1
646 * - Sink Pad/Stream
647 - Source Pad/Stream
648 - Routing Flags
649 - Comments
650 * - 0/0
651 - 1/0
652 - V4L2_SUBDEV_ROUTE_FL_ACTIVE
653 - Pixel data stream from Sensor A
654 * - 0/1
655 - 2/0
656 - V4L2_SUBDEV_ROUTE_FL_ACTIVE
657 - Pixel data stream from Sensor B
669 stream endpoint in each sub-device.