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.
167 After this function was called successfully the subdev->dev field points to
170 If the v4l2_device parent device has a non-NULL mdev field, the sub-device
173 You can unregister a sub-device using:
180 :c:type:`sd <v4l2_subdev>`->dev == ``NULL``.
186 the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
209 registering their async sub-devices with the notifier.
212 sensor drivers registering their own async sub-device, but it also registers a
213 notifier and further registers async sub-devices for lens and flash devices
214 found in firmware. The notifier for the sub-device is unregistered with the
215 async sub-device.
217 These functions allocate an async sub-device descriptor which is of type struct
218 :c:type:`v4l2_async_subdev` embedded in a driver-specific struct. The &struct
221 .. code-block:: c
246 Drivers can store any type of custom data in their driver-specific
264 .. code-block:: c
266 err = sd->ops->core->g_std(sd, &norm);
270 .. code-block:: c
274 The macro will do the right ``NULL`` pointer checks and returns ``-ENODEV``
275 if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either
276 :c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the act…
277 :c:type:`sd <v4l2_subdev>`->ops->core->g_std ops.
279 It is also possible to call all or a subset of the sub-devices:
281 .. code-block:: c
288 .. code-block:: c
292 Any error except ``-ENOIOCTLCMD`` will exit the loop with that error. If no
293 errors (except ``-ENOIOCTLCMD``) occurred, then 0 is returned.
295 The second argument to both calls is a group ID. If 0, then all subdevs are
296 called. If non-zero, then only those whose group ID match that value will
298 :c:type:`sd <v4l2_subdev>`->grp_id to whatever value it wants (it's 0 by
299 default). This value is owned by the bridge driver and the sub-device driver
302 The group ID gives the bridge driver more control how callbacks are called.
305 user want to change the volume. You can set the group ID for that subdev to
306 e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
310 If the sub-device needs to notify its v4l2_device parent of an event, then
312 whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not.
315 V4L2 sub-device userspace API
316 -----------------------------
321 hardware from applications. For complex devices, finer-grained control of the
326 Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access
327 sub-devices directly. If a sub-device supports direct userspace configuration
330 After registering sub-devices, the :c:type:`v4l2_device` driver can create
331 device nodes for all registered sub-devices marked with
334 automatically removed when sub-devices are unregistered.
348 controls implemented in the sub-device. Depending on the driver, those
358 events generated by the sub-device. Depending on the driver, those
361 Sub-device drivers that want to use events need to set the
363 the sub-device. After registration events can be queued as usual on the
371 All ioctls not in the above list are passed directly to the sub-device
374 Read-only sub-device userspace API
375 ----------------------------------
383 configuration through a read-only API, that does not permit applications to
391 through a read-only API.
393 To create a read-only device node for all the subdevices registered with the
398 sub-device device nodes registered with
405 These ioctls are only allowed on a read-only subdevice device node
406 for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
413 These ioctls are not allowed on a read-only subdevice node.
417 the errno variable is set to ``-EPERM``.
419 I2C sub-device drivers
420 ----------------------
423 ease the use of these drivers (``v4l2-common.h``).
433 .. code-block:: c
442 .. code-block:: c
444 v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
452 .. code-block:: c
462 .. code-block:: c
468 .. code-block:: c
474 when the ``remove()`` callback is called. This will unregister the sub-device
475 from the bridge driver. It is safe to call this even if the sub-device was
488 .. code-block:: c
500 are only used if the previous argument is 0. A non-zero argument means that you
528 -------------------------------------
542 device configuration, is stored in the sub-device itself as part of
547 Sub-device drivers can opt-in and use state to manage their active configuration
549 before registering the sub-device. They must also call v4l2_subdev_cleanup()
550 to release all the allocated resources before unregistering the sub-device.
555 V4L2 sub-device operations that use both the :ref:`ACTIVE and TRY formats
556 <v4l2-subdev-format-whence>` receive the correct state to operate on through
564 calling :c:func:`v4l2_subdev_lock_and_get_active_state()`. The sub-device active
589 .. code-block:: c
591 sd->ctrl_handler->lock = &priv->mutex;
592 sd->state_lock = &priv->mutex;
596 V4L2 sub-device functions and data structures
597 ---------------------------------------------
599 .. kernel-doc:: include/media/v4l2-subdev.h