Lines Matching +full:a +full:- +full:c

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
17 struct if more state information needs to be stored. Usually there is a
18 low-level device struct (e.g. ``i2c_client``) that contains the device data as
20 data of :c:type:`v4l2_subdev` using :c:func:`v4l2_set_subdevdata`. That makes
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`.
26 a :c:type:`v4l2_subdev` pointer, for other buses you may have to use other
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
32 :c:func:`v4l2_get_subdev_hostdata` and :c:func:`v4l2_set_subdev_hostdata`.
34 From the bridge driver perspective, you load the sub-device module and somehow
35 obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call
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
42 do so many different things and you do not want to end up with a huge ops struct
43 of which only a handful of ops are commonly implemented, the function pointers
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:
92 	:c:func:`v4l2_subdev_init <v4l2_subdev_init>`
93 	(:c:type:`sd <v4l2_subdev>`, &\ :c:type:`ops <v4l2_subdev_ops>`).
96 Afterwards you need to initialize :c:type:`sd <v4l2_subdev>`->name with a
101 :c:type:`media_entity` struct embedded in the :c:type:`v4l2_subdev` struct
102 (entity field) by calling :c:func:`media_entity_pads_init`, if the entity has
105 .. code-block:: c
107 	struct media_pad *pads = &my_sd->pads;
110 	err = media_entity_pads_init(&sd->entity, npads, pads);
116 A reference to the entity will be automatically acquired/released when the
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
126 link_validate field in :c:type:`v4l2_subdev_pad_ops` to provide its own link
130 between sub-devices and video nodes.
133 :c:func:`v4l2_subdev_link_validate_default` is used instead. This function
151 asynchronously to bridge devices. An example of such a configuration is a Device
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
164 :c:type:`v4l2_subdev` with the v4l2_device:
166 	:c:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>`
167 	(:c:type:`v4l2_dev <v4l2_device>`, :c:type:`sd <v4l2_subdev>`).
170 After this function was called successfully the subdev->dev field points to
171 the :c:type:`v4l2_device`.
173 If the v4l2_device parent device has a non-NULL mdev field, the sub-device
176 You can unregister a sub-device using:
178 	:c:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>`
179 	(:c:type:`sd <v4l2_subdev>`).
182 :c:type:`sd <v4l2_subdev>`->dev == ``NULL``.
184 .. _media-registering-async-subdevs:
186 Registering asynchronous sub-devices
191 all the requirements for a successful probing are satisfied. This can include a
192 check for a master clock availability. If any of the conditions aren't satisfied
193 the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
195 the :c:func:`v4l2_async_register_subdev` function. Unregistration is
196 performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
197 registered this way are stored in a global list of subdevices, ready to be
200 Drivers must complete all initialization of the sub-device before
201 registering it using :c:func:`v4l2_async_register_subdev`, including
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
209 using the :c:func:`v4l2_async_nf_register` call. To unregister the notifier the
210 driver has to call :c:func:`v4l2_async_nf_unregister`. Before releasing memory
212 :c:func:`v4l2_async_nf_cleanup`.
215 notifier must be initialized using the :c:func:`v4l2_async_nf_init`.  Second,
216 bridge drivers can then begin to form a list of async connection descriptors
218 operation. :c:func:`v4l2_async_nf_add_fwnode`,
219 :c:func:`v4l2_async_nf_add_fwnode_remote` and :c:func:`v4l2_async_nf_add_i2c`
221 Async connection descriptors describe connections to external sub-devices the
222 drivers for which are not yet probed. Based on an async connection, a media data
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
242 :c:func:`v4l2_async_register_subdev_sensor` is a helper function for sensor
243 drivers registering their own async connection, but it also registers a notifier
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
253 :c:type:`v4l2_async_connection` shall be the first member of this struct:
255 .. code-block:: c
274 Asynchronous sub-device notifier callbacks
278 registered subdevices to them. If a match is detected the ``.bound()`` notifier
280 callback is called. When a connection is removed from the system the
283 Drivers can store any type of custom data in their driver-specific
284 :c:type:`v4l2_async_connection` wrapper. If any of that data requires special
287 :c:type:`v4l2_async_connection`.
292 The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and
293 does not contain any knowledge about the underlying hardware. So a driver might
294 contain several subdevs that use an I2C bus, but also a subdev that is
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
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
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 -----------------------------
356 and control subdevices through the :c:type:`v4l2_subdev_ops` operations in
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
370 :c:func:`v4l2_device_register_subdev_nodes`. Those device nodes will be
371 automatically removed when sub-devices are unregistered.
373 The device node handles a subset of the V4L2 API.
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
399 	``V4L2_SUBDEV_FL_HAS_EVENTS`` :c:type:`v4l2_subdev`.flags before registering
400 	the sub-device. After registration events can be queued as usual on the
401 	:c:type:`v4l2_subdev`.devnode device node.
408 	All ioctls not in the above list are passed directly to the sub-device
411 Read-only sub-device userspace API
412 ----------------------------------
415 the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
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
431 ``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
432 :c:func:`v4l2_device_register_ro_subdev_nodes`.
435 sub-device device nodes registered with
436 :c:func:`v4l2_device_register_ro_subdev_nodes`.
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.
453 ``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
454 the errno variable is set to ``-EPERM``.
456 I2C sub-device drivers
457 ----------------------
460 ease the use of these drivers (``v4l2-common.h``).
462 The recommended method of adding :c:type:`v4l2_subdev` support to an I2C driver
463 is to embed the :c:type:`v4l2_subdev` struct into the state struct that is
465 struct and in that case you can just create a :c:type:`v4l2_subdev` directly.
467 A typical state struct would look like this (where 'chipname' is replaced by
470 .. code-block:: c
477 Initialize the :c:type:`v4l2_subdev` struct as follows:
479 .. code-block:: c
481 	v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
483 This function will fill in all the fields of :c:type:`v4l2_subdev` ensure that
484 the :c:type:`v4l2_subdev` and i2c_client both point to one another.
486 You should also add a helper inline function to go from a :c:type:`v4l2_subdev`
487 pointer to a chipname_state struct:
489 .. code-block:: c
496 Use this to go from the :c:type:`v4l2_subdev` struct to the ``i2c_client``
499 .. code-block:: c
503 And this to go from an ``i2c_client`` to a :c:type:`v4l2_subdev` struct:
505 .. code-block:: c
510 :c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`)
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
519 :c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`)
525 .. code-block:: c
531 and calls :c:func:`i2c_new_client_device` with the given ``i2c_adapter`` and
535 You can also use the last argument of :c:func:`v4l2_i2c_new_subdev` to pass
537 are only used if the previous argument is 0. A non-zero argument means that you
542 Note that the chipid you pass to :c:func:`v4l2_i2c_new_subdev` is usually
543 the same as the module name. It allows you to specify a chip variant, e.g.
545 The use of chipid is something that needs to be looked at more closely at a
552 :c:func:`v4l2_i2c_new_subdev_board` uses an :c:type:`i2c_board_info` struct
559 The :c:func:`v4l2_i2c_new_subdev` function will call
560 :c:func:`v4l2_i2c_new_subdev_board`, internally filling a
561 :c:type:`i2c_board_info` structure using the ``client_type`` and the
565 -------------------------------------
572 In addition to the active configuration, each subdev file handle has a struct
576 To simplify the subdev drivers the V4L2 subdev API now optionally supports a
578 :c:type:`v4l2_subdev_state`. One instance of state, which contains the active
579 device configuration, is stored in the sub-device itself as part of
580 the :c:type:`v4l2_subdev` structure, while the core associates a try state to
584 Sub-device drivers can opt-in and use state to manage their active configuration
585 by initializing the subdevice state with a call to v4l2_subdev_init_finalize()
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.
588 The core automatically allocates and initializes a state for each open file
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
595 caller by calling :c:func:`v4l2_subdev_lock_state()` and
596 :c:func:`v4l2_subdev_unlock_state()`. The caller can do so by calling the subdev
597 operation through the :c:func:`v4l2_subdev_call_state_active()` macro.
599 Operations that do not receive a state parameter implicitly operate on the
601 calling :c:func:`v4l2_subdev_lock_and_get_active_state()`. The sub-device active
602 state must equally be released by calling :c:func:`v4l2_subdev_unlock_state()`.
604 Drivers must never manually access the state stored in the :c:type:`v4l2_subdev`
608 operations, many existing device drivers pass a NULL state when calling
609 operations with :c:func:`v4l2_subdev_call()`. This legacy construct causes
611 as they expect to receive the appropriate state as a parameter. To help the
612 conversion of subdevice drivers to a managed active state without having to
615 the callee's active state with :c:func:`v4l2_subdev_lock_and_get_active_state()`,
620 future these parts should be combined into a single state. For the time being
621 we need a way to handle the locking for these parts. This can be accomplished
622 by sharing a lock. The v4l2_ctrl_handler already supports this via its 'lock'
626 .. code-block:: c
628 	sd->ctrl_handler->lock = &priv->mutex;
629 	sd->state_lock = &priv->mutex;
634 ----------------------------------------------------
636 A subdevice driver can implement support for multiplexed streams by setting
641 V4L2 sub-device functions and data structures
642 ---------------------------------------------
644 .. kernel-doc:: include/media/v4l2-subdev.h