Lines Matching +full:cluster +full:- +full:mode
1 .. SPDX-License-Identifier: GPL-2.0
7 ------------
31 sub-device drivers.
35 ------------------------
48 Basic usage for V4L2 and sub-device drivers
49 -------------------------------------------
53 .. code-block:: c
55 #include <media/v4l2-ctrls.h>
57 1.1) Add the handler to your driver's top-level struct:
61 .. code-block:: c
71 For sub-device drivers:
73 .. code-block:: c
85 .. code-block:: c
87 v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
97 .. code-block:: c
99 foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;
101 For sub-device drivers:
103 .. code-block:: c
105 foo->sd.ctrl_handler = &foo->ctrl_handler;
109 .. code-block:: c
111 v4l2_ctrl_handler_free(&foo->ctrl_handler);
116 You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`:
118 .. code-block:: c
127 .. code-block:: c
136 .. code-block:: c
146 .. code-block:: c
155 .. code-block:: c
164 .. code-block:: c
167 -2, -1, 0, 1, 2
176 v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
177 v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
179 v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
181 v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops,
185 v4l2_ctrl_new_int_menu(&foo->ctrl_handler, &foo_ctrl_ops,
187 ARRAY_SIZE(exp_bias_qmenu) - 1,
188 ARRAY_SIZE(exp_bias_qmenu) / 2 - 1,
190 v4l2_ctrl_new_std_menu_items(&foo->ctrl_handler, &foo_ctrl_ops,
191 V4L2_CID_TEST_PATTERN, ARRAY_SIZE(test_pattern) - 1, 0,
194 if (foo->ctrl_handler.error) {
195 int err = foo->ctrl_handler.error;
197 v4l2_ctrl_handler_free(&foo->ctrl_handler);
217 integer menu control with driver-specific items in the menu. It differs
219 takes as the last argument an array of signed 64-bit integers that form an
231 set ctrl_handler->error to the error code. If ctrl_handler->error was already
243 .. code-block:: c
245 v4l2_ctrl_handler_setup(&foo->ctrl_handler);
254 .. code-block:: c
262 .. code-block:: c
266 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
268 switch (ctrl->id) {
270 write_reg(0x123, ctrl->val);
273 write_reg(0x456, ctrl->val);
294 Inheriting Sub-device Controls
295 ------------------------------
297 When a sub-device is registered with a V4L2 driver by calling
310 ------------------------
315 .. code-block:: c
327 .. code-block:: c
340 .. code-block:: c
342 &ctrl->val == ctrl->p_new.p_s32
343 &ctrl->cur.val == ctrl->p_cur.p_s32
345 For all other types use ctrl->p_cur.p<something>. Basically the val
350 ctrl->maximum + 1, and are always 0-terminated.
361 strength read-out that changes continuously. In that case you will need to
364 .. code-block:: c
368 switch (ctrl->id) {
370 ctrl->val = read_reg(0x123);
376 controls that need to implement g_volatile_ctrl are read-only controls. If they
382 .. code-block:: c
384 ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);
386 ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
403 .. code-block:: c
414 .. code-block:: c
416 mutex_lock(&state->ctrl_handler.lock);
417 pr_info("String value is '%s'\n", ctrl1->p_cur.p_char);
418 pr_info("Integer value is '%s'\n", ctrl2->cur.val);
419 mutex_unlock(&state->ctrl_handler.lock);
423 -------------
427 .. code-block:: c
436 implementation where you can return -EINVAL if a certain menu item is not
451 ---------------
455 .. code-block:: c
467 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL);
469 The last argument is the priv pointer which can be set to driver-specific
479 ---------------------------
497 will return -EBUSY if an attempt is made to set this control. The
503 ----------------
507 In that case you need to 'cluster' them:
509 .. code-block:: c
519 state->audio_cluster[AUDIO_CL_VOLUME] =
520 v4l2_ctrl_new_std(&state->ctrl_handler, ...);
521 state->audio_cluster[AUDIO_CL_MUTE] =
522 v4l2_ctrl_new_std(&state->ctrl_handler, ...);
523 v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster);
526 cluster is set (or 'gotten', or 'tried'), only the control ops of the first
533 .. code-block:: c
537 struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
539 switch (ctrl->id) {
541 struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE];
543 write_reg(0x123, mute->val ? 0 : ctrl->val);
547 write_reg(0x456, ctrl->val);
555 .. code-block:: c
557 ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
558 ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
560 In practice using cluster arrays like this becomes very tiresome. So instead
563 .. code-block:: c
566 /* audio cluster */
571 The anonymous struct is used to clearly 'cluster' these two control pointers,
575 .. code-block:: c
577 state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
578 state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
579 v4l2_ctrl_cluster(2, &state->volume);
581 And in foo_s_ctrl you can use these pointers directly: state->mute->val.
583 Note that controls in a cluster may be NULL. For example, if for some
586 cluster of 2 controls, of which only 1 is actually instantiated. The
587 only restriction is that the first control of the cluster must always be
588 present, since that is the 'master' control of the cluster. The master
589 control is the one that identifies the cluster and that provides the
590 pointer to the v4l2_ctrl_ops struct that is used for that cluster.
592 Obviously, all controls in the cluster array must be initialized to either
595 In rare cases you might want to know which controls of a cluster actually
597 each control. For example, in the case of a volume/mute cluster the 'is_new'
605 Handling autogain/gain-type Controls with Auto Clusters
606 -------------------------------------------------------
608 A common type of control cluster is one that handles 'auto-foo/foo'-type
614 If the cluster is in automatic mode, then the manual controls should be
617 mode set up automatically.
619 If the cluster is put in manual mode, then the manual controls should become
621 called while in manual mode). In addition just before switching to manual mode
622 the current values as determined by the auto mode are copied as the new manual
631 .. code-block:: c
637 tells the framework which value switches the cluster into manual mode. The
638 last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls.
641 determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow
644 The first control of the cluster is assumed to be the 'auto' control.
651 -------------------------
661 --------------------------------------------
675 manually to add the subdev's control handler (sd->ctrl_handler) to the desired
686 .. code-block:: c
700 .. code-block:: c
709 .. code-block:: c
720 ----------------
730 .. code-block:: c
734 volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);
739 .. code-block:: c
748 .. code-block:: c
761 -------------------------------
765 have low-level controls that make sense for some advanced embedded system, but
766 not when it is used in consumer-level hardware. In that case you want to keep
767 those low-level controls local to the subdev. You can do this by simply
770 .. code-block:: c
782 ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL);
788 ----------------------------------
801 -----------------------
804 from a sub-device driver changes. You can set a notify callback by calling
807 .. code-block:: c
821 ---------------------------------------
823 .. kernel-doc:: include/media/v4l2-ctrls.h