^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) V4L2 sub-devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Many drivers need to communicate with sub-devices. These devices can do all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) sort of tasks, but most commonly they handle audio and/or video muxing,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) encoding or decoding. For webcams common sub-devices are sensors and camera
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) controllers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Usually these are I2C devices, but not necessarily. In order to provide the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) driver with a consistent interface to these sub-devices the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) :c:type:`v4l2_subdev` struct (v4l2-subdev.h) was created.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Each sub-device driver must have a :c:type:`v4l2_subdev` struct. This struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) can be stand-alone for simple sub-devices or it might be embedded in a larger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) struct if more state information needs to be stored. Usually there is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) low-level device struct (e.g. ``i2c_client``) that contains the device data as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) setup by the kernel. It is recommended to store that pointer in the private
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) data of :c:type:`v4l2_subdev` using :c:func:`v4l2_set_subdevdata`. That makes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) it easy to go from a :c:type:`v4l2_subdev` to the actual low-level bus-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) device data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) You also need a way to go from the low-level struct to :c:type:`v4l2_subdev`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) For the common i2c_client struct the i2c_set_clientdata() call is used to store
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) a :c:type:`v4l2_subdev` pointer, for other buses you may have to use other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) methods.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Bridges might also need to store per-subdev private data, such as a pointer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) bridge-specific per-subdev private data. The :c:type:`v4l2_subdev` structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) provides host private data for that purpose that can be accessed with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) :c:func:`v4l2_get_subdev_hostdata` and :c:func:`v4l2_set_subdev_hostdata`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) From the bridge driver perspective, you load the sub-device module and somehow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) ``i2c_get_clientdata()``. For other buses something similar needs to be done.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) Helper functions exist for sub-devices on an I2C bus that do most of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) tricky work for you.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) Each :c:type:`v4l2_subdev` contains function pointers that sub-device drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) can implement (or leave ``NULL`` if it is not applicable). Since sub-devices can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) do so many different things and you do not want to end up with a huge ops struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) of which only a handful of ops are commonly implemented, the function pointers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) are sorted according to category and each category has its own ops struct.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) The top-level ops struct contains pointers to the category ops structs, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) may be NULL if the subdev driver does not support anything from that category.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) It looks like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) struct v4l2_subdev_core_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) int (*log_status)(struct v4l2_subdev *sd);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) int (*init)(struct v4l2_subdev *sd, u32 val);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) struct v4l2_subdev_tuner_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) struct v4l2_subdev_audio_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) struct v4l2_subdev_video_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) struct v4l2_subdev_pad_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) struct v4l2_subdev_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) const struct v4l2_subdev_core_ops *core;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) const struct v4l2_subdev_tuner_ops *tuner;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) const struct v4l2_subdev_audio_ops *audio;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) const struct v4l2_subdev_video_ops *video;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) const struct v4l2_subdev_pad_ops *video;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) The core ops are common to all subdevs, the other categories are implemented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) depending on the sub-device. E.g. a video device is unlikely to support the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) audio ops and vice versa.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) This setup limits the number of function pointers while still making it easy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) to add new ops and categories.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) A sub-device driver initializes the :c:type:`v4l2_subdev` struct using:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) :c:func:`v4l2_subdev_init <v4l2_subdev_init>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) (:c:type:`sd <v4l2_subdev>`, &\ :c:type:`ops <v4l2_subdev_ops>`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) Afterwards you need to initialize :c:type:`sd <v4l2_subdev>`->name with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) unique name and set the module owner. This is done for you if you use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) i2c helper functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) If integration with the media framework is needed, you must initialize the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) :c:type:`media_entity` struct embedded in the :c:type:`v4l2_subdev` struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) (entity field) by calling :c:func:`media_entity_pads_init`, if the entity has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) pads:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) struct media_pad *pads = &my_sd->pads;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) err = media_entity_pads_init(&sd->entity, npads, pads);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) The pads array must have been previously initialized. There is no need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) manually set the struct media_entity function and name fields, but the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) revision field must be initialized if needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) A reference to the entity will be automatically acquired/released when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) subdev device node (if any) is opened/closed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Don't forget to cleanup the media entity before the sub-device is destroyed:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) media_entity_cleanup(&sd->entity);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) If the subdev driver intends to process video and integrate with the media
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) framework, it must implement format related functionality using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) :c:type:`v4l2_subdev_pad_ops` instead of :c:type:`v4l2_subdev_video_ops`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) In that case, the subdev driver may set the link_validate field to provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) its own link validation function. The link validation function is called for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) every link in the pipeline where both of the ends of the links are V4L2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) sub-devices. The driver is still responsible for validating the correctness
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) of the format configuration between sub-devices and video nodes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) If link_validate op is not set, the default function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) :c:func:`v4l2_subdev_link_validate_default` is used instead. This function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) ensures that width, height and the media bus pixel code are equal on both source
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) and sink of the link. Subdev drivers are also free to use this function to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) perform the checks mentioned above in addition to their own checks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) Subdev registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) ~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) There are currently two ways to register subdevices with the V4L2 core. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) first (traditional) possibility is to have subdevices registered by bridge
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) drivers. This can be done when the bridge driver has the complete information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) about subdevices connected to it and knows exactly when to register them. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) is typically the case for internal subdevices, like video data processing units
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) within SoCs or complex PCI(e) boards, camera sensors in USB cameras or connected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) to SoCs, which pass information about them to bridge drivers, usually in their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) platform data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) There are however also situations where subdevices have to be registered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) asynchronously to bridge devices. An example of such a configuration is a Device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) Tree based system where information about subdevices is made available to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) system independently from the bridge devices, e.g. when subdevices are defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) in DT as I2C device nodes. The API used in this second case is described further
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) Using one or the other registration method only affects the probing process, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) run-time bridge-subdevice interaction is in both cases the same.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) In the **synchronous** case a device (bridge) driver needs to register the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) :c:type:`v4l2_subdev` with the v4l2_device:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) :c:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) (:c:type:`v4l2_dev <v4l2_device>`, :c:type:`sd <v4l2_subdev>`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) This can fail if the subdev module disappeared before it could be registered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) After this function was called successfully the subdev->dev field points to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) the :c:type:`v4l2_device`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) If the v4l2_device parent device has a non-NULL mdev field, the sub-device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) entity will be automatically registered with the media device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) You can unregister a sub-device using:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) :c:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) (:c:type:`sd <v4l2_subdev>`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) Afterwards the subdev module can be unloaded and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) :c:type:`sd <v4l2_subdev>`->dev == ``NULL``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) In the **asynchronous** case subdevice probing can be invoked independently of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) the bridge driver availability. The subdevice driver then has to verify whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) all the requirements for a successful probing are satisfied. This can include a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) check for a master clock availability. If any of the conditions aren't satisfied
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) attempts. Once all conditions are met the subdevice shall be registered using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) the :c:func:`v4l2_async_register_subdev` function. Unregistration is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) registered this way are stored in a global list of subdevices, ready to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) picked up by bridge drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) Bridge drivers in turn have to register a notifier object. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) performed using the :c:func:`v4l2_async_notifier_register` call. To
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) unregister the notifier the driver has to call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) :c:func:`v4l2_async_notifier_unregister`. The former of the two functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) takes two arguments: a pointer to struct :c:type:`v4l2_device` and a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) pointer to struct :c:type:`v4l2_async_notifier`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) Before registering the notifier, bridge drivers must do two things:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) first, the notifier must be initialized using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) :c:func:`v4l2_async_notifier_init`. Second, bridge drivers can then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) begin to form a list of subdevice descriptors that the bridge device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) needs for its operation. Subdevice descriptors are added to the notifier
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) using the :c:func:`v4l2_async_notifier_add_subdev` call. This function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) takes two arguments: a pointer to struct :c:type:`v4l2_async_notifier`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) and a pointer to the subdevice descripter, which is of type struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) :c:type:`v4l2_async_subdev`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) The V4L2 core will then use these descriptors to match asynchronously
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) registered subdevices to them. If a match is detected the ``.bound()``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) notifier callback is called. After all subdevices have been located the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) .complete() callback is called. When a subdevice is removed from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) system the .unbind() method is called. All three callbacks are optional.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) Calling subdev operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) ~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) does not contain any knowledge about the underlying hardware. So a driver might
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) contain several subdevs that use an I2C bus, but also a subdev that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) controlled through GPIO pins. This distinction is only relevant when setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) up the device, but once the subdev is registered it is completely transparent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) Once te subdev has been registered you can call an ops function either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) directly:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) err = sd->ops->core->g_std(sd, &norm);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) but it is better and easier to use this macro:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) err = v4l2_subdev_call(sd, core, g_std, &norm);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) The macro will do the right ``NULL`` pointer checks and returns ``-ENODEV``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) :c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the actual result of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) :c:type:`sd <v4l2_subdev>`->ops->core->g_std ops.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) It is also possible to call all or a subset of the sub-devices:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) Any subdev that does not support this ops is skipped and error results are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) ignored. If you want to check for errors use this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) Any error except ``-ENOIOCTLCMD`` will exit the loop with that error. If no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) errors (except ``-ENOIOCTLCMD``) occurred, then 0 is returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) The second argument to both calls is a group ID. If 0, then all subdevs are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) called. If non-zero, then only those whose group ID match that value will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) be called. Before a bridge driver registers a subdev it can set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) :c:type:`sd <v4l2_subdev>`->grp_id to whatever value it wants (it's 0 by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) default). This value is owned by the bridge driver and the sub-device driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) will never modify or use it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) The group ID gives the bridge driver more control how callbacks are called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) For example, there may be multiple audio chips on a board, each capable of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) changing the volume. But usually only one will actually be used when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) user want to change the volume. You can set the group ID for that subdev to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) ``v4l2_device_call_all()``. That ensures that it will only go to the subdev
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) that needs it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) If the sub-device needs to notify its v4l2_device parent of an event, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) it can call ``v4l2_subdev_notify(sd, notification, arg)``. This macro checks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) Otherwise the result of the ``notify()`` call is returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) V4L2 sub-device userspace API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) Bridge drivers traditionally expose one or multiple video nodes to userspace,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) and control subdevices through the :c:type:`v4l2_subdev_ops` operations in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) response to video node operations. This hides the complexity of the underlying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) hardware from applications. For complex devices, finer-grained control of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) device than what the video nodes offer may be required. In those cases, bridge
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) drivers that implement :ref:`the media controller API <media_controller>` may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) opt for making the subdevice operations directly accessible from userpace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) sub-devices directly. If a sub-device supports direct userspace configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) it must set the ``V4L2_SUBDEV_FL_HAS_DEVNODE`` flag before being registered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) After registering sub-devices, the :c:type:`v4l2_device` driver can create
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) device nodes for all registered sub-devices marked with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) ``V4L2_SUBDEV_FL_HAS_DEVNODE`` by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) :c:func:`v4l2_device_register_subdev_nodes`. Those device nodes will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) automatically removed when sub-devices are unregistered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) The device node handles a subset of the V4L2 API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) ``VIDIOC_QUERYCTRL``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) ``VIDIOC_QUERYMENU``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) ``VIDIOC_G_CTRL``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) ``VIDIOC_S_CTRL``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) ``VIDIOC_G_EXT_CTRLS``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) ``VIDIOC_S_EXT_CTRLS`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) ``VIDIOC_TRY_EXT_CTRLS``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) The controls ioctls are identical to the ones defined in V4L2. They
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) behave identically, with the only exception that they deal only with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) controls implemented in the sub-device. Depending on the driver, those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) controls can be also be accessed through one (or several) V4L2 device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) nodes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) ``VIDIOC_DQEVENT``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) ``VIDIOC_SUBSCRIBE_EVENT`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) ``VIDIOC_UNSUBSCRIBE_EVENT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) The events ioctls are identical to the ones defined in V4L2. They
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) behave identically, with the only exception that they deal only with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) events generated by the sub-device. Depending on the driver, those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) events can also be reported by one (or several) V4L2 device nodes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) Sub-device drivers that want to use events need to set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) ``V4L2_SUBDEV_FL_HAS_EVENTS`` :c:type:`v4l2_subdev`.flags before registering
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) the sub-device. After registration events can be queued as usual on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) :c:type:`v4l2_subdev`.devnode device node.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) To properly support events, the ``poll()`` file operation is also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) implemented.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) Private ioctls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) All ioctls not in the above list are passed directly to the sub-device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) driver through the core::ioctl operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) Read-only sub-device userspace API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) Bridge drivers that control their connected subdevices through direct calls to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) want userspace to be able to change the same parameters through the subdevice
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) device node and thus do not usually register any.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) It is sometimes useful to report to userspace the current subdevice
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) configuration through a read-only API, that does not permit applications to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) change to the device parameters but allows interfacing to the subdevice device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) node to inspect them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) For instance, to implement cameras based on computational photography, userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) needs to know the detailed camera sensor configuration (in terms of skipping,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) binning, cropping and scaling) for each supported output resolution. To support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) such use cases, bridge drivers may expose the subdevice operations to userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) through a read-only API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) To create a read-only device node for all the subdevices registered with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) ``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) :c:func:`v4l2_device_register_ro_subdev_nodes`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) Access to the following ioctls for userspace applications is restricted on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) sub-device device nodes registered with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) :c:func:`v4l2_device_register_ro_subdev_nodes`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) ``VIDIOC_SUBDEV_S_FMT``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) ``VIDIOC_SUBDEV_S_CROP``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) ``VIDIOC_SUBDEV_S_SELECTION``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) These ioctls are only allowed on a read-only subdevice device node
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) formats and selection rectangles.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) ``VIDIOC_SUBDEV_S_FRAME_INTERVAL``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) ``VIDIOC_SUBDEV_S_DV_TIMINGS``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) ``VIDIOC_SUBDEV_S_STD``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) These ioctls are not allowed on a read-only subdevice node.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) In case the ioctl is not allowed, or the format to modify is set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) ``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) the errno variable is set to ``-EPERM``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) I2C sub-device drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) Since these drivers are so common, special helper functions are available to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) ease the use of these drivers (``v4l2-common.h``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) The recommended method of adding :c:type:`v4l2_subdev` support to an I2C driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) is to embed the :c:type:`v4l2_subdev` struct into the state struct that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) created for each I2C device instance. Very simple devices have no state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) struct and in that case you can just create a :c:type:`v4l2_subdev` directly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) A typical state struct would look like this (where 'chipname' is replaced by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) the name of the chip):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) struct chipname_state {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) struct v4l2_subdev sd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) ... /* additional state fields */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) Initialize the :c:type:`v4l2_subdev` struct as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) This function will fill in all the fields of :c:type:`v4l2_subdev` ensure that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) the :c:type:`v4l2_subdev` and i2c_client both point to one another.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) You should also add a helper inline function to go from a :c:type:`v4l2_subdev`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) pointer to a chipname_state struct:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) return container_of(sd, struct chipname_state, sd);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) Use this to go from the :c:type:`v4l2_subdev` struct to the ``i2c_client``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) struct:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) struct i2c_client *client = v4l2_get_subdevdata(sd);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) And this to go from an ``i2c_client`` to a :c:type:`v4l2_subdev` struct:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) struct v4l2_subdev *sd = i2c_get_clientdata(client);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) Make sure to call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) :c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) when the ``remove()`` callback is called. This will unregister the sub-device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) from the bridge driver. It is safe to call this even if the sub-device was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) never registered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) You need to do this because when the bridge driver destroys the i2c adapter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) the ``remove()`` callbacks are called of the i2c devices on that adapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) After that the corresponding v4l2_subdev structures are invalid, so they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) have to be unregistered first. Calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) :c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) from the ``remove()`` callback ensures that this is always done correctly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) The bridge driver also has some helper functions it can use:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) "module_foo", "chipid", 0x36, NULL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) This loads the given module (can be ``NULL`` if no module needs to be loaded)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) and calls :c:func:`i2c_new_client_device` with the given ``i2c_adapter`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) chip/address arguments. If all goes well, then it registers the subdev with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) the v4l2_device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) You can also use the last argument of :c:func:`v4l2_i2c_new_subdev` to pass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) an array of possible I2C addresses that it should probe. These probe addresses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) are only used if the previous argument is 0. A non-zero argument means that you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) know the exact i2c address so in that case no probing will take place.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) Both functions return ``NULL`` if something went wrong.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) Note that the chipid you pass to :c:func:`v4l2_i2c_new_subdev` is usually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) the same as the module name. It allows you to specify a chip variant, e.g.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) "saa7114" or "saa7115". In general though the i2c driver autodetects this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) The use of chipid is something that needs to be looked at more closely at a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) later date. It differs between i2c drivers and as such can be confusing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) To see which chip variants are supported you can look in the i2c driver code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) for the i2c_device_id table. This lists all the possibilities.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) There are one more helper function:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) :c:func:`v4l2_i2c_new_subdev_board` uses an :c:type:`i2c_board_info` struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) which is passed to the i2c driver and replaces the irq, platform_data and addr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) arguments.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) If the subdev supports the s_config core ops, then that op is called with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) the irq and platform_data arguments after the subdev was setup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) The :c:func:`v4l2_i2c_new_subdev` function will call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) :c:func:`v4l2_i2c_new_subdev_board`, internally filling a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) :c:type:`i2c_board_info` structure using the ``client_type`` and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) ``addr`` to fill it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) V4L2 sub-device functions and data structures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) ---------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) .. kernel-doc:: include/media/v4l2-subdev.h
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags