Lines Matching +full:audio +full:- +full:bridge
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
7 sort of tasks, but most commonly they handle audio and/or video muxing,
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
78 const struct v4l2_subdev_audio_ops *audio;
84 depending on the sub-device. E.g. a video device is unlikely to support the
85 audio ops and vice versa.
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.
142 first (traditional) possibility is to have subdevices registered by bridge
143 drivers. This can be done when the bridge driver has the complete information
147 to SoCs, which pass information about them to bridge drivers, usually in their
151 asynchronously to bridge devices. An example of such a configuration is a Device
153 system independently from the bridge devices, e.g. when subdevices are defined
158 run-time bridge-subdevice interaction is in both cases the same.
160 Registering synchronous sub-devices
163 In the **synchronous** case a device (bridge) driver needs to register the
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
190 the bridge driver availability. The subdevice driver then has to verify whether
193 the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
198 picked up by bridge drivers.
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
208 Bridge drivers in turn have to register a notifier object. This is performed
214 Before registering the notifier, bridge drivers must do two things: first, the
216 bridge drivers can then begin to form a list of async connection descriptors
217 that the bridge device needs for its
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
233 process is similar to that of a bridge driver apart from that the notifier is
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.
333 called. If non-zero, then only those whose group ID match that value will
334 be called. Before a bridge driver registers a subdev it can set
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.
340 For example, there may be multiple audio chips on a board, each capable of
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 -----------------------------
355 Bridge drivers traditionally expose one or multiple video nodes to userspace,
358 hardware from applications. For complex devices, finer-grained control of the
359 device than what the video nodes offer may be required. In those cases, bridge
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 ----------------------------------
414 Bridge drivers that control their connected subdevices through direct calls to
420 configuration through a read-only API, that does not permit applications to
427 such use cases, bridge drivers may expose the subdevice operations to userspace
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
515 You need to do this because when the bridge driver destroys the i2c adapter
523 The bridge driver also has some helper functions it can use:
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