Documentation/driver-api/media/v4l2-controls.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/media/v4l2-controls.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/media/v4l2-controls.rst
Extension
.rst
Size
28186 bytes
Lines
821
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct foo_dev {
		...
		struct v4l2_device v4l2_dev;
		...
		struct v4l2_ctrl_handler ctrl_handler;
		...
	};

For sub-device drivers:

.. code-block:: c

	struct foo_dev {
		...
		struct v4l2_subdev sd;
		...
		struct v4l2_ctrl_handler ctrl_handler;
		...
	};

1.2) Initialize the handler:

.. code-block:: c

	v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);

The second argument is a hint telling the function how many controls this
handler is expected to handle. It will allocate a hashtable based on this
information. It is a hint only.

1.3) Hook the control handler into the driver:

For V4L2 drivers:

.. code-block:: c

	foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;

For sub-device drivers:

.. code-block:: c

	foo->sd.ctrl_handler = &foo->ctrl_handler;

1.4) Clean up the handler at the end:

.. code-block:: c

	v4l2_ctrl_handler_free(&foo->ctrl_handler);

:c:func:`v4l2_ctrl_handler_free` does not touch the handler's ``error`` field.

2) Add controls:

You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`:

.. code-block:: c

	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
:c:func:`v4l2_ctrl_new_std_menu`:

.. code-block:: c

	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);

Annotation

Implementation Notes