^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) V4L2 Controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) The V4L2 control API seems simple enough, but quickly becomes very hard to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) implement correctly in drivers. But much of the code needed to handle controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) is actually not driver specific and can be moved to the V4L core framework.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) After all, the only part that a driver developer is interested in is:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) 1) How do I add a control?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) 2) How do I set the control's value? (i.e. s_ctrl)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) And occasionally:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) 3) How do I get the control's value? (i.e. g_volatile_ctrl)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) 4) How do I validate the user's proposed control value? (i.e. try_ctrl)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) All the rest is something that can be done centrally.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) The control framework was created in order to implement all the rules of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) V4L2 specification with respect to controls in a central place. And to make
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) life as easy as possible for the driver developer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Note that the control framework relies on the presence of a struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) :c:type:`v4l2_device` for V4L2 drivers and struct v4l2_subdev for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) sub-device drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Objects in the framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) There are two main objects:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) The :c:type:`v4l2_ctrl` object describes the control properties and keeps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) track of the control's value (both the current value and the proposed new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) value).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) :c:type:`v4l2_ctrl_handler` is the object that keeps track of controls. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) maintains a list of v4l2_ctrl objects that it owns and another list of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) references to controls, possibly to controls owned by other handlers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) Basic usage for V4L2 and sub-device drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) -------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) 1) Prepare the driver:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) #include <media/v4l2-ctrls.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) 1.1) Add the handler to your driver's top-level struct:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) For V4L2 drivers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) struct foo_dev {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) struct v4l2_device v4l2_dev;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) struct v4l2_ctrl_handler ctrl_handler;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) For sub-device drivers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) struct foo_dev {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) struct v4l2_subdev sd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) struct v4l2_ctrl_handler ctrl_handler;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) 1.2) Initialize the handler:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) The second argument is a hint telling the function how many controls this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) handler is expected to handle. It will allocate a hashtable based on this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) information. It is a hint only.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) 1.3) Hook the control handler into the driver:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) For V4L2 drivers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) For sub-device drivers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) foo->sd.ctrl_handler = &foo->ctrl_handler;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) 1.4) Clean up the handler at the end:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) v4l2_ctrl_handler_free(&foo->ctrl_handler);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) 2) Add controls:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) const struct v4l2_ctrl_ops *ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) u32 id, s32 min, s32 max, u32 step, s32 def);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) Menu and integer menu controls are added by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) :c:func:`v4l2_ctrl_new_std_menu`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) const struct v4l2_ctrl_ops *ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) u32 id, s32 max, s32 skip_mask, s32 def);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) Menu controls with a driver specific menu are added by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) :c:func:`v4l2_ctrl_new_std_menu_items`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) struct v4l2_ctrl_handler *hdl,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) const struct v4l2_ctrl_ops *ops, u32 id, s32 max,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) s32 skip_mask, s32 def, const char * const *qmenu);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) Standard compound controls can be added by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) :c:func:`v4l2_ctrl_new_std_compound`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) struct v4l2_ctrl *v4l2_ctrl_new_std_compound(struct v4l2_ctrl_handler *hdl,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) const struct v4l2_ctrl_ops *ops, u32 id,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) const union v4l2_ctrl_ptr p_def);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) Integer menu controls with a driver specific menu can be added by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) :c:func:`v4l2_ctrl_new_int_menu`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) const struct v4l2_ctrl_ops *ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) u32 id, s32 max, s32 def, const s64 *qmenu_int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) These functions are typically called right after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) :c:func:`v4l2_ctrl_handler_init`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) static const s64 exp_bias_qmenu[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) -2, -1, 0, 1, 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) static const char * const test_pattern[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) "Disabled",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) "Vertical Bars",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) "Solid Black",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) "Solid White",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) V4L2_CID_BRIGHTNESS, 0, 255, 1, 128);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) V4L2_CID_CONTRAST, 0, 255, 1, 128);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) V4L2_CID_POWER_LINE_FREQUENCY,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) V4L2_CID_POWER_LINE_FREQUENCY_60HZ, 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) V4L2_CID_POWER_LINE_FREQUENCY_DISABLED);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) v4l2_ctrl_new_int_menu(&foo->ctrl_handler, &foo_ctrl_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) V4L2_CID_EXPOSURE_BIAS,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) ARRAY_SIZE(exp_bias_qmenu) - 1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) ARRAY_SIZE(exp_bias_qmenu) / 2 - 1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) exp_bias_qmenu);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) v4l2_ctrl_new_std_menu_items(&foo->ctrl_handler, &foo_ctrl_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) V4L2_CID_TEST_PATTERN, ARRAY_SIZE(test_pattern) - 1, 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) 0, test_pattern);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) if (foo->ctrl_handler.error) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) int err = foo->ctrl_handler.error;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) v4l2_ctrl_handler_free(&foo->ctrl_handler);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) The :c:func:`v4l2_ctrl_new_std` function returns the v4l2_ctrl pointer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) the new control, but if you do not need to access the pointer outside the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) control ops, then there is no need to store it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) The :c:func:`v4l2_ctrl_new_std` function will fill in most fields based on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) the control ID except for the min, max, step and default values. These are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) passed in the last four arguments. These values are driver specific while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) control attributes like type, name, flags are all global. The control's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) current value will be set to the default value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) The :c:func:`v4l2_ctrl_new_std_menu` function is very similar but it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) used for menu controls. There is no min argument since that is always 0 for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) menu controls, and instead of a step there is a skip_mask argument: if bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) X is 1, then menu item X is skipped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) The :c:func:`v4l2_ctrl_new_int_menu` function creates a new standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) integer menu control with driver-specific items in the menu. It differs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) from v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) takes as the last argument an array of signed 64-bit integers that form an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) exact menu item list.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) The :c:func:`v4l2_ctrl_new_std_menu_items` function is very similar to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) driver specific menu for an otherwise standard menu control. A good example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) for this control is the test pattern control for capture/display/sensors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) devices that have the capability to generate test patterns. These test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) patterns are hardware specific, so the contents of the menu will vary from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) device to device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) Note that if something fails, the function will return NULL or an error and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) set ctrl_handler->error to the error code. If ctrl_handler->error was already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) set, then it will just return and do nothing. This is also true for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) v4l2_ctrl_handler_init if it cannot allocate the internal data structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) This makes it easy to init the handler and just add all controls and only check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) the error code at the end. Saves a lot of repetitive error checking.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) It is recommended to add controls in ascending control ID order: it will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) a bit faster that way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) 3) Optionally force initial control setup:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) v4l2_ctrl_handler_setup(&foo->ctrl_handler);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) This will call s_ctrl for all controls unconditionally. Effectively this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) initializes the hardware to the default control values. It is recommended
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) that you do this as this ensures that both the internal data structures and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) the hardware are in sync.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) 4) Finally: implement the :c:type:`v4l2_ctrl_ops`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) static const struct v4l2_ctrl_ops foo_ctrl_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) .s_ctrl = foo_s_ctrl,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) Usually all you need is s_ctrl:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) switch (ctrl->id) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) case V4L2_CID_BRIGHTNESS:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) write_reg(0x123, ctrl->val);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) case V4L2_CID_CONTRAST:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) write_reg(0x456, ctrl->val);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) The control ops are called with the v4l2_ctrl pointer as argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) The new control value has already been validated, so all you need to do is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) to actually update the hardware registers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) You're done! And this is sufficient for most of the drivers we have. No need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) to do any validation of control values, or implement QUERYCTRL, QUERY_EXT_CTRL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) The remainder sections deal with more advanced controls topics and scenarios.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) In practice the basic usage as described above is sufficient for most drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) Inheriting Sub-device Controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) When a sub-device is registered with a V4L2 driver by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) and v4l2_device are set, then the controls of the subdev will become
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) automatically available in the V4L2 driver as well. If the subdev driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) contains controls that already exist in the V4L2 driver, then those will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) skipped (so a V4L2 driver can always override a subdev control).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) What happens here is that v4l2_device_register_subdev() calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) v4l2_ctrl_add_handler() adding the controls of the subdev to the controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) of v4l2_device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) Accessing Control Values
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) The following union is used inside the control framework to access control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) values:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) union v4l2_ctrl_ptr {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) s32 *p_s32;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) s64 *p_s64;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) char *p_char;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) void *p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) The v4l2_ctrl struct contains these fields that can be used to access both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) current and new values:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) s32 val;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) s32 val;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) } cur;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) union v4l2_ctrl_ptr p_new;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) union v4l2_ctrl_ptr p_cur;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) If the control has a simple s32 type type, then:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) &ctrl->val == ctrl->p_new.p_s32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) &ctrl->cur.val == ctrl->p_cur.p_s32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) For all other types use ctrl->p_cur.p<something>. Basically the val
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) and cur.val fields can be considered an alias since these are used so often.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) Within the control ops you can freely use these. The val and cur.val speak for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) themselves. The p_char pointers point to character buffers of length
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) ctrl->maximum + 1, and are always 0-terminated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) Unless the control is marked volatile the p_cur field points to the the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) current cached control value. When you create a new control this value is made
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) identical to the default value. After calling v4l2_ctrl_handler_setup() this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) value is passed to the hardware. It is generally a good idea to call this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) Whenever a new value is set that new value is automatically cached. This means
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) that most drivers do not need to implement the g_volatile_ctrl() op. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) exception is for controls that return a volatile register such as a signal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) strength read-out that changes continuously. In that case you will need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) implement g_volatile_ctrl like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) switch (ctrl->id) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) case V4L2_CID_BRIGHTNESS:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) ctrl->val = read_reg(0x123);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) Note that you use the 'new value' union as well in g_volatile_ctrl. In general
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) controls that need to implement g_volatile_ctrl are read-only controls. If they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) are not, a V4L2_EVENT_CTRL_CH_VALUE will not be generated when the control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) if (ctrl)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) For try/s_ctrl the new values (i.e. as passed by the user) are filled in and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) contains the current value, which you can use (but not change!) as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) If s_ctrl returns 0 (OK), then the control framework will copy the new final
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) values to the 'cur' union.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) While in g_volatile/s/try_ctrl you can access the value of all controls owned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) by the same handler since the handler's lock is held. If you need to access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) the value of controls owned by other handlers, then you have to be very careful
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) not to introduce deadlocks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) Outside of the control ops you have to go through to helper functions to get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) or set a single control value safely in your driver:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) will result in a deadlock since these helpers lock the handler as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) You can also take the handler lock yourself:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) mutex_lock(&state->ctrl_handler.lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) pr_info("String value is '%s'\n", ctrl1->p_cur.p_char);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) pr_info("Integer value is '%s'\n", ctrl2->cur.val);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) mutex_unlock(&state->ctrl_handler.lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) Menu Controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) The v4l2_ctrl struct contains this union:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) union {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) u32 step;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) u32 menu_skip_mask;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) For menu controls menu_skip_mask is used. What it does is that it allows you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) implementation where you can return -EINVAL if a certain menu item is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) menu controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) A good example is the MPEG Audio Layer II Bitrate menu control where the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) menu is a list of standardized possible bitrates. But in practice hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) implementations will only support a subset of those. By setting the skip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) mask you can tell the framework which menu items should be skipped. Setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) it to 0 means that all menu items are supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) You set this mask either through the v4l2_ctrl_config struct for a custom
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) control, or by calling v4l2_ctrl_new_std_menu().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) Custom Controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) Driver specific controls can be created using v4l2_ctrl_new_custom():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) static const struct v4l2_ctrl_config ctrl_filter = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) .ops = &ctrl_custom_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) .id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) .name = "Spatial Filter",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) .type = V4L2_CTRL_TYPE_INTEGER,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) .flags = V4L2_CTRL_FLAG_SLIDER,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) .max = 15,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) .step = 1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) The last argument is the priv pointer which can be set to driver-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) private data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) The v4l2_ctrl_config struct also has a field to set the is_private flag.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) If the name field is not set, then the framework will assume this is a standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) control and will fill in the name, type and flags fields accordingly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) Active and Grabbed Controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) If you get more complex relationships between controls, then you may have to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) activate and deactivate controls. For example, if the Chroma AGC control is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) on, then the Chroma Gain control is inactive. That is, you may set it, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) the value will not be used by the hardware as long as the automatic gain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) control is on. Typically user interfaces can disable such input fields.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) You can set the 'active' status using v4l2_ctrl_activate(). By default all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) controls are active. Note that the framework does not check for this flag.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) It is meant purely for GUIs. The function is typically called from within
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) s_ctrl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) The other flag is the 'grabbed' flag. A grabbed control means that you cannot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) change it because it is in use by some resource. Typical examples are MPEG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) bitrate controls that cannot be changed while capturing is in progress.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) will return -EBUSY if an attempt is made to set this control. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) v4l2_ctrl_grab() function is typically called from the driver when it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) starts or stops streaming.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) Control Clusters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) By default all controls are independent from the others. But in more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) complex scenarios you can get dependencies from one control to another.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) In that case you need to 'cluster' them:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) struct foo {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) struct v4l2_ctrl_handler ctrl_handler;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) #define AUDIO_CL_VOLUME (0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) #define AUDIO_CL_MUTE (1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) struct v4l2_ctrl *audio_cluster[2];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) state->audio_cluster[AUDIO_CL_VOLUME] =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) v4l2_ctrl_new_std(&state->ctrl_handler, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) state->audio_cluster[AUDIO_CL_MUTE] =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) v4l2_ctrl_new_std(&state->ctrl_handler, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) From now on whenever one or more of the controls belonging to the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) cluster is set (or 'gotten', or 'tried'), only the control ops of the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) control ('volume' in this example) is called. You effectively create a new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) composite control. Similar to how a 'struct' works in C.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) all two controls belonging to the audio_cluster:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) switch (ctrl->id) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) case V4L2_CID_AUDIO_VOLUME: {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) write_reg(0x123, mute->val ? 0 : ctrl->val);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) case V4L2_CID_CONTRAST:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) write_reg(0x456, ctrl->val);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) In the example above the following are equivalent for the VOLUME case:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) In practice using cluster arrays like this becomes very tiresome. So instead
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) the following equivalent method is used:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) /* audio cluster */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) struct v4l2_ctrl *volume;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) struct v4l2_ctrl *mute;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) The anonymous struct is used to clearly 'cluster' these two control pointers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) but it serves no other purpose. The effect is the same as creating an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) array with two control pointers. So you can just do:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) v4l2_ctrl_cluster(2, &state->volume);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) And in foo_s_ctrl you can use these pointers directly: state->mute->val.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) Note that controls in a cluster may be NULL. For example, if for some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) reason mute was never added (because the hardware doesn't support that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) particular feature), then mute will be NULL. So in that case we have a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) cluster of 2 controls, of which only 1 is actually instantiated. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) only restriction is that the first control of the cluster must always be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) present, since that is the 'master' control of the cluster. The master
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) control is the one that identifies the cluster and that provides the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) pointer to the v4l2_ctrl_ops struct that is used for that cluster.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) Obviously, all controls in the cluster array must be initialized to either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) a valid control or to NULL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) In rare cases you might want to know which controls of a cluster actually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) were set explicitly by the user. For this you can check the 'is_new' flag of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) each control. For example, in the case of a volume/mute cluster the 'is_new'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) flag of the mute control would be set if the user called VIDIOC_S_CTRL for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) mute only. If the user would call VIDIOC_S_EXT_CTRLS for both mute and volume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) controls, then the 'is_new' flag would be 1 for both controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) Handling autogain/gain-type Controls with Auto Clusters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) -------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) A common type of control cluster is one that handles 'auto-foo/foo'-type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) controls. Typical examples are autogain/gain, autoexposure/exposure,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) autowhitebalance/red balance/blue balance. In all cases you have one control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) that determines whether another control is handled automatically by the hardware,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) or whether it is under manual control from the user.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) If the cluster is in automatic mode, then the manual controls should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) marked inactive and volatile. When the volatile controls are read the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) g_volatile_ctrl operation should return the value that the hardware's automatic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) mode set up automatically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) If the cluster is put in manual mode, then the manual controls should become
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) active again and the volatile flag is cleared (so g_volatile_ctrl is no longer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) called while in manual mode). In addition just before switching to manual mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) the current values as determined by the auto mode are copied as the new manual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) changing that control affects the control flags of the manual controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) In order to simplify this a special variation of v4l2_ctrl_cluster was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) introduced:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) u8 manual_val, bool set_volatile);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) The first two arguments are identical to v4l2_ctrl_cluster. The third argument
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) tells the framework which value switches the cluster into manual mode. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) last argument will optionally set V4L2_CTRL_FLAG_VOLATILE for the non-auto controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) If it is false, then the manual controls are never volatile. You would typically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) use that if the hardware does not give you the option to read back to values as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) determined by the auto mode (e.g. if autogain is on, the hardware doesn't allow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) you to obtain the current gain value).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) The first control of the cluster is assumed to be the 'auto' control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) Using this function will ensure that you don't need to handle all the complex
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) flag and volatile handling.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) VIDIOC_LOG_STATUS Support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) This ioctl allow you to dump the current status of a driver to the kernel log.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) value of the controls owned by the given handler to the log. You can supply a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) prefix as well. If the prefix didn't end with a space, then ': ' will be added
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) for you.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) Different Handlers for Different Video Nodes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) --------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) Usually the V4L2 driver has just one control handler that is global for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) all video nodes. But you can also specify different control handlers for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665) different video nodes. You can do that by manually setting the ctrl_handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) field of struct video_device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) That is no problem if there are no subdevs involved but if there are, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) you need to block the automatic merging of subdev controls to the global
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) control handler. You do that by simply setting the ctrl_handler field in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) merge subdev controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) After each subdev was added, you will then have to call v4l2_ctrl_add_handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) manually to add the subdev's control handler (sd->ctrl_handler) to the desired
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) control handler. This control handler may be specific to the video_device or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) for a subset of video_device's. For example: the radio device nodes only have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) audio controls, while the video and vbi device nodes share the same control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) handler for the audio and video controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) If you want to have one handler (e.g. for a radio device node) have a subset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) of another handler (e.g. for a video device node), then you should first add
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) the controls to the first handler, add the other controls to the second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) handler and finally add the first handler to the second. For example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler, NULL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) The last argument to v4l2_ctrl_add_handler() is a filter function that allows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) you to filter which controls will be added. Set it to NULL if you want to add
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) all controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) Or you can add specific controls to a handler:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704) v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) What you should not do is make two identical controls for two handlers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707) For example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) This would be bad since muting the radio would not change the video mute
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) control. The rule is to have one control for each hardware 'knob' that you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) can twiddle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) Finding Controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) Normally you have created the controls yourself and you can store the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) v4l2_ctrl pointer into your own struct.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725) But sometimes you need to find a control from another handler that you do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) not own. For example, if you have to find a volume control from a subdev.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) You can do that by calling v4l2_ctrl_find:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) struct v4l2_ctrl *volume;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) Since v4l2_ctrl_find will lock the handler you have to be careful where you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) use it. For example, this is not a good idea:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741) struct v4l2_ctrl_handler ctrl_handler;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) ...and in video_ops.s_ctrl:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) case V4L2_CID_BRIGHTNESS:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) attempting to find another control from the same handler will deadlock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) It is recommended not to use this function from inside the control ops.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) Preventing Controls inheritance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763) When one control handler is added to another using v4l2_ctrl_add_handler, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) by default all controls from one are merged to the other. But a subdev might
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) have low-level controls that make sense for some advanced embedded system, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) not when it is used in consumer-level hardware. In that case you want to keep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) those low-level controls local to the subdev. You can do this by simply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) setting the 'is_private' flag of the control to 1:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772) static const struct v4l2_ctrl_config ctrl_private = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) .ops = &ctrl_custom_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774) .id = V4L2_CID_...,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) .name = "Some Private Control",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776) .type = V4L2_CTRL_TYPE_INTEGER,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) .max = 15,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) .step = 1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) .is_private = 1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) These controls will now be skipped when v4l2_ctrl_add_handler is called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787) V4L2_CTRL_TYPE_CTRL_CLASS Controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) Controls of this type can be used by GUIs to get the name of the control class.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791) A fully featured GUI can make a dialog with multiple tabs with each tab
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) containing the controls belonging to a particular control class. The name of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) each tab can be found by querying a special control with ID <control class | 1>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) Drivers do not have to care about this. The framework will automatically add
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) a control of this type whenever the first control belonging to a new control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) class is added.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800) Adding Notify Callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) Sometimes the platform or bridge driver needs to be notified when a control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) from a sub-device driver changes. You can set a notify callback by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) this function:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809) void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) Whenever the give control changes value the notify callback will be called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813) with a pointer to the control and the priv pointer that was passed with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) v4l2_ctrl_notify. Note that the control's handler lock is held when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815) notify function is called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) There can be only one notify function per control handler. Any attempt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) to set another notify function will cause a WARN_ON.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820) v4l2_ctrl functions and data structures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) ---------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) .. kernel-doc:: include/media/v4l2-ctrls.h
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags