Lines Matching +full:sub +full:- +full:group
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);
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.
325 The second argument to both calls is a group ID. If 0, then all subdevs are
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
332 The group ID gives the bridge driver more control how callbacks are called.
335 user want to change the volume. You can set the group ID for that subdev to
336 e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
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 -----------------------------
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.
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
401 All ioctls not in the above list are passed directly to the sub-device
404 Read-only sub-device userspace API
405 ----------------------------------
413 configuration through a read-only API, that does not permit applications to
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