[media] doc-rst: move videobuf documentation to media/kapi

V4L2 Controls

=============

Introduction

============

------------

The V4L2 control API seems simple enough, but quickly becomes very hard to

implement correctly in drivers. But much of the code needed to handle controls

Objects in the framework

========================

------------------------

There are two main objects:

Basic usage for V4L2 and sub-device drivers

===========================================

-------------------------------------------

1) Prepare the driver:

1.1) Add the handler to your driver's top-level struct:

.. code-block:: none

	struct foo_dev {

		...

		struct v4l2_ctrl_handler ctrl_handler;

1.2) Initialize the handler:

.. code-block:: none

	v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);

The second argument is a hint telling the function how many controls this

1.3.1) For V4L2 drivers do this:

.. code-block:: none

	struct foo_dev {

		...

		struct v4l2_device v4l2_dev;

1.3.2) For sub-device drivers do this:

.. code-block:: none

	struct foo_dev {

		...

		struct v4l2_subdev sd;

And set all core control ops in your struct v4l2_subdev_core_ops to these

helpers:

.. code-block:: none

	.queryctrl = v4l2_subdev_queryctrl,

	.querymenu = v4l2_subdev_querymenu,

	.g_ctrl = v4l2_subdev_g_ctrl,

1.4) Clean up the handler at the end:

.. code-block:: none

	v4l2_ctrl_handler_free(&foo->ctrl_handler);

You add non-menu controls by calling v4l2_ctrl_new_std:

.. code-block:: none

	struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,

			const struct v4l2_ctrl_ops *ops,

			u32 id, s32 min, s32 max, u32 step, s32 def);

Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu:

.. code-block:: none

	struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,

			const struct v4l2_ctrl_ops *ops,

			u32 id, s32 max, s32 skip_mask, s32 def);

Menu controls with a driver specific menu are added by calling

v4l2_ctrl_new_std_menu_items:

.. code-block:: none

       struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(

                       struct v4l2_ctrl_handler *hdl,

                       const struct v4l2_ctrl_ops *ops, u32 id, s32 max,

Integer menu controls with a driver specific menu can be added by calling

v4l2_ctrl_new_int_menu:

.. code-block:: none

	struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,

			const struct v4l2_ctrl_ops *ops,

			u32 id, s32 max, s32 def, const s64 *qmenu_int);

These functions are typically called right after the v4l2_ctrl_handler_init:

.. code-block:: none

	static const s64 exp_bias_qmenu[] = {

	       -2, -1, 0, 1, 2

	};

3) Optionally force initial control setup:

.. code-block:: none

	v4l2_ctrl_handler_setup(&foo->ctrl_handler);

This will call s_ctrl for all controls unconditionally. Effectively this

4) Finally: implement the v4l2_ctrl_ops

.. code-block:: none

	static const struct v4l2_ctrl_ops foo_ctrl_ops = {

		.s_ctrl = foo_s_ctrl,

	};

Usually all you need is s_ctrl:

.. code-block:: none

	static int foo_s_ctrl(struct v4l2_ctrl *ctrl)

	{

		struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);

and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.

==============================================================================

.. note::

The remainder of this document deals with more advanced topics and scenarios.

   The remainder sections deal with more advanced controls topics and scenarios.

   In practice the basic usage as described above is sufficient for most drivers.

===============================================================================

Inheriting Controls

===================

-------------------

When a sub-device is registered with a V4L2 driver by calling

v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev

Accessing Control Values

========================

------------------------

The following union is used inside the control framework to access control

values:

.. code-block:: none

	union v4l2_ctrl_ptr {

		s32 *p_s32;

		s64 *p_s64;

The v4l2_ctrl struct contains these fields that can be used to access both

current and new values:

.. code-block:: none

	s32 val;

	struct {

		s32 val;

If the control has a simple s32 type type, then:

.. code-block:: none

	&ctrl->val == ctrl->p_new.p_s32

	&ctrl->cur.val == ctrl->p_cur.p_s32

strength read-out that changes continuously. In that case you will need to

implement g_volatile_ctrl like this:

.. code-block:: none

	static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl)

	{

		switch (ctrl->id) {

To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:

.. code-block:: none

	ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);

	if (ctrl)

		ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;

Outside of the control ops you have to go through to helper functions to get

or set a single control value safely in your driver:

.. code-block:: none

	s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);

	int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);

You can also take the handler lock yourself:

.. code-block:: none

	mutex_lock(&state->ctrl_handler.lock);

	pr_info("String value is '%s'\n", ctrl1->p_cur.p_char);

	pr_info("Integer value is '%s'\n", ctrl2->cur.val);

Menu Controls

=============

-------------

The v4l2_ctrl struct contains this union:

.. code-block:: none

	union {

		u32 step;

		u32 menu_skip_mask;

Custom Controls

===============

---------------

Driver specific controls can be created using v4l2_ctrl_new_custom():

.. code-block:: none

	static const struct v4l2_ctrl_config ctrl_filter = {

		.ops = &ctrl_custom_ops,

		.id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER,

Active and Grabbed Controls

===========================

---------------------------

If you get more complex relationships between controls, then you may have to

activate and deactivate controls. For example, if the Chroma AGC control is

Control Clusters

================

----------------

By default all controls are independent from the others. But in more

complex scenarios you can get dependencies from one control to another.

In that case you need to 'cluster' them:

.. code-block:: none

	struct foo {

		struct v4l2_ctrl_handler ctrl_handler;

	#define AUDIO_CL_VOLUME (0)

So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set

all two controls belonging to the audio_cluster:

.. code-block:: none

	static int foo_s_ctrl(struct v4l2_ctrl *ctrl)

	{

		struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);

In the example above the following are equivalent for the VOLUME case:

.. code-block:: none

	ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]

	ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]

In practice using cluster arrays like this becomes very tiresome. So instead

the following equivalent method is used:

.. code-block:: none

	struct {

		/* audio cluster */

		struct v4l2_ctrl *volume;

but it serves no other purpose. The effect is the same as creating an

array with two control pointers. So you can just do:

.. code-block:: none

	state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);

	state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);

	v4l2_ctrl_cluster(2, &state->volume);

Handling autogain/gain-type Controls with Auto Clusters

=======================================================

-------------------------------------------------------

A common type of control cluster is one that handles 'auto-foo/foo'-type

controls. Typical examples are autogain/gain, autoexposure/exposure,

In order to simplify this a special variation of v4l2_ctrl_cluster was

introduced:

.. code-block:: none

	void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,

				    u8 manual_val, bool set_volatile);

VIDIOC_LOG_STATUS Support

=========================

-------------------------

This ioctl allow you to dump the current status of a driver to the kernel log.

The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the

Different Handlers for Different Video Nodes

============================================

--------------------------------------------

Usually the V4L2 driver has just one control handler that is global for

all video nodes. But you can also specify different control handlers for

the controls to the first handler, add the other controls to the second

handler and finally add the first handler to the second. For example:

.. code-block:: none

	v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...);

	v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);

	v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);

Or you can add specific controls to a handler:

.. code-block:: none

	volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...);

	v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...);

	v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...);

What you should not do is make two identical controls for two handlers.

For example:

.. code-block:: none

	v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);

	v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...);

Finding Controls

================

----------------

Normally you have created the controls yourself and you can store the struct

v4l2_ctrl pointer into your own struct.

You can do that by calling v4l2_ctrl_find:

.. code-block:: none

	struct v4l2_ctrl *volume;

	volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);

Since v4l2_ctrl_find will lock the handler you have to be careful where you

use it. For example, this is not a good idea:

.. code-block:: none

	struct v4l2_ctrl_handler ctrl_handler;

	v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);

...and in video_ops.s_ctrl:

.. code-block:: none

	case V4L2_CID_BRIGHTNESS:

		contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST);

		...

Inheriting Controls

===================

-------------------

When one control handler is added to another using v4l2_ctrl_add_handler, then

by default all controls from one are merged to the other. But a subdev might

those low-level controls local to the subdev. You can do this by simply

setting the 'is_private' flag of the control to 1:

.. code-block:: none

	static const struct v4l2_ctrl_config ctrl_private = {

		.ops = &ctrl_custom_ops,

		.id = V4L2_CID_...,

V4L2_CTRL_TYPE_CTRL_CLASS Controls

==================================

----------------------------------

Controls of this type can be used by GUIs to get the name of the control class.

A fully featured GUI can make a dialog with multiple tabs with each tab

Adding Notify Callbacks

=======================

-----------------------

Sometimes the platform or bridge driver needs to be notified when a control

from a sub-device driver changes. You can set a notify callback by calling

this function:

.. code-block:: none

	void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,

		void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);