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