Documentation/video4linux/v4l2-controls.txt

25 for V4L2 drivers and struct v4l2_subdev for sub-device drivers.
41 Basic usage for V4L2 and sub-device drivers
46 1.1) Add the handler to your driver's top-level struct:
54 	struct foo_dev *foo;
58 	v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
76 	foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;
78   Where foo->v4l2_dev is of type struct v4l2_device.
85 1.3.2) For sub-device drivers do this:
95 	foo->sd.ctrl_handler = &foo->ctrl_handler;
97   Where foo->sd is of type struct v4l2_subdev.
116 	v4l2_ctrl_handler_free(&foo->ctrl_handler);
121 You add non-menu controls by calling v4l2_ctrl_new_std:
135 	v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
136 	v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
138 	v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
140 	v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops,
145 	if (foo->ctrl_handler.error) {
146 		int err = foo->ctrl_handler.error;
148 		v4l2_ctrl_handler_free(&foo->ctrl_handler);
168 set ctrl_handler->error to the error code. If ctrl_handler->error was already
180 	v4l2_ctrl_handler_setup(&foo->ctrl_handler);
197 		struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
199 		switch (ctrl->id) {
201 			write_reg(0x123, ctrl->val);
204 			write_reg(0x456, ctrl->val);
230 When a sub-device is registered with a V4L2 driver by calling
263 ctrl->maximum + 1, and are always 0-terminated.
273 strength read-out that changes continuously. In that case you will need to
278 		switch (ctrl->id) {
280 			ctrl->val = read_reg(0x123);
286 controls that need to implement g_volatile_ctrl are read-only controls.
290 	ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);
292 		ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
318 	mutex_lock(&state->ctrl_handler.lock);
319 	printk(KERN_INFO "String value is '%s'\n", ctrl1->cur.string);
320 	printk(KERN_INFO "Integer value is '%s'\n", ctrl2->cur.val);
321 	mutex_unlock(&state->ctrl_handler.lock);
336 implementation where you can return -EINVAL if a certain menu item is not
365 	ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL);
367 The last argument is the priv pointer which can be set to driver-specific
395 will return -EBUSY if an attempt is made to set this control. The
407 	struct foo {
415 	state->audio_cluster[AUDIO_CL_VOLUME] =
416 		v4l2_ctrl_new_std(&state->ctrl_handler, ...);
417 	state->audio_cluster[AUDIO_CL_MUTE] =
418 		v4l2_ctrl_new_std(&state->ctrl_handler, ...);
419 	v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster);
431 		struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
433 		switch (ctrl->id) {
435 			struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE];
437 			write_reg(0x123, mute->val ? 0 : ctrl->val);
441 			write_reg(0x456, ctrl->val);
449 	ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
450 	ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
465 	state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
466 	state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
467 	v4l2_ctrl_cluster(2, &state->volume);
469 And in foo_s_ctrl you can use these pointers directly: state->mute->val.
493 Handling autogain/gain-type Controls with Auto Clusters
496 A common type of control cluster is one that handles 'auto-foo/foo'-type
524 last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls.
541 value of the controls owned by the given handler to the log. You can supply a
561 manually to add the subdev's control handler (sd->ctrl_handler) to the desired
609 	volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);
636 have low-level controls that make sense for some advanced embedded system, but
637 not when it is used in consumer-level hardware. In that case you want to keep
638 those low-level controls local to the subdev. You can do this by simply
651 	ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL);