Documentation/userspace-api/media/v4l/dev-subdev.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/media/v4l/dev-subdev.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/media/v4l/dev-subdev.rst
Extension
.rst
Size
27356 bytes
Lines
694
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _subdev:

********************
Sub-device Interface
********************

The complex nature of V4L2 devices, where hardware is often made of
several integrated circuits that need to interact with each other in a
controlled way, leads to complex V4L2 drivers. The drivers usually
reflect the hardware model in software, and model the different hardware
components as software blocks called sub-devices.

V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
implements the media device API, they will automatically inherit from
media entities. Applications will be able to enumerate the sub-devices
and discover the hardware topology using the media entities, pads and
links enumeration API.

In addition to make sub-devices discoverable, drivers can also choose to
make them directly configurable by applications. When both the
sub-device driver and the V4L2 device driver support this, sub-devices
will feature a character device node on which ioctls can be called to

-  query, read and write sub-devices controls

-  subscribe and unsubscribe to events and retrieve them

-  negotiate image formats on individual pads

-  inspect and modify internal data routing between pads of the same entity

Sub-device character device nodes, conventionally named
``/dev/v4l-subdev*``, use major number 81.

Drivers may opt to limit the sub-device character devices to only expose
operations that do not modify the device state. In such a case the sub-devices
are referred to as ``read-only`` in the rest of this documentation, and the
related restrictions are documented in individual ioctls.


Controls
========

Most V4L2 controls are implemented by sub-device hardware. Drivers
usually merge all controls and expose them through video device nodes.
Applications can control all sub-devices through a single interface.

Complex devices sometimes implement the same control in different pieces
of hardware. This situation is common in embedded platforms, where both
sensors and image processing hardware implement identical functions,
such as contrast adjustment, white balance or faulty pixels correction.
As the V4L2 controls API doesn't support several identical controls in a
single device, all but one of the identical controls are hidden.

Applications can access those hidden controls through the sub-device
node with the V4L2 control API described in :ref:`control`. The ioctls
behave identically as when issued on V4L2 device nodes, with the
exception that they deal only with controls implemented in the
sub-device.

Depending on the driver, those controls might also be exposed through
one (or several) V4L2 device nodes.


Events
======

Annotation

Implementation Notes