driver-api/media/v4l2-subdev.rst

1 .. SPDX-License-Identifier: GPL-2.0
3 V4L2 sub-devices
4 ----------------
6 Many drivers need to communicate with sub-devices. These devices can do all
8 encoding or decoding. For webcams common sub-devices are sensors and camera
12 driver with a consistent interface to these sub-devices the
13 :c:type:`v4l2_subdev` struct (v4l2-subdev.h) was created.
15 Each sub-device driver must have a :c:type:`v4l2_subdev` struct. This struct
16 can be stand-alone for simple sub-devices or it might be embedded in a larger
18 low-level device struct (e.g. ``i2c_client``) that contains the device data as
21 it easy to go from a :c:type:`v4l2_subdev` to the actual low-level bus-specific
24 You also need a way to go from the low-level struct to :c:type:`v4l2_subdev`.
29 Bridges might also need to store per-subdev private data, such as a pointer to
30 bridge-specific per-subdev private data. The :c:type:`v4l2_subdev` structure
34 From the bridge driver perspective, you load the sub-device module and somehow
37 Helper functions exist for sub-devices on an I2C bus that do most of this
40 Each :c:type:`v4l2_subdev` contains function pointers that sub-device drivers
41 can implement (or leave ``NULL`` if it is not applicable). Since sub-devices can
46 The top-level ops struct contains pointers to the category ops structs, which
51 .. code-block:: c
84 depending on the sub-device. E.g. a video device is unlikely to support the
90 A sub-device driver initializes the :c:type:`v4l2_subdev` struct using:
96 Afterwards you need to initialize :c:type:`sd <v4l2_subdev>`->name with a
105 .. code-block:: c
107 	struct media_pad *pads = &my_sd->pads;
110 	err = media_entity_pads_init(&sd->entity, npads, pads);
117 subdev device node (if any) is opened/closed.
119 Don't forget to cleanup the media entity before the sub-device is destroyed:
121 .. code-block:: c
123 	media_entity_cleanup(&sd->entity);
125 If a sub-device driver implements sink pads, the subdev driver may set the
130 between sub-devices and video nodes.
158 run-time bridge-subdevice interaction is in both cases the same.
160 Registering synchronous sub-devices
170 After this function was called successfully the subdev->dev field points to
173 If the v4l2_device parent device has a non-NULL mdev field, the sub-device
176 You can unregister a sub-device using:
182 :c:type:`sd <v4l2_subdev>`->dev == ``NULL``.
184 Registering asynchronous sub-devices
191 the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
198 Asynchronous sub-device notifiers
214 Async connection descriptors describe connections to external sub-devices the
216 or ancillary link may be created when the related sub-device becomes
217 available. There may be one or more async connections to a given sub-device but
219 connections are bound as matching async sub-devices are found, one by one.
221 Asynchronous sub-device notifier for sub-devices
224 A driver that registers an asynchronous sub-device may also register an
225 asynchronous notifier. This is called an asynchronous sub-device notifier andthe
227 initialised using :c:func:`v4l2_async_subdev_nf_init` instead. A sub-device
229 a path via async sub-devices and notifiers to a notifier that is not an
230 asynchronous sub-device notifier.
232 Asynchronous sub-device registration helper for camera sensor drivers
238 firmware. The notifier for the sub-device is unregistered and cleaned up with
239 the async sub-device, using :c:func:`v4l2_async_unregister_subdev`.
241 Asynchronous sub-device notifier example
245 :c:type:`v4l2_async_connection` embedded in a driver-specific struct. The &struct
248 .. code-block:: c
267 Asynchronous sub-device notifier callbacks
276 Drivers can store any type of custom data in their driver-specific
294 .. code-block:: c
296 	err = sd->ops->core->g_std(sd, &norm);
300 .. code-block:: c
304 The macro will do the right ``NULL`` pointer checks and returns ``-ENODEV``
305 if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either
306 :c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the act…
307 :c:type:`sd <v4l2_subdev>`->ops->core->g_std ops.
309 It is also possible to call all or a subset of the sub-devices:
311 .. code-block:: c
318 .. code-block:: c
322 Any error except ``-ENOIOCTLCMD`` will exit the loop with that error. If no
323 errors (except ``-ENOIOCTLCMD``) occurred, then 0 is returned.
326 called. If non-zero, then only those whose group ID match that value will
328 :c:type:`sd <v4l2_subdev>`->grp_id to whatever value it wants (it's 0 by
329 default). This value is owned by the bridge driver and the sub-device driver
340 If the sub-device needs to notify its v4l2_device parent of an event, then
342 whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not.
345 V4L2 sub-device userspace API
346 -----------------------------
350 response to video node operations. This hides the complexity of the underlying
351 hardware from applications. For complex devices, finer-grained control of the
356 Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access
357 sub-devices directly. If a sub-device supports direct userspace configuration
360 After registering sub-devices, the :c:type:`v4l2_device` driver can create
361 device nodes for all registered sub-devices marked with
364 automatically removed when sub-devices are unregistered.
366 The device node handles a subset of the V4L2 API.
378 	controls implemented in the sub-device. Depending on the driver, those
388 	events generated by the sub-device. Depending on the driver, those
391 	Sub-device drivers that want to use events need to set the
393 	the sub-device. After registration events can be queued as usual on the
394 	:c:type:`v4l2_subdev`.devnode device node.
401 	All ioctls not in the above list are passed directly to the sub-device
404 Read-only sub-device userspace API
405 ----------------------------------
410 device node and thus do not usually register any.
413 configuration through a read-only API, that does not permit applications to
415 node to inspect them.
421 through a read-only API.
423 To create a read-only device node for all the subdevices registered with the
428 sub-device device nodes registered with
435 	These ioctls are only allowed on a read-only subdevice device node
436 	for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
443 	These ioctls are not allowed on a read-only subdevice node.
447 the errno variable is set to ``-EPERM``.
449 I2C sub-device drivers
450 ----------------------
453 ease the use of these drivers (``v4l2-common.h``).
463 .. code-block:: c
472 .. code-block:: c
474 	v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
482 .. code-block:: c
492 .. code-block:: c
498 .. code-block:: c
504 when the ``remove()`` callback is called. This will unregister the sub-device
505 from the bridge driver. It is safe to call this even if the sub-device was
518 .. code-block:: c
530 are only used if the previous argument is 0. A non-zero argument means that you
558 -------------------------------------
572 device configuration, is stored in the sub-device itself as part of
577 Sub-device drivers can opt-in and use state to manage their active configuration
579 before registering the sub-device. They must also call v4l2_subdev_cleanup()
580 to release all the allocated resources before unregistering the sub-device.
585 V4L2 sub-device operations that use both the :ref:`ACTIVE and TRY formats
586 <v4l2-subdev-format-whence>` receive the correct state to operate on through
594 calling :c:func:`v4l2_subdev_lock_and_get_active_state()`. The sub-device active
619 .. code-block:: c
621 	sd->ctrl_handler->lock = &priv->mutex;
622 	sd->state_lock = &priv->mutex;
627 ----------------------------------------------------
634 V4L2 sub-device functions and data structures
635 ---------------------------------------------
637 .. kernel-doc:: include/media/v4l2-subdev.h