| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 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 |
| 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 |
| 20 |
data of :c:type:`v4l2_subdev` using :c:func:`v4l2_set_subdevdata`. That makes |
| 21 |
it easy to go from a :c:type:`v4l2_subdev` to the actual low-level bus-specific |
| 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 |
| 26 |
a :c:type:`v4l2_subdev` pointer, for other buses you may have to use other |
| 27 |
methods. |
| 28 |
|
| 29 |
Bridges might also need to store per-subdev private data, such as a pointer to |
| 30 |
bridge-specific per-subdev private data. The :c:type:`v4l2_subdev` structure |
| 31 |
provides host private data for that purpose that can be accessed with |
| 32 |
:c:func:`v4l2_get_subdev_hostdata` and :c:func:`v4l2_set_subdev_hostdata`. |
| 33 |
|
| 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 |
| 36 |
``i2c_get_clientdata()``. For other buses something similar needs to be done. |
| 37 |
Helper functions exist for sub-devices on an I2C bus that do most of this |
| 38 |
tricky work for you. |
| 39 |
|
| 40 |
Each :c:type:`v4l2_subdev` contains function pointers that sub-device drivers |
| 41 |
can implement (or leave ``NULL`` if it is not applicable). Since sub-devices can |
| 42 |
do so many different things and you do not want to end up with a huge ops struct |
| 43 |
of which only a handful of ops are commonly implemented, the function pointers |
| 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 |
|
| 51 |
.. code-block:: c |
| 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 |
|
| 90 |
A sub-device driver initializes the :c:type:`v4l2_subdev` struct using: |
| 91 |
|
| 92 |
:c:func:`v4l2_subdev_init <v4l2_subdev_init>` |
| 93 |
(:c:type:`sd <v4l2_subdev>`, &\ :c:type:`ops <v4l2_subdev_ops>`). |
| 94 |
|
| 95 |
|
| 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. |
| 99 |
|
| 100 |
If integration with the media framework is needed, you must initialize the |
| 101 |
:c:type:`media_entity` struct embedded in the :c:type:`v4l2_subdev` struct |
| 102 |
(entity field) by calling :c:func:`media_entity_pads_init`, if the entity has |
| 103 |
pads: |
| 104 |
|
| 105 |
.. code-block:: c |
| 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 |
| 113 |
manually set the struct media_entity function and name fields, but the |
| 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 |
|
| 121 |
.. code-block:: c |
| 122 |
|
| 123 |
media_entity_cleanup(&sd->entity); |
| 124 |
|
| 125 |
If a sub-device driver implements sink pads, the subdev driver may set the |
| 126 |
link_validate field in :c:type:`v4l2_subdev_pad_ops` to provide its own link |
| 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. |
| 131 |
|
| 132 |
If link_validate op is not set, the default function |
| 133 |
:c:func:`v4l2_subdev_link_validate_default` is used instead. This function |
| 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 |
| 136 |
perform the checks mentioned above in addition to their own checks. |
| 137 |
|
| 138 |
Subdev registration |
| 139 |
~~~~~~~~~~~~~~~~~~~ |
| 140 |
|
| 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 |
|
| 160 |
Registering synchronous sub-devices |
| 161 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 162 |
|
| 163 |
In the **synchronous** case a device (bridge) driver needs to register the |
| 164 |
:c:type:`v4l2_subdev` with the v4l2_device: |
| 165 |
|
| 166 |
:c:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>` |
| 167 |
(:c:type:`v4l2_dev <v4l2_device>`, :c:type:`sd <v4l2_subdev>`). |
| 168 |
|
| 169 |
This can fail if the subdev module disappeared before it could be registered. |
| 170 |
After this function was called successfully the subdev->dev field points to |
| 171 |
the :c:type:`v4l2_device`. |
| 172 |
|
| 173 |
If the v4l2_device parent device has a non-NULL mdev field, the sub-device |
| 174 |
entity will be automatically registered with the media device. |
| 175 |
|
| 176 |
You can unregister a sub-device using: |
| 177 |
|
| 178 |
:c:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>` |
| 179 |
(:c:type:`sd <v4l2_subdev>`). |
| 180 |
|
| 181 |
Afterwards the subdev module can be unloaded and |
| 182 |
:c:type:`sd <v4l2_subdev>`->dev == ``NULL``. |
| 183 |
|
| 184 |
.. _media-registering-async-subdevs: |
| 185 |
|
| 186 |
Registering asynchronous sub-devices |
| 187 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 188 |
|
| 189 |
In the **asynchronous** case subdevice probing can be invoked independently of |
| 190 |
the bridge driver availability. The subdevice driver then has to verify whether |
| 191 |
all the requirements for a successful probing are satisfied. This can include a |
| 192 |
check for a master clock availability. If any of the conditions aren't satisfied |
| 193 |
the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing |
| 194 |
attempts. Once all conditions are met the subdevice shall be registered using |
| 195 |
the :c:func:`v4l2_async_register_subdev` function. Unregistration is |
| 196 |
performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices |
| 197 |
registered this way are stored in a global list of subdevices, ready to be |
| 198 |
picked up by bridge drivers. |
| 199 |
|
| 200 |
Drivers must complete all initialization of the sub-device before |
| 201 |
registering it using :c:func:`v4l2_async_register_subdev`, including |
| 202 |
enabling runtime PM. This is because the sub-device becomes accessible |
| 203 |
as soon as it gets registered. |
| 204 |
|
| 205 |
Asynchronous sub-device notifiers |
| 206 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 207 |
|
| 208 |
Bridge drivers in turn have to register a notifier object. This is performed |
| 209 |
using the :c:func:`v4l2_async_nf_register` call. To unregister the notifier the |
| 210 |
driver has to call :c:func:`v4l2_async_nf_unregister`. Before releasing memory |
| 211 |
of an unregister notifier, it must be cleaned up by calling |
| 212 |
:c:func:`v4l2_async_nf_cleanup`. |
| 213 |
|
| 214 |
Before registering the notifier, bridge drivers must do two things: first, the |
| 215 |
notifier must be initialized using the :c:func:`v4l2_async_nf_init`. Second, |
| 216 |
bridge drivers can then begin to form a list of async connection descriptors |
| 217 |
that the bridge device needs for its |
| 218 |
operation. :c:func:`v4l2_async_nf_add_fwnode`, |
| 219 |
:c:func:`v4l2_async_nf_add_fwnode_remote` and :c:func:`v4l2_async_nf_add_i2c` |
| 220 |
|
| 221 |
Async connection descriptors describe connections to external sub-devices the |
| 222 |
drivers for which are not yet probed. Based on an async connection, a media data |
| 223 |
or ancillary link may be created when the related sub-device becomes |
| 224 |
available. There may be one or more async connections to a given sub-device but |
| 225 |
this is not known at the time of adding the connections to the notifier. Async |
| 226 |
connections are bound as matching async sub-devices are found, one by one. |
| 227 |
|
| 228 |
Asynchronous sub-device notifier for sub-devices |
| 229 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 230 |
|
| 231 |
A driver that registers an asynchronous sub-device may also register an |
| 232 |
asynchronous notifier. This is called an asynchronous sub-device notifier and the |
| 233 |
process is similar to that of a bridge driver apart from that the notifier is |
| 234 |
initialised using :c:func:`v4l2_async_subdev_nf_init` instead. A sub-device |
| 235 |
notifier may complete only after the V4L2 device becomes available, i.e. there's |
| 236 |
a path via async sub-devices and notifiers to a notifier that is not an |
| 237 |
asynchronous sub-device notifier. |
| 238 |
|
| 239 |
Asynchronous sub-device registration helper for camera sensor drivers |
| 240 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 241 |
|
| 242 |
:c:func:`v4l2_async_register_subdev_sensor` is a helper function for sensor |
| 243 |
drivers registering their own async connection, but it also registers a notifier |
| 244 |
and further registers async connections for lens and flash devices found in |
| 245 |
firmware. The notifier for the sub-device is unregistered and cleaned up with |
| 246 |
the async sub-device, using :c:func:`v4l2_async_unregister_subdev`. |
| 247 |
|
| 248 |
Asynchronous sub-device notifier example |
| 249 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 250 |
|
| 251 |
These functions allocate an async connection descriptor which is of type struct |
| 252 |
:c:type:`v4l2_async_connection` embedded in a driver-specific struct. The &struct |
| 253 |
:c:type:`v4l2_async_connection` shall be the first member of this struct: |
| 254 |
|
| 255 |
.. code-block:: c |
| 256 |
|
| 257 |
struct my_async_connection { |
| 258 |
struct v4l2_async_connection asc; |
| 259 |
... |
| 260 |
}; |
| 261 |
|
| 262 |
struct my_async_connection *my_asc; |
| 263 |
struct fwnode_handle *ep; |
| 264 |
|
| 265 |
... |
| 266 |
|
| 267 |
my_asc = v4l2_async_nf_add_fwnode_remote(¬ifier, ep, |
| 268 |
struct my_async_connection); |
| 269 |
fwnode_handle_put(ep); |
| 270 |
|
| 271 |
if (IS_ERR(my_asc)) |
| 272 |
return PTR_ERR(my_asc); |
| 273 |
|
| 274 |
Asynchronous sub-device notifier callbacks |
| 275 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 276 |
|
| 277 |
The V4L2 core will then use these connection descriptors to match asynchronously |
| 278 |
registered subdevices to them. If a match is detected the ``.bound()`` notifier |
| 279 |
callback is called. After all connections have been bound the .complete() |
| 280 |
callback is called. When a connection is removed from the system the |
| 281 |
``.unbind()`` method is called. All three callbacks are optional. |
| 282 |
|
| 283 |
Drivers can store any type of custom data in their driver-specific |
| 284 |
:c:type:`v4l2_async_connection` wrapper. If any of that data requires special |
| 285 |
handling when the structure is freed, drivers must implement the ``.destroy()`` |
| 286 |
notifier callback. The framework will call it right before freeing the |
| 287 |
:c:type:`v4l2_async_connection`. |
| 288 |
|
| 289 |
Calling subdev operations |
| 290 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 291 |
|
| 292 |
The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and |
| 293 |
does not contain any knowledge about the underlying hardware. So a driver might |
| 294 |
contain several subdevs that use an I2C bus, but also a subdev that is |
| 295 |
controlled through GPIO pins. This distinction is only relevant when setting |
| 296 |
up the device, but once the subdev is registered it is completely transparent. |
| 297 |
|
| 298 |
Once the subdev has been registered you can call an ops function either |
| 299 |
directly: |
| 300 |
|
| 301 |
.. code-block:: c |
| 302 |
|
| 303 |
err = sd->ops->core->g_std(sd, &norm); |
| 304 |
|
| 305 |
but it is better and easier to use this macro: |
| 306 |
|
| 307 |
.. code-block:: c |
| 308 |
|
| 309 |
err = v4l2_subdev_call(sd, core, g_std, &norm); |
| 310 |
|
| 311 |
The macro will do the right ``NULL`` pointer checks and returns ``-ENODEV`` |
| 312 |
if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either |
| 313 |
:c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the actual result of the |
| 314 |
:c:type:`sd <v4l2_subdev>`->ops->core->g_std ops. |
| 315 |
|
| 316 |
It is also possible to call all or a subset of the sub-devices: |
| 317 |
|
| 318 |
.. code-block:: c |
| 319 |
|
| 320 |
v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm); |
| 321 |
|
| 322 |
Any subdev that does not support this ops is skipped and error results are |
| 323 |
ignored. If you want to check for errors use this: |
| 324 |
|
| 325 |
.. code-block:: c |
| 326 |
|
| 327 |
err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm); |
| 328 |
|
| 329 |
Any error except ``-ENOIOCTLCMD`` will exit the loop with that error. If no |
| 330 |
errors (except ``-ENOIOCTLCMD``) occurred, then 0 is returned. |
| 331 |
|
| 332 |
The second argument to both calls is a group ID. If 0, then all subdevs are |
| 333 |
called. If non-zero, then only those whose group ID match that value will |
| 334 |
be called. Before a bridge driver registers a subdev it can set |
| 335 |
:c:type:`sd <v4l2_subdev>`->grp_id to whatever value it wants (it's 0 by |
| 336 |
default). This value is owned by the bridge driver and the sub-device driver |
| 337 |
will never modify or use it. |
| 338 |
|
| 339 |
The group ID gives the bridge driver more control how callbacks are called. |
| 340 |
For example, there may be multiple audio chips on a board, each capable of |
| 341 |
changing the volume. But usually only one will actually be used when the |
| 342 |
user want to change the volume. You can set the group ID for that subdev to |
| 343 |
e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling |
| 344 |
``v4l2_device_call_all()``. That ensures that it will only go to the subdev |
| 345 |
that needs it. |
| 346 |
|
| 347 |
If the sub-device needs to notify its v4l2_device parent of an event, then |
| 348 |
it can call ``v4l2_subdev_notify(sd, notification, arg)``. This macro checks |
| 349 |
whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not. |
| 350 |
Otherwise the result of the ``notify()`` call is returned. |
| 351 |
|
| 352 |
V4L2 sub-device userspace API |
| 353 |
----------------------------- |
| 354 |
|
| 355 |
Bridge drivers traditionally expose one or multiple video nodes to userspace, |
| 356 |
and control subdevices through the :c:type:`v4l2_subdev_ops` operations in |
| 357 |
response to video node operations. This hides the complexity of the underlying |
| 358 |
hardware from applications. For complex devices, finer-grained control of the |
| 359 |
device than what the video nodes offer may be required. In those cases, bridge |
| 360 |
drivers that implement :ref:`the media controller API <media_controller>` may |
| 361 |
opt for making the subdevice operations directly accessible from userspace. |
| 362 |
|
| 363 |
Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access |
| 364 |
sub-devices directly. If a sub-device supports direct userspace configuration |
| 365 |
it must set the ``V4L2_SUBDEV_FL_HAS_DEVNODE`` flag before being registered. |
| 366 |
|
| 367 |
After registering sub-devices, the :c:type:`v4l2_device` driver can create |
| 368 |
device nodes for all registered sub-devices marked with |
| 369 |
``V4L2_SUBDEV_FL_HAS_DEVNODE`` by calling |
| 370 |
:c:func:`v4l2_device_register_subdev_nodes`. Those device nodes will be |
| 371 |
automatically removed when sub-devices are unregistered. |
| 372 |
|
| 373 |
The device node handles a subset of the V4L2 API. |
| 374 |
|
| 375 |
``VIDIOC_QUERYCTRL``, |
| 376 |
``VIDIOC_QUERYMENU``, |
| 377 |
``VIDIOC_G_CTRL``, |
| 378 |
``VIDIOC_S_CTRL``, |
| 379 |
``VIDIOC_G_EXT_CTRLS``, |
| 380 |
``VIDIOC_S_EXT_CTRLS`` and |
| 381 |
``VIDIOC_TRY_EXT_CTRLS``: |
| 382 |
|
| 383 |
The controls ioctls are identical to the ones defined in V4L2. They |
| 384 |
behave identically, with the only exception that they deal only with |
| 385 |
controls implemented in the sub-device. Depending on the driver, those |
| 386 |
controls can be also be accessed through one (or several) V4L2 device |
| 387 |
nodes. |
| 388 |
|
| 389 |
``VIDIOC_DQEVENT``, |
| 390 |
``VIDIOC_SUBSCRIBE_EVENT`` and |
| 391 |
``VIDIOC_UNSUBSCRIBE_EVENT`` |
| 392 |
|
| 393 |
The events ioctls are identical to the ones defined in V4L2. They |
| 394 |
behave identically, with the only exception that they deal only with |
| 395 |
events generated by the sub-device. Depending on the driver, those |
| 396 |
events can also be reported by one (or several) V4L2 device nodes. |
| 397 |
|
| 398 |
Sub-device drivers that want to use events need to set the |
| 399 |
``V4L2_SUBDEV_FL_HAS_EVENTS`` :c:type:`v4l2_subdev`.flags before registering |
| 400 |
the sub-device. After registration events can be queued as usual on the |
| 401 |
:c:type:`v4l2_subdev`.devnode device node. |
| 402 |
|
| 403 |
To properly support events, the ``poll()`` file operation is also |
| 404 |
implemented. |
| 405 |
|
| 406 |
Private ioctls |
| 407 |
|
| 408 |
All ioctls not in the above list are passed directly to the sub-device |
| 409 |
driver through the core::ioctl operation. |
| 410 |
|
| 411 |
Read-only sub-device userspace API |
| 412 |
---------------------------------- |
| 413 |
|
| 414 |
Bridge drivers that control their connected subdevices through direct calls to |
| 415 |
the kernel API realized by :c:type:`v4l2_subdev_ops` structure do not usually |
| 416 |
want userspace to be able to change the same parameters through the subdevice |
| 417 |
device node and thus do not usually register any. |
| 418 |
|
| 419 |
It is sometimes useful to report to userspace the current subdevice |
| 420 |
configuration through a read-only API, that does not permit applications to |
| 421 |
change to the device parameters but allows interfacing to the subdevice device |
| 422 |
node to inspect them. |
| 423 |
|
| 424 |
For instance, to implement cameras based on computational photography, userspace |
| 425 |
needs to know the detailed camera sensor configuration (in terms of skipping, |
| 426 |
binning, cropping and scaling) for each supported output resolution. To support |
| 427 |
such use cases, bridge drivers may expose the subdevice operations to userspace |
| 428 |
through a read-only API. |
| 429 |
|
| 430 |
To create a read-only device node for all the subdevices registered with the |
| 431 |
``V4L2_SUBDEV_FL_HAS_DEVNODE`` set, the :c:type:`v4l2_device` driver should call |
| 432 |
:c:func:`v4l2_device_register_ro_subdev_nodes`. |
| 433 |
|
| 434 |
Access to the following ioctls for userspace applications is restricted on |
| 435 |
sub-device device nodes registered with |
| 436 |
:c:func:`v4l2_device_register_ro_subdev_nodes`. |
| 437 |
|
| 438 |
``VIDIOC_SUBDEV_S_FMT``, |
| 439 |
``VIDIOC_SUBDEV_S_CROP``, |
| 440 |
``VIDIOC_SUBDEV_S_SELECTION``: |
| 441 |
|
| 442 |
These ioctls are only allowed on a read-only subdevice device node |
| 443 |
for the :ref:`V4L2_SUBDEV_FORMAT_TRY <v4l2-subdev-format-whence>` |
| 444 |
formats and selection rectangles. |
| 445 |
|
| 446 |
``VIDIOC_SUBDEV_S_FRAME_INTERVAL``, |
| 447 |
``VIDIOC_SUBDEV_S_DV_TIMINGS``, |
| 448 |
``VIDIOC_SUBDEV_S_STD``: |
| 449 |
|
| 450 |
These ioctls are not allowed on a read-only subdevice node. |
| 451 |
|
| 452 |
In case the ioctl is not allowed, or the format to modify is set to |
| 453 |
``V4L2_SUBDEV_FORMAT_ACTIVE``, the core returns a negative error code and |
| 454 |
the errno variable is set to ``-EPERM``. |
| 455 |
|
| 456 |
I2C sub-device drivers |
| 457 |
---------------------- |
| 458 |
|
| 459 |
Since these drivers are so common, special helper functions are available to |
| 460 |
ease the use of these drivers (``v4l2-common.h``). |
| 461 |
|
| 462 |
The recommended method of adding :c:type:`v4l2_subdev` support to an I2C driver |
| 463 |
is to embed the :c:type:`v4l2_subdev` struct into the state struct that is |
| 464 |
created for each I2C device instance. Very simple devices have no state |
| 465 |
struct and in that case you can just create a :c:type:`v4l2_subdev` directly. |
| 466 |
|
| 467 |
A typical state struct would look like this (where 'chipname' is replaced by |
| 468 |
the name of the chip): |
| 469 |
|
| 470 |
.. code-block:: c |
| 471 |
|
| 472 |
struct chipname_state { |
| 473 |
struct v4l2_subdev sd; |
| 474 |
... /* additional state fields */ |
| 475 |
}; |
| 476 |
|
| 477 |
Initialize the :c:type:`v4l2_subdev` struct as follows: |
| 478 |
|
| 479 |
.. code-block:: c |
| 480 |
|
| 481 |
v4l2_i2c_subdev_init(&state->sd, client, subdev_ops); |
| 482 |
|
| 483 |
This function will fill in all the fields of :c:type:`v4l2_subdev` ensure that |
| 484 |
the :c:type:`v4l2_subdev` and i2c_client both point to one another. |
| 485 |
|
| 486 |
You should also add a helper inline function to go from a :c:type:`v4l2_subdev` |
| 487 |
pointer to a chipname_state struct: |
| 488 |
|
| 489 |
.. code-block:: c |
| 490 |
|
| 491 |
static inline struct chipname_state *to_state(struct v4l2_subdev *sd) |
| 492 |
{ |
| 493 |
return container_of(sd, struct chipname_state, sd); |
| 494 |
} |
| 495 |
|
| 496 |
Use this to go from the :c:type:`v4l2_subdev` struct to the ``i2c_client`` |
| 497 |
struct: |
| 498 |
|
| 499 |
.. code-block:: c |
| 500 |
|
| 501 |
struct i2c_client *client = v4l2_get_subdevdata(sd); |
| 502 |
|
| 503 |
And this to go from an ``i2c_client`` to a :c:type:`v4l2_subdev` struct: |
| 504 |
|
| 505 |
.. code-block:: c |
| 506 |
|
| 507 |
struct v4l2_subdev *sd = i2c_get_clientdata(client); |
| 508 |
|
| 509 |
Make sure to call |
| 510 |
:c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`) |
| 511 |
when the ``remove()`` callback is called. This will unregister the sub-device |
| 512 |
from the bridge driver. It is safe to call this even if the sub-device was |
| 513 |
never registered. |
| 514 |
|
| 515 |
You need to do this because when the bridge driver destroys the i2c adapter |
| 516 |
the ``remove()`` callbacks are called of the i2c devices on that adapter. |
| 517 |
After that the corresponding v4l2_subdev structures are invalid, so they |
| 518 |
have to be unregistered first. Calling |
| 519 |
:c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`) |
| 520 |
from the ``remove()`` callback ensures that this is always done correctly. |
| 521 |
|
| 522 |
|
| 523 |
The bridge driver also has some helper functions it can use: |
| 524 |
|
| 525 |
.. code-block:: c |
| 526 |
|
| 527 |
struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter, |
| 528 |
"module_foo", "chipid", 0x36, NULL); |
| 529 |
|
| 530 |
This loads the given module (can be ``NULL`` if no module needs to be loaded) |
| 531 |
and calls :c:func:`i2c_new_client_device` with the given ``i2c_adapter`` and |
| 532 |
chip/address arguments. If all goes well, then it registers the subdev with |
| 533 |
the v4l2_device. |
| 534 |
|
| 535 |
You can also use the last argument of :c:func:`v4l2_i2c_new_subdev` to pass |
| 536 |
an array of possible I2C addresses that it should probe. These probe addresses |
| 537 |
are only used if the previous argument is 0. A non-zero argument means that you |
| 538 |
know the exact i2c address so in that case no probing will take place. |
| 539 |
|
| 540 |
Both functions return ``NULL`` if something went wrong. |
| 541 |
|
| 542 |
Note that the chipid you pass to :c:func:`v4l2_i2c_new_subdev` is usually |
| 543 |
the same as the module name. It allows you to specify a chip variant, e.g. |
| 544 |
"saa7114" or "saa7115". In general though the i2c driver autodetects this. |
| 545 |
The use of chipid is something that needs to be looked at more closely at a |
| 546 |
later date. It differs between i2c drivers and as such can be confusing. |
| 547 |
To see which chip variants are supported you can look in the i2c driver code |
| 548 |
for the i2c_device_id table. This lists all the possibilities. |
| 549 |
|
| 550 |
There are one more helper function: |
| 551 |
|
| 552 |
:c:func:`v4l2_i2c_new_subdev_board` uses an :c:type:`i2c_board_info` struct |
| 553 |
which is passed to the i2c driver and replaces the irq, platform_data and addr |
| 554 |
arguments. |
| 555 |
|
| 556 |
If the subdev supports the s_config core ops, then that op is called with |
| 557 |
the irq and platform_data arguments after the subdev was setup. |
| 558 |
|
| 559 |
The :c:func:`v4l2_i2c_new_subdev` function will call |
| 560 |
:c:func:`v4l2_i2c_new_subdev_board`, internally filling a |
| 561 |
:c:type:`i2c_board_info` structure using the ``client_type`` and the |
| 562 |
``addr`` to fill it. |
| 563 |
|
| 564 |
Centrally managed subdev active state |
| 565 |
------------------------------------- |
| 566 |
|
| 567 |
Traditionally V4L2 subdev drivers maintained internal state for the active |
| 568 |
device configuration. This is often implemented as e.g. an array of struct |
| 569 |
v4l2_mbus_framefmt, one entry for each pad, and similarly for crop and compose |
| 570 |
rectangles. |
| 571 |
|
| 572 |
In addition to the active configuration, each subdev file handle has a struct |
| 573 |
v4l2_subdev_state, managed by the V4L2 core, which contains the try |
| 574 |
configuration. |
| 575 |
|
| 576 |
To simplify the subdev drivers the V4L2 subdev API now optionally supports a |
| 577 |
centrally managed active configuration represented by |
| 578 |
:c:type:`v4l2_subdev_state`. One instance of state, which contains the active |
| 579 |
device configuration, is stored in the sub-device itself as part of |
| 580 |
the :c:type:`v4l2_subdev` structure, while the core associates a try state to |
| 581 |
each open file handle, to store the try configuration related to that file |
| 582 |
handle. |
| 583 |
|
| 584 |
Sub-device drivers can opt-in and use state to manage their active configuration |
| 585 |
by initializing the subdevice state with a call to v4l2_subdev_init_finalize() |
| 586 |
before registering the sub-device. They must also call v4l2_subdev_cleanup() |
| 587 |
to release all the allocated resources before unregistering the sub-device. |
| 588 |
The core automatically allocates and initializes a state for each open file |
| 589 |
handle to store the try configurations and frees it when closing the file |
| 590 |
handle. |
| 591 |
|
| 592 |
V4L2 sub-device operations that use both the :ref:`ACTIVE and TRY formats |
| 593 |
<v4l2-subdev-format-whence>` receive the correct state to operate on through |
| 594 |
the 'state' parameter. The state must be locked and unlocked by the |
| 595 |
caller by calling :c:func:`v4l2_subdev_lock_state()` and |
| 596 |
:c:func:`v4l2_subdev_unlock_state()`. The caller can do so by calling the subdev |
| 597 |
operation through the :c:func:`v4l2_subdev_call_state_active()` macro. |
| 598 |
|
| 599 |
Operations that do not receive a state parameter implicitly operate on the |
| 600 |
subdevice active state, which drivers can exclusively access by |
| 601 |
calling :c:func:`v4l2_subdev_lock_and_get_active_state()`. The sub-device active |
| 602 |
state must equally be released by calling :c:func:`v4l2_subdev_unlock_state()`. |
| 603 |
|
| 604 |
Drivers must never manually access the state stored in the :c:type:`v4l2_subdev` |
| 605 |
or in the file handle without going through the designated helpers. |
| 606 |
|
| 607 |
While the V4L2 core passes the correct try or active state to the subdevice |
| 608 |
operations, many existing device drivers pass a NULL state when calling |
| 609 |
operations with :c:func:`v4l2_subdev_call()`. This legacy construct causes |
| 610 |
issues with subdevice drivers that let the V4L2 core manage the active state, |
| 611 |
as they expect to receive the appropriate state as a parameter. To help the |
| 612 |
conversion of subdevice drivers to a managed active state without having to |
| 613 |
convert all callers at the same time, an additional wrapper layer has been |
| 614 |
added to v4l2_subdev_call(), which handles the NULL case by getting and locking |
| 615 |
the callee's active state with :c:func:`v4l2_subdev_lock_and_get_active_state()`, |
| 616 |
and unlocking the state after the call. |
| 617 |
|
| 618 |
The whole subdev state is in reality split into three parts: the |
| 619 |
v4l2_subdev_state, subdev controls and subdev driver's internal state. In the |
| 620 |
future these parts should be combined into a single state. For the time being |
| 621 |
we need a way to handle the locking for these parts. This can be accomplished |
| 622 |
by sharing a lock. The v4l2_ctrl_handler already supports this via its 'lock' |
| 623 |
pointer and the same model is used with states. The driver can do the following |
| 624 |
before calling v4l2_subdev_init_finalize(): |
| 625 |
|
| 626 |
.. code-block:: c |
| 627 |
|
| 628 |
sd->ctrl_handler->lock = &priv->mutex; |
| 629 |
sd->state_lock = &priv->mutex; |
| 630 |
|
| 631 |
This shares the driver's private mutex between the controls and the states. |
| 632 |
|
| 633 |
Streams, multiplexed media pads and internal routing |
| 634 |
---------------------------------------------------- |
| 635 |
|
| 636 |
A subdevice driver can implement support for multiplexed streams by setting |
| 637 |
the V4L2_SUBDEV_FL_STREAMS subdev flag and implementing support for |
| 638 |
centrally managed subdev active state, routing and stream based |
| 639 |
configuration. |
| 640 |
|
| 641 |
V4L2 sub-device functions and data structures |
| 642 |
--------------------------------------------- |
| 643 |
|
| 644 |
.. kernel-doc:: include/media/v4l2-subdev.h |