There are two additional subdev-specific sections at the
v4l2-framework file. Move them to the subdev chapter, in order
to better organize the book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
---
Documentation/media/kapi/v4l2-framework.rst | 165 ---------------------------
Documentation/media/kapi/v4l2-subdev.rst | 166 ++++++++++++++++++++++++++++
2 files changed, 166 insertions(+), 165 deletions(-)
diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst
index a7f64b38af5c..de341fc5b235 100644
--- a/Documentation/media/kapi/v4l2-framework.rst
+++ b/Documentation/media/kapi/v4l2-framework.rst
@@ -80,171 +80,6 @@ The V4L2 framework also optionally integrates with the media framework. If a
driver sets the struct v4l2_device mdev field, sub-devices and video nodes
will automatically appear in the media framework as entities.
-V4L2 sub-device userspace API
------------------------------
-
-Beside exposing a kernel API through the v4l2_subdev_ops structure, V4L2
-sub-devices can also be controlled directly by userspace applications.
-
-Device nodes named v4l-subdevX can be created in /dev to access sub-devices
-directly. If a sub-device supports direct userspace configuration it must set
-the V4L2_SUBDEV_FL_HAS_DEVNODE flag before being registered.
-
-After registering sub-devices, the v4l2_device driver can create device nodes
-for all registered sub-devices marked with V4L2_SUBDEV_FL_HAS_DEVNODE by calling
-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.
-
-VIDIOC_QUERYCTRL
-VIDIOC_QUERYMENU
-VIDIOC_G_CTRL
-VIDIOC_S_CTRL
-VIDIOC_G_EXT_CTRLS
-VIDIOC_S_EXT_CTRLS
-VIDIOC_TRY_EXT_CTRLS
-
- The controls ioctls are identical to the ones defined in V4L2. They
- behave identically, with the only exception that they deal only with
- controls implemented in the sub-device. Depending on the driver, those
- controls can be also be accessed through one (or several) V4L2 device
- nodes.
-
-VIDIOC_DQEVENT
-VIDIOC_SUBSCRIBE_EVENT
-VIDIOC_UNSUBSCRIBE_EVENT
-
- The events ioctls are identical to the ones defined in V4L2. They
- behave identically, with the only exception that they deal only with
- events generated by the sub-device. Depending on the driver, those
- events can also be reported by one (or several) V4L2 device nodes.
-
- Sub-device drivers that want to use events need to set the
- V4L2_SUBDEV_USES_EVENTS v4l2_subdev::flags and initialize
- v4l2_subdev::nevents to events queue depth before registering the
- sub-device. After registration events can be queued as usual on the
- v4l2_subdev::devnode device node.
-
- To properly support events, the poll() file operation is also
- implemented.
-
-Private ioctls
-
- All ioctls not in the above list are passed directly to the sub-device
- driver through the core::ioctl operation.
-
-
-I2C sub-device drivers
-----------------------
-
-Since these drivers are so common, special helper functions are available to
-ease the use of these drivers (v4l2-common.h).
-
-The recommended method of adding v4l2_subdev support to an I2C driver is to
-embed the v4l2_subdev struct into the state struct that is created for each
-I2C device instance. Very simple devices have no state struct and in that case
-you can just create a v4l2_subdev directly.
-
-A typical state struct would look like this (where 'chipname' is replaced by
-the name of the chip):
-
-.. code-block:: none
-
- struct chipname_state {
- struct v4l2_subdev sd;
- ... /* additional state fields */
- };
-
-Initialize the v4l2_subdev struct as follows:
-
-.. code-block:: none
-
- v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
-
-This function will fill in all the fields of v4l2_subdev and ensure that the
-v4l2_subdev and i2c_client both point to one another.
-
-You should also add a helper inline function to go from a v4l2_subdev pointer
-to a chipname_state struct:
-
-.. code-block:: none
-
- static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
- {
- return container_of(sd, struct chipname_state, sd);
- }
-
-Use this to go from the v4l2_subdev struct to the i2c_client struct:
-
-.. code-block:: none
-
- struct i2c_client *client = v4l2_get_subdevdata(sd);
-
-And this to go from an i2c_client to a v4l2_subdev struct:
-
-.. code-block:: none
-
- struct v4l2_subdev *sd = i2c_get_clientdata(client);
-
-Make sure to call v4l2_device_unregister_subdev(sd) 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.
-
-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 v4l2_device_unregister_subdev(sd)
-from the remove() callback ensures that this is always done correctly.
-
-
-The bridge driver also has some helper functions it can use:
-
-.. code-block:: none
-
- struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
- "module_foo", "chipid", 0x36, NULL);
-
-This loads the given module (can be NULL if no module needs to be loaded) and
-calls 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 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 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
-later date. It differs between i2c drivers and as such can be confusing.
-To see which chip variants are supported you can look in the i2c driver code
-for the i2c_device_id table. This lists all the possibilities.
-
-There are two more helper functions:
-
-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.
-
-For example: this will probe for address 0x10:
-
-.. code-block:: none
-
- struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
- "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
-
-v4l2_i2c_new_subdev_board uses an 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
-v4l2_i2c_new_(probed\_)subdev functions will call s_config as well, but with
-irq set to 0 and platform_data set to NULL.
struct video_device
-------------------
diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
index 829016940597..2845a749409c 100644
--- a/Documentation/media/kapi/v4l2-subdev.rst
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -262,6 +262,172 @@ is called. After all subdevices have been located the .complete() callback is
called. When a subdevice is removed from the system the .unbind() method is
called. All three callbacks are optional.
+V4L2 sub-device userspace API
+-----------------------------
+
+Beside exposing a kernel API through the v4l2_subdev_ops structure, V4L2
+sub-devices can also be controlled directly by userspace applications.
+
+Device nodes named v4l-subdevX can be created in /dev to access sub-devices
+directly. If a sub-device supports direct userspace configuration it must set
+the V4L2_SUBDEV_FL_HAS_DEVNODE flag before being registered.
+
+After registering sub-devices, the v4l2_device driver can create device nodes
+for all registered sub-devices marked with V4L2_SUBDEV_FL_HAS_DEVNODE by calling
+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.
+
+VIDIOC_QUERYCTRL
+VIDIOC_QUERYMENU
+VIDIOC_G_CTRL
+VIDIOC_S_CTRL
+VIDIOC_G_EXT_CTRLS
+VIDIOC_S_EXT_CTRLS
+VIDIOC_TRY_EXT_CTRLS
+
+ The controls ioctls are identical to the ones defined in V4L2. They
+ behave identically, with the only exception that they deal only with
+ controls implemented in the sub-device. Depending on the driver, those
+ controls can be also be accessed through one (or several) V4L2 device
+ nodes.
+
+VIDIOC_DQEVENT
+VIDIOC_SUBSCRIBE_EVENT
+VIDIOC_UNSUBSCRIBE_EVENT
+
+ The events ioctls are identical to the ones defined in V4L2. They
+ behave identically, with the only exception that they deal only with
+ events generated by the sub-device. Depending on the driver, those
+ events can also be reported by one (or several) V4L2 device nodes.
+
+ Sub-device drivers that want to use events need to set the
+ V4L2_SUBDEV_USES_EVENTS v4l2_subdev::flags and initialize
+ v4l2_subdev::nevents to events queue depth before registering the
+ sub-device. After registration events can be queued as usual on the
+ v4l2_subdev::devnode device node.
+
+ To properly support events, the poll() file operation is also
+ implemented.
+
+Private ioctls
+
+ All ioctls not in the above list are passed directly to the sub-device
+ driver through the core::ioctl operation.
+
+
+I2C sub-device drivers
+----------------------
+
+Since these drivers are so common, special helper functions are available to
+ease the use of these drivers (v4l2-common.h).
+
+The recommended method of adding v4l2_subdev support to an I2C driver is to
+embed the v4l2_subdev struct into the state struct that is created for each
+I2C device instance. Very simple devices have no state struct and in that case
+you can just create a v4l2_subdev directly.
+
+A typical state struct would look like this (where 'chipname' is replaced by
+the name of the chip):
+
+.. code-block:: none
+
+ struct chipname_state {
+ struct v4l2_subdev sd;
+ ... /* additional state fields */
+ };
+
+Initialize the v4l2_subdev struct as follows:
+
+.. code-block:: none
+
+ v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
+
+This function will fill in all the fields of v4l2_subdev and ensure that the
+v4l2_subdev and i2c_client both point to one another.
+
+You should also add a helper inline function to go from a v4l2_subdev pointer
+to a chipname_state struct:
+
+.. code-block:: none
+
+ static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
+ {
+ return container_of(sd, struct chipname_state, sd);
+ }
+
+Use this to go from the v4l2_subdev struct to the i2c_client struct:
+
+.. code-block:: none
+
+ struct i2c_client *client = v4l2_get_subdevdata(sd);
+
+And this to go from an i2c_client to a v4l2_subdev struct:
+
+.. code-block:: none
+
+ struct v4l2_subdev *sd = i2c_get_clientdata(client);
+
+Make sure to call v4l2_device_unregister_subdev(sd) 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.
+
+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 v4l2_device_unregister_subdev(sd)
+from the remove() callback ensures that this is always done correctly.
+
+
+The bridge driver also has some helper functions it can use:
+
+.. code-block:: none
+
+ struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
+ "module_foo", "chipid", 0x36, NULL);
+
+This loads the given module (can be NULL if no module needs to be loaded) and
+calls 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 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 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
+later date. It differs between i2c drivers and as such can be confusing.
+To see which chip variants are supported you can look in the i2c driver code
+for the i2c_device_id table. This lists all the possibilities.
+
+There are two more helper functions:
+
+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.
+
+For example: this will probe for address 0x10:
+
+.. code-block:: none
+
+ struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
+ "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
+
+v4l2_i2c_new_subdev_board uses an 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
+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 subdev kAPI
^^^^^^^^^^^^^^^^
--
2.7.4
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
