From 2873f4db2ac28b83f076bd8283389b551e9be887 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Jul 2016 09:27:37 -0300 Subject: [media] v4l2-subdev.rst: add two sections from v4l2-framework.rst 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 --- Documentation/media/kapi/v4l2-framework.rst | 165 --------------------------- Documentation/media/kapi/v4l2-subdev.rst | 166 ++++++++++++++++++++++++++++ 2 files changed, 166 insertions(+), 165 deletions(-) (limited to 'Documentation/media') 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 ^^^^^^^^^^^^^^^^ -- cgit v1.2.3-59-g8ed1b