summaryrefslogtreecommitdiffstats
path: root/include/media
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2016-08-29 17:26:15 -0300
committerMauro Carvalho Chehab <mchehab@s-opensource.com>2016-09-09 09:33:01 -0300
commit2257e180101c910c2d93dd226ab1e500e4a6813c (patch)
tree38c1c4f0f1e5696225487d8c9ea6b7b5f1f96621 /include/media
parent9fa7235f88386c9a5f5013a90f0c6fe8aa6fe828 (diff)
downloadlinux-stable-2257e180101c910c2d93dd226ab1e500e4a6813c.tar.gz
linux-stable-2257e180101c910c2d93dd226ab1e500e4a6813c.tar.bz2
linux-stable-2257e180101c910c2d93dd226ab1e500e4a6813c.zip
[media] v4l2-ctrls: document some extra data structures
The typedefs and a macro are not defined. While here, improve a few bits on the documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'include/media')
-rw-r--r--include/media/v4l2-ctrls.h51
1 files changed, 44 insertions, 7 deletions
diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index 178a88d45aea..b8e043f63825 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -93,6 +93,16 @@ struct v4l2_ctrl_type_ops {
union v4l2_ctrl_ptr ptr);
};
+/**
+ * typedef v4l2_ctrl_notify_fnc - typedef for a notify argument with a function
+ * that should be called when a control value has changed.
+ *
+ * @ctrl: pointer to struct &v4l2_ctrl
+ * @priv: control private data
+ *
+ * This typedef definition is used as an argument to v4l2_ctrl_notify()
+ * and as an argument at struct &v4l2_ctrl_handler.
+ */
typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
/**
@@ -369,17 +379,38 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
* @key: Used by the lock validator if CONFIG_LOCKDEP is set.
* @name: Used by the lock validator if CONFIG_LOCKDEP is set.
*
- * Returns an error if the buckets could not be allocated. This error will
- * also be stored in @hdl->error.
+ * .. attention::
+ *
+ * Never use this call directly, always use the v4l2_ctrl_handler_init()
+ * macro that hides the @key and @name arguments.
*
- * Never use this call directly, always use the v4l2_ctrl_handler_init
- * macro that hides the @key and @name arguments.
+ * Return: returns an error if the buckets could not be allocated. This
+ * error will also be stored in @hdl->error.
*/
int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
unsigned int nr_of_controls_hint,
struct lock_class_key *key, const char *name);
#ifdef CONFIG_LOCKDEP
+
+/**
+ * v4l2_ctrl_handler_init -
+ *
+ * @hdl: The control handler.
+ * @nr_of_controls_hint: A hint of how many controls this handler is
+ * expected to refer to. This is the total number, so including
+ * any inherited controls. It doesn't have to be precise, but if
+ * it is way off, then you either waste memory (too many buckets
+ * are allocated) or the control lookup becomes slower (not enough
+ * buckets are allocated, so there are more slow list lookups).
+ * It will always work, though.
+ *
+ * This helper function creates a static struct &lock_class_key and
+ * calls v4l2_ctrl_handler_init_class(), providing a proper name for the lock
+ * validador.
+ *
+ * Use this helper function to initialize a control handler.
+ */
#define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint) \
( \
({ \
@@ -564,6 +595,13 @@ struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
u32 id, u8 max, u8 def,
const s64 *qmenu_int);
+/**
+ * typedef v4l2_ctrl_filter - Typedef to define the filter function to be
+ * used when adding a control handler.
+ *
+ * @ctrl: pointer to struct &v4l2_ctrl.
+ */
+
typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl);
/**
@@ -635,8 +673,8 @@ void v4l2_ctrl_cluster(unsigned int ncontrols, struct v4l2_ctrl **controls);
* be marked active, and any reads will just return the current value without
* going through g_volatile_ctrl.
*
- * In addition, this function will set the V4L2_CTRL_FLAG_UPDATE flag
- * on the autofoo control and V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
+ * In addition, this function will set the %V4L2_CTRL_FLAG_UPDATE flag
+ * on the autofoo control and %V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
* if autofoo is in auto mode.
*/
void v4l2_ctrl_auto_cluster(unsigned int ncontrols,
@@ -686,7 +724,6 @@ void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
*/
void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed);
-
/**
*__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
*