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
258 .. code-block:: c
260 err = sd->ops->core->g_std(sd, &norm);
264 .. code-block:: c
268 The macro will do the right ``NULL`` pointer checks and returns ``-ENODEV``
269 if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either
270 :c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the act…
271 :c:type:`sd <v4l2_subdev>`->ops->core->g_std ops.
273 It is also possible to call all or a subset of the sub-devices:
275 .. code-block:: c
282 .. code-block:: c
286 Any error except ``-ENOIOCTLCMD`` will exit the loop with that error. If no
287 errors (except ``-ENOIOCTLCMD``) occurred, then 0 is returned.
289 The second argument to both calls is a group ID. If 0, then all subdevs are
290 called. If non-zero, then only those whose group ID match that value will
292 :c:type:`sd <v4l2_subdev>`->grp_id to whatever value it wants (it's 0 by
293 default). This value is owned by the bridge driver and the sub-device driver
296 The group ID gives the bridge driver more control how callbacks are called.
299 user want to change the volume. You can set the group ID for that subdev to
300 e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
304 If the sub-device needs to notify its v4l2_device parent of an event, then
306 whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not.
309 V4L2 sub-device userspace API
310 -----------------------------
315 hardware from applications. For complex devices, finer-grained control of the
320 Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access
321 sub-devices directly. If a sub-device supports direct userspace configuration
324 After registering sub-devices, the :c:type:`v4l2_device` driver can create
325 device nodes for all registered sub-devices marked with
328 automatically removed when sub-devices are unregistered.
342 controls implemented in the sub-device. Depending on the driver, those
352 events generated by the sub-device. Depending on the driver, those
355 Sub-device drivers that want to use events need to set the
357 the sub-device. After registration events can be queued as usual on the
365 All ioctls not in the above list are passed directly to the sub-device
368 Read-only sub-device userspace API
369 ----------------------------------
377 configuration through a read-only API, that does not permit applications to
385 through a read-only API.
387 To create a read-only device node for all the subdevices registered with the
392 sub-device device nodes registered with
399 These ioctls are only allowed on a read-only subdevice device node
400 for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
407 These ioctls are not allowed on a read-only subdevice node.
411 the errno variable is set to ``-EPERM``.
413 I2C sub-device drivers
414 ----------------------
417 ease the use of these drivers (``v4l2-common.h``).
427 .. code-block:: c
436 .. code-block:: c
438 v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
446 .. code-block:: c
456 .. code-block:: c
462 .. code-block:: c
468 when the ``remove()`` callback is called. This will unregister the sub-device
469 from the bridge driver. It is safe to call this even if the sub-device was
482 .. code-block:: c
494 are only used if the previous argument is 0. A non-zero argument means that you
521 V4L2 sub-device functions and data structures
522 ---------------------------------------------
524 .. kernel-doc:: include/media/v4l2-subdev.h