v4l2-controls.rst 28 KB

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