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 .. _media-registering-async-subdevs:
186 Registering asynchronous sub-devices
193 the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
200 Drivers must complete all initialization of the sub-device before
202 enabling runtime PM. This is because the sub-device becomes accessible
205 Asynchronous sub-device notifiers
221 Async connection descriptors describe connections to external sub-devices the
223 or ancillary link may be created when the related sub-device becomes
224 available. There may be one or more async connections to a given sub-device but
226 connections are bound as matching async sub-devices are found, one by one.
228 Asynchronous sub-device notifier for sub-devices
231 A driver that registers an asynchronous sub-device may also register an
232 asynchronous notifier. This is called an asynchronous sub-device notifier and the
234 initialised using :c:func:`v4l2_async_subdev_nf_init` instead. A sub-device
236 a path via async sub-devices and notifiers to a notifier that is not an
237 asynchronous sub-device notifier.
239 Asynchronous sub-device registration helper for camera sensor drivers
245 firmware. The notifier for the sub-device is unregistered and cleaned up with
246 the async sub-device, using :c:func:`v4l2_async_unregister_subdev`.
248 Asynchronous sub-device notifier example
252 :c:type:`v4l2_async_connection` embedded in a driver-specific struct. The &struct
255 .. code-block:: c
274 Asynchronous sub-device notifier callbacks
283 Drivers can store any type of custom data in their driver-specific
301 .. code-block:: c
303 err = sd->ops->core->g_std(sd, &norm);
307 .. code-block:: c
311 The macro will do the right ``NULL`` pointer checks and returns ``-ENODEV``
312 if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either
313 :c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the act…
314 :c:type:`sd <v4l2_subdev>`->ops->core->g_std ops.
316 It is also possible to call all or a subset of the sub-devices:
318 .. code-block:: c
325 .. code-block:: c
329 Any error except ``-ENOIOCTLCMD`` will exit the loop with that error. If no
330 errors (except ``-ENOIOCTLCMD``) occurred, then 0 is returned.
332 The second argument to both calls is a group ID. If 0, then all subdevs are
333 called. If non-zero, then only those whose group ID match that value will
335 :c:type:`sd <v4l2_subdev>`->grp_id to whatever value it wants (it's 0 by
336 default). This value is owned by the bridge driver and the sub-device driver
339 The group ID gives the bridge driver more control how callbacks are called.
342 user want to change the volume. You can set the group ID for that subdev to
343 e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
347 If the sub-device needs to notify its v4l2_device parent of an event, then
349 whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not.
352 V4L2 sub-device userspace API
353 -----------------------------
358 hardware from applications. For complex devices, finer-grained control of the
363 Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access
364 sub-devices directly. If a sub-device supports direct userspace configuration
367 After registering sub-devices, the :c:type:`v4l2_device` driver can create
368 device nodes for all registered sub-devices marked with
371 automatically removed when sub-devices are unregistered.
385 controls implemented in the sub-device. Depending on the driver, those
395 events generated by the sub-device. Depending on the driver, those
398 Sub-device drivers that want to use events need to set the
400 the sub-device. After registration events can be queued as usual on the
408 All ioctls not in the above list are passed directly to the sub-device
411 Read-only sub-device userspace API
412 ----------------------------------
420 configuration through a read-only API, that does not permit applications to
428 through a read-only API.
430 To create a read-only device node for all the subdevices registered with the
435 sub-device device nodes registered with
442 These ioctls are only allowed on a read-only subdevice device node
443 for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
450 These ioctls are not allowed on a read-only subdevice node.
454 the errno variable is set to ``-EPERM``.
456 I2C sub-device drivers
457 ----------------------
460 ease the use of these drivers (``v4l2-common.h``).
470 .. code-block:: c
479 .. code-block:: c
481 v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
489 .. code-block:: c
499 .. code-block:: c
505 .. code-block:: c
511 when the ``remove()`` callback is called. This will unregister the sub-device
512 from the bridge driver. It is safe to call this even if the sub-device was
525 .. code-block:: c
537 are only used if the previous argument is 0. A non-zero argument means that you
565 -------------------------------------
579 device configuration, is stored in the sub-device itself as part of
584 Sub-device drivers can opt-in and use state to manage their active configuration
586 before registering the sub-device. They must also call v4l2_subdev_cleanup()
587 to release all the allocated resources before unregistering the sub-device.
592 V4L2 sub-device operations that use both the :ref:`ACTIVE and TRY formats
593 <v4l2-subdev-format-whence>` receive the correct state to operate on through
601 calling :c:func:`v4l2_subdev_lock_and_get_active_state()`. The sub-device active
626 .. code-block:: c
628 sd->ctrl_handler->lock = &priv->mutex;
629 sd->state_lock = &priv->mutex;
634 ----------------------------------------------------
641 V4L2 sub-device functions and data structures
642 ---------------------------------------------
644 .. kernel-doc:: include/media/v4l2-subdev.h