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