Lines Matching +full:sub +full:- +full:module
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
97 unique name and set the module owner. This is done for you if you use the
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);
132 sub-devices. The driver is still responsible for validating the correctness
133 of the format configuration between sub-devices and video nodes.
161 run-time bridge-subdevice interaction is in both cases the same.
169 This can fail if the subdev module disappeared before it could be registered.
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 Afterwards the subdev module can be unloaded and
183 :c:type:`sd <v4l2_subdev>`->dev == ``NULL``.
189 the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
231 .. code-block:: c
233 err = sd->ops->core->g_std(sd, &norm);
237 .. code-block:: c
241 The macro will do the right ``NULL`` pointer checks and returns ``-ENODEV``
242 if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either
243 :c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the act…
244 :c:type:`sd <v4l2_subdev>`->ops->core->g_std ops.
246 It is also possible to call all or a subset of the sub-devices:
248 .. code-block:: c
255 .. code-block:: c
259 Any error except ``-ENOIOCTLCMD`` will exit the loop with that error. If no
260 errors (except ``-ENOIOCTLCMD``) occurred, then 0 is returned.
263 called. If non-zero, then only those whose group ID match that value will
265 :c:type:`sd <v4l2_subdev>`->grp_id to whatever value it wants (it's 0 by
266 default). This value is owned by the bridge driver and the sub-device driver
277 If the sub-device needs to notify its v4l2_device parent of an event, then
279 whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not.
282 V4L2 sub-device userspace API
283 -----------------------------
288 hardware from applications. For complex devices, finer-grained control of the
293 Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access
294 sub-devices directly. If a sub-device supports direct userspace configuration
297 After registering sub-devices, the :c:type:`v4l2_device` driver can create
298 device nodes for all registered sub-devices marked with
301 automatically removed when sub-devices are unregistered.
315 controls implemented in the sub-device. Depending on the driver, those
325 events generated by the sub-device. Depending on the driver, those
328 Sub-device drivers that want to use events need to set the
330 the sub-device. After registration events can be queued as usual on the
338 All ioctls not in the above list are passed directly to the sub-device
341 Read-only sub-device userspace API
342 ----------------------------------
350 configuration through a read-only API, that does not permit applications to
358 through a read-only API.
360 To create a read-only device node for all the subdevices registered with the
365 sub-device device nodes registered with
372 These ioctls are only allowed on a read-only subdevice device node
373 for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
380 These ioctls are not allowed on a read-only subdevice node.
384 the errno variable is set to ``-EPERM``.
386 I2C sub-device drivers
387 ----------------------
390 ease the use of these drivers (``v4l2-common.h``).
400 .. code-block:: c
409 .. code-block:: c
411 v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
419 .. code-block:: c
429 .. code-block:: c
435 .. code-block:: c
441 when the ``remove()`` callback is called. This will unregister the sub-device
442 from the bridge driver. It is safe to call this even if the sub-device was
455 .. code-block:: c
460 This loads the given module (can be ``NULL`` if no module needs to be loaded)
467 are only used if the previous argument is 0. A non-zero argument means that you
473 the same as the module name. It allows you to specify a chip variant, e.g.
494 V4L2 sub-device functions and data structures
495 ---------------------------------------------
497 .. kernel-doc:: include/media/v4l2-subdev.h