diff options
Diffstat (limited to 'Documentation/media/kapi/v4l2-subdev.rst')
| -rw-r--r-- | Documentation/media/kapi/v4l2-subdev.rst | 42 |
1 files changed, 21 insertions, 21 deletions
diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst index 7e45b23ad3bd..d767b61e9842 100644 --- a/Documentation/media/kapi/v4l2-subdev.rst +++ b/Documentation/media/kapi/v4l2-subdev.rst @@ -15,7 +15,7 @@ can be stand-alone for simple sub-devices or it might be embedded in a larger struct if more state information needs to be stored. Usually there is a low-level device struct (e.g. ``i2c_client``) that contains the device data as setup by the kernel. It is recommended to store that pointer in the private -data of :c:type:`v4l2_subdev` using :cpp:func:`v4l2_set_subdevdata`. That makes +data of :c:type:`v4l2_subdev` using :c:func:`v4l2_set_subdevdata`. That makes it easy to go from a :c:type:`v4l2_subdev` to the actual low-level bus-specific device data. @@ -27,7 +27,7 @@ methods. Bridges might also need to store per-subdev private data, such as a pointer to bridge-specific per-subdev private data. The :c:type:`v4l2_subdev` structure provides host private data for that purpose that can be accessed with -:cpp:func:`v4l2_get_subdev_hostdata` and :cpp:func:`v4l2_set_subdev_hostdata`. +:c:func:`v4l2_get_subdev_hostdata` and :cpp:func:`v4l2_set_subdev_hostdata`. From the bridge driver perspective, you load the sub-device module and somehow obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call @@ -87,7 +87,7 @@ to add new ops and categories. A sub-device driver initializes the :c:type:`v4l2_subdev` struct using: - :cpp:func:`v4l2_subdev_init <v4l2_subdev_init>` + :c:func:`v4l2_subdev_init <v4l2_subdev_init>` (:c:type:`sd <v4l2_subdev>`, &\ :c:type:`ops <v4l2_subdev_ops>`). @@ -97,7 +97,7 @@ i2c helper functions. If integration with the media framework is needed, you must initialize the :c:type:`media_entity` struct embedded in the :c:type:`v4l2_subdev` struct -(entity field) by calling :cpp:func:`media_entity_pads_init`, if the entity has +(entity field) by calling :c:func:`media_entity_pads_init`, if the entity has pads: .. code-block:: c @@ -131,7 +131,7 @@ sub-devices. The driver is still responsible for validating the correctness of the format configuration between sub-devices and video nodes. If link_validate op is not set, the default function -:cpp:func:`v4l2_subdev_link_validate_default` is used instead. This function +:c:func:`v4l2_subdev_link_validate_default` is used instead. This function ensures that width, height and the media bus pixel code are equal on both source and sink of the link. Subdev drivers are also free to use this function to perform the checks mentioned above in addition to their own checks. @@ -158,7 +158,7 @@ run-time bridge-subdevice interaction is in both cases the same. In the synchronous case a device (bridge) driver needs to register the :c:type:`v4l2_subdev` with the v4l2_device: - :cpp:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>` + :c:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>` (:c:type:`v4l2_dev <v4l2_device>`, :c:type:`sd <v4l2_subdev>`). This can fail if the subdev module disappeared before it could be registered. @@ -170,7 +170,7 @@ entity will be automatically registered with the media device. You can unregister a sub-device using: - :cpp:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>` + :c:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>` (:c:type:`sd <v4l2_subdev>`). @@ -242,16 +242,16 @@ the requirements for a successful probing are satisfied. This can include a check for a master clock availability. If any of the conditions aren't satisfied the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing attempts. Once all conditions are met the subdevice shall be registered using -the :cpp:func:`v4l2_async_register_subdev` function. Unregistration is -performed using the :cpp:func:`v4l2_async_unregister_subdev` call. Subdevices +the :c:func:`v4l2_async_register_subdev` function. Unregistration is +performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices registered this way are stored in a global list of subdevices, ready to be picked up by bridge drivers. Bridge drivers in turn have to register a notifier object with an array of subdevice descriptors that the bridge device needs for its operation. This is -performed using the :cpp:func:`v4l2_async_notifier_register` call. To +performed using the :c:func:`v4l2_async_notifier_register` call. To unregister the notifier the driver has to call -:cpp:func:`v4l2_async_notifier_unregister`. The former of the two functions +:c:func:`v4l2_async_notifier_unregister`. The former of the two functions takes two arguments: a pointer to struct :c:type:`v4l2_device` and a pointer to struct :c:type:`v4l2_async_notifier`. The latter contains a pointer to an array of pointers to subdevice descriptors of type struct :c:type:`v4l2_async_subdev` @@ -275,7 +275,7 @@ it must set the ``V4L2_SUBDEV_FL_HAS_DEVNODE`` flag before being registered. After registering sub-devices, the :c:type:`v4l2_device` driver can create device nodes for all registered sub-devices marked with ``V4L2_SUBDEV_FL_HAS_DEVNODE`` by calling -:cpp:func:`v4l2_device_register_subdev_nodes`. Those device nodes will be +:c:func:`v4l2_device_register_subdev_nodes`. Those device nodes will be automatically removed when sub-devices are unregistered. The device node handles a subset of the V4L2 API. @@ -372,7 +372,7 @@ And this to go from an ``i2c_client`` to a :c:type:`v4l2_subdev` struct: struct v4l2_subdev *sd = i2c_get_clientdata(client); Make sure to call -:cpp:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`) +:c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`) when the ``remove()`` callback is called. This will unregister the sub-device from the bridge driver. It is safe to call this even if the sub-device was never registered. @@ -381,7 +381,7 @@ You need to do this because when the bridge driver destroys the i2c adapter the ``remove()`` callbacks are called of the i2c devices on that adapter. After that the corresponding v4l2_subdev structures are invalid, so they have to be unregistered first. Calling -:cpp:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`) +:c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`) from the ``remove()`` callback ensures that this is always done correctly. @@ -393,18 +393,18 @@ The bridge driver also has some helper functions it can use: "module_foo", "chipid", 0x36, NULL); This loads the given module (can be ``NULL`` if no module needs to be loaded) -and calls :cpp:func:`i2c_new_device` with the given ``i2c_adapter`` and +and calls :c:func:`i2c_new_device` with the given ``i2c_adapter`` and chip/address arguments. If all goes well, then it registers the subdev with the v4l2_device. -You can also use the last argument of :cpp:func:`v4l2_i2c_new_subdev` to pass +You can also use the last argument of :c:func:`v4l2_i2c_new_subdev` to pass an array of possible I2C addresses that it should probe. These probe addresses are only used if the previous argument is 0. A non-zero argument means that you know the exact i2c address so in that case no probing will take place. Both functions return ``NULL`` if something went wrong. -Note that the chipid you pass to :cpp:func:`v4l2_i2c_new_subdev` is usually +Note that the chipid you pass to :c:func:`v4l2_i2c_new_subdev` is usually the same as the module name. It allows you to specify a chip variant, e.g. "saa7114" or "saa7115". In general though the i2c driver autodetects this. The use of chipid is something that needs to be looked at more closely at a @@ -414,7 +414,7 @@ for the i2c_device_id table. This lists all the possibilities. There are two more helper functions: -:cpp:func:`v4l2_i2c_new_subdev_cfg`: this function adds new irq and +:c:func:`v4l2_i2c_new_subdev_cfg`: this function adds new irq and platform_data arguments and has both 'addr' and 'probed_addrs' arguments: if addr is not 0 then that will be used (non-probing variant), otherwise the probed_addrs are probed. @@ -426,15 +426,15 @@ For example: this will probe for address 0x10: struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter, "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10)); -:cpp:func:`v4l2_i2c_new_subdev_board` uses an :c:type:`i2c_board_info` struct +:c:func:`v4l2_i2c_new_subdev_board` uses an :c:type:`i2c_board_info` struct which is passed to the i2c driver and replaces the irq, platform_data and addr arguments. If the subdev supports the s_config core ops, then that op is called with the irq and platform_data arguments after the subdev was setup. -The older :cpp:func:`v4l2_i2c_new_subdev` and -:cpp:func:`v4l2_i2c_new_probed_subdev` functions will call ``s_config`` as +The older :c:func:`v4l2_i2c_new_subdev` and +:c:func:`v4l2_i2c_new_probed_subdev` functions will call ``s_config`` as well, but with irq set to 0 and platform_data set to ``NULL``. V4L2 sub-device functions and data structures |