[media] v4l2-ctrls.h: add to device-drivers DocBook

The comments there are using a wrong format. Due to that,
DocBook were unable to parse it.

Fix the tags format, and add it to device-drivers.xml.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

Documentation/DocBook/device-drivers.tmpl

@@ -231,17 +231,13 @@ X!Isound/sound_firmware.c
 !Idrivers/media/dvb-core/dvb_frontend.h
 !Idrivers/media/dvb-core/dvb_math.h
 !Idrivers/media/dvb-core/dvb_ringbuffer.h
+!Iinclude/media/v4l2-ctrls.h
 <!-- FIXME: Removed for now due to document generation inconsistency
-X!Iinclude/media/v4l2-ctrls.h
 X!Iinclude/media/v4l2-dv-timings.h
 X!Iinclude/media/v4l2-event.h
 X!Iinclude/media/v4l2-mediabus.h
 X!Iinclude/media/videobuf2-memops.h
 X!Iinclude/media/videobuf2-core.h
-X!Iinclude/media/lirc.h
-X!Edrivers/media/dvb-core/dvb_demux.c
-X!Idrivers/media/dvb-core/dvbdev.h
-X!Edrivers/media/dvb-core/dvb_net.c
 -->
 
   </chapter>

include/media/v4l2-ctrls.h

@@ -36,7 +36,8 @@ struct v4l2_subscribed_event;
 struct v4l2_fh;
 struct poll_table_struct;
 
-/** union v4l2_ctrl_ptr - A pointer to a control value.
+/**
+ * union v4l2_ctrl_ptr - A pointer to a control value.
  * @p_s32:	Pointer to a 32-bit signed value.
  * @p_s64:	Pointer to a 64-bit signed value.
  * @p_u8:	Pointer to a 8-bit unsigned value.
@@ -55,7 +56,8 @@ union v4l2_ctrl_ptr {
 	void *p;
 };
 
-/** struct v4l2_ctrl_ops - The control operations that the driver has to provide.
+/**
+ * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
  * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
  *		for volatile (and usually read-only) controls such as a control
  *		that returns the current signal strength which changes
@@ -73,7 +75,10 @@ struct v4l2_ctrl_ops {
 	int (*s_ctrl)(struct v4l2_ctrl *ctrl);
 };
 
-/** struct v4l2_ctrl_type_ops - The control type operations that the driver has to provide.
+/**
+ * struct v4l2_ctrl_type_ops - The control type operations that the driver
+ * 			       has to provide.
+ *
  * @equal: return true if both values are equal.
  * @init: initialize the value.
  * @log: log the value.
@@ -92,7 +97,8 @@ struct v4l2_ctrl_type_ops {
 
 typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
 
-/** struct v4l2_ctrl - The control structure.
+/**
+ * struct v4l2_ctrl - The control structure.
  * @node:	The list node.
  * @ev_subs:	The list of control event subscriptions.
  * @handler:	The handler that owns the control.
@@ -210,7 +216,8 @@ struct v4l2_ctrl {
 	union v4l2_ctrl_ptr p_cur;
 };
 
-/** struct v4l2_ctrl_ref - The control reference.
+/**
+ * struct v4l2_ctrl_ref - The control reference.
  * @node:	List node for the sorted list.
  * @next:	Single-link list node for the hash.
  * @ctrl:	The actual control information.
@@ -227,7 +234,8 @@ struct v4l2_ctrl_ref {
 	struct v4l2_ctrl_helper *helper;
 };
 
-/** struct v4l2_ctrl_handler - The control handler keeps track of all the
+/**
+ * struct v4l2_ctrl_handler - The control handler keeps track of all the
  * controls: both the controls owned by the handler and those inherited
  * from other handlers.
  * @_lock:	Default for "lock".
@@ -259,7 +267,8 @@ struct v4l2_ctrl_handler {
 	int error;
 };
 
-/** struct v4l2_ctrl_config - Control configuration structure.
+/**
+ * struct v4l2_ctrl_config - Control configuration structure.
  * @ops:	The control ops.
  * @type_ops:	The control type ops. Only needed for compound controls.
  * @id:	The control ID.
@@ -304,7 +313,8 @@ struct v4l2_ctrl_config {
 	unsigned int is_private:1;
 };
 
-/** v4l2_ctrl_fill() - Fill in the control fields based on the control ID.
+/**
+ * v4l2_ctrl_fill() - Fill in the control fields based on the control ID.
  *
  * This works for all standard V4L2 controls.
  * For non-standard controls it will only fill in the given arguments
@@ -322,7 +332,8 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
 		    s64 *min, s64 *max, u64 *step, s64 *def, u32 *flags);
 
 
-/** v4l2_ctrl_handler_init_class() - Initialize the control handler.
+/**
+ * v4l2_ctrl_handler_init_class() - Initialize the control handler.
  * @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
@@ -361,7 +372,8 @@ int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
 	v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint, NULL, NULL)
 #endif
 
-/** v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
+/**
+ * v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
  * the control list.
  * @hdl:	The control handler.
  *
@@ -369,7 +381,8 @@ int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
  */
 void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl);
 
-/** v4l2_ctrl_lock() - Helper function to lock the handler
+/**
+ * v4l2_ctrl_lock() - Helper function to lock the handler
  * associated with the control.
  * @ctrl:	The control to lock.
  */
@@ -378,7 +391,8 @@ static inline void v4l2_ctrl_lock(struct v4l2_ctrl *ctrl)
 	mutex_lock(ctrl->handler->lock);
 }
 
-/** v4l2_ctrl_unlock() - Helper function to unlock the handler
+/**
+ * v4l2_ctrl_unlock() - Helper function to unlock the handler
  * associated with the control.
  * @ctrl:	The control to unlock.
  */
@@ -387,7 +401,8 @@ static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl)
 	mutex_unlock(ctrl->handler->lock);
 }
 
-/** v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
+/**
+ * v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
  * to the handler to initialize the hardware to the current control values.
  * @hdl:	The control handler.
  *
@@ -397,7 +412,8 @@ static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl)
  */
 int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
 
-/** v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
+/**
+ * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
  * @hdl:	The control handler.
  * @prefix:	The prefix to use when logging the control values. If the
  *		prefix does not end with a space, then ": " will be added
@@ -411,7 +427,8 @@ int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
 void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
 				  const char *prefix);
 
-/** v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
+/**
+ * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
  * control.
  * @hdl:	The control handler.
  * @cfg:	The control's configuration data.
@@ -423,7 +440,8 @@ void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
 struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
 			const struct v4l2_ctrl_config *cfg, void *priv);
 
-/** v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu control.
+/**
+ * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu control.
  * @hdl:	The control handler.
  * @ops:	The control ops.
  * @id:	The control ID.
@@ -444,7 +462,8 @@ struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
 			const struct v4l2_ctrl_ops *ops,
 			u32 id, s64 min, s64 max, u64 step, s64 def);
 
-/** v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2 menu control.
+/**
+ * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2 menu control.
  * @hdl:	The control handler.
  * @ops:	The control ops.
  * @id:	The control ID.
@@ -466,7 +485,8 @@ struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
 			const struct v4l2_ctrl_ops *ops,
 			u32 id, u8 max, u64 mask, u8 def);
 
-/** v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
+/**
+ * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
  * with driver specific menu.
  * @hdl:	The control handler.
  * @ops:	The control ops.
@@ -489,7 +509,8 @@ struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
 			const struct v4l2_ctrl_ops *ops, u32 id, u8 max,
 			u64 mask, u8 def, const char * const *qmenu);
 
-/** v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
+/**
+ * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
  * @hdl:	The control handler.
  * @ops:	The control ops.
  * @id:	The control ID.
@@ -506,7 +527,8 @@ struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
 			const struct v4l2_ctrl_ops *ops,
 			u32 id, u8 max, u8 def, const s64 *qmenu_int);
 
-/** v4l2_ctrl_add_ctrl() - Add a control from another handler to this handler.
+/**
+ * v4l2_ctrl_add_ctrl() - Add a control from another handler to this handler.
  * @hdl:	The control handler.
  * @ctrl:	The control to add.
  *
@@ -517,7 +539,8 @@ struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
 struct v4l2_ctrl *v4l2_ctrl_add_ctrl(struct v4l2_ctrl_handler *hdl,
 					  struct v4l2_ctrl *ctrl);
 
-/** v4l2_ctrl_add_handler() - Add all controls from handler @add to
+/**
+ * v4l2_ctrl_add_handler() - Add all controls from handler @add to
  * handler @hdl.
  * @hdl:	The control handler.
  * @add:	The control handler whose controls you want to add to
@@ -534,7 +557,8 @@ int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
 			  struct v4l2_ctrl_handler *add,
 			  bool (*filter)(const struct v4l2_ctrl *ctrl));
 
-/** v4l2_ctrl_radio_filter() - Standard filter for radio controls.
+/**
+ * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
  * @ctrl:	The control that is filtered.
  *
  * This will return true for any controls that are valid for radio device
@@ -545,14 +569,16 @@ int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
  */
 bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl);
 
-/** v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging to that cluster.
+/**
+ * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging to that cluster.
  * @ncontrols:	The number of controls in this cluster.
  * @controls: 	The cluster control array of size @ncontrols.
  */
 void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls);
 
 
-/** v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging to
+/**
+ * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging to
  * that cluster and set it up for autofoo/foo-type handling.
  * @ncontrols:	The number of controls in this cluster.
  * @controls:	The cluster control array of size @ncontrols. The first control
@@ -585,7 +611,8 @@ void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
 			u8 manual_val, bool set_volatile);
 
 
-/** v4l2_ctrl_find() - Find a control with the given ID.
+/**
+ * v4l2_ctrl_find() - Find a control with the given ID.
  * @hdl:	The control handler.
  * @id:	The control ID to find.
  *
@@ -594,7 +621,8 @@ void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
  */
 struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
 
-/** v4l2_ctrl_activate() - Make the control active or inactive.
+/**
+ * v4l2_ctrl_activate() - Make the control active or inactive.
  * @ctrl:	The control to (de)activate.
  * @active:	True if the control should become active.
  *
@@ -607,7 +635,8 @@ struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
  */
 void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
 
-/** v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
+/**
+ * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
  * @ctrl:	The control to (de)activate.
  * @grabbed:	True if the control should become grabbed.
  *
@@ -623,11 +652,30 @@ 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() */
+/**
+ *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
+ *
+ * @ctrl:	The control to update.
+ * @min:	The control's minimum value.
+ * @max:	The control's maximum value.
+ * @step:	The control's step value
+ * @def:	The control's default value.
+ *
+ * Update the range of a control on the fly. This works for control types
+ * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
+ * @step value is interpreted as a menu_skip_mask.
+ *
+ * An error is returned if one of the range arguments is invalid for this
+ * control type.
+ *
+ * This function assumes that the control handler is not locked and will
+ * take the lock itself.
+ */
 int __v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
 			     s64 min, s64 max, u64 step, s64 def);
 
-/** v4l2_ctrl_modify_range() - Update the range of a control.
+/**
+ * v4l2_ctrl_modify_range() - Update the range of a control.
  * @ctrl:	The control to update.
  * @min:	The control's minimum value.
  * @max:	The control's maximum value.
@@ -656,7 +704,8 @@ static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
 	return rval;
 }
 
-/** v4l2_ctrl_notify() - Function to set a notify callback for a control.
+/**
+ * v4l2_ctrl_notify() - Function to set a notify callback for a control.
  * @ctrl:	The control.
  * @notify:	The callback function.
  * @priv:	The callback private handle, passed as argument to the callback.
@@ -670,7 +719,8 @@ static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
  */
 void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify, void *priv);
 
-/** v4l2_ctrl_get_name() - Get the name of the control
+/**
+ * v4l2_ctrl_get_name() - Get the name of the control
  * @id:		The control ID.
  *
  * This function returns the name of the given control ID or NULL if it isn't
@@ -678,7 +728,8 @@ void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify, void
  */
 const char *v4l2_ctrl_get_name(u32 id);
 
-/** v4l2_ctrl_get_menu() - Get the menu string array of the control
+/**
+ * v4l2_ctrl_get_menu() - Get the menu string array of the control
  * @id:		The control ID.
  *
  * This function returns the NULL-terminated menu string array name of the
@@ -686,7 +737,8 @@ const char *v4l2_ctrl_get_name(u32 id);
  */
 const char * const *v4l2_ctrl_get_menu(u32 id);
 
-/** v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
+/**
+ * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
  * @id:		The control ID.
  * @len:	The size of the integer array.
  *
@@ -695,7 +747,8 @@ const char * const *v4l2_ctrl_get_menu(u32 id);
  */
 const s64 *v4l2_ctrl_get_int_menu(u32 id, u32 *len);
 
-/** v4l2_ctrl_g_ctrl() - Helper function to get the control's value from within a driver.
+/**
+ * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from within a driver.
  * @ctrl:	The control.
  *
  * This returns the control's value safely by going through the control
@@ -706,8 +759,19 @@ const s64 *v4l2_ctrl_get_int_menu(u32 id, u32 *len);
  */
 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
 
-/** __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl(). */
+/**
+ * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
+ * @ctrl:	The control.
+ * @val:	The new value.
+ *
+ * This set the control's new value safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for integer type controls only.
+ */
 int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
+
 /** v4l2_ctrl_s_ctrl() - Helper function to set the control's value from within a driver.
  * @ctrl:	The control.
  * @val:	The new value.
@@ -729,7 +793,9 @@ static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
 	return rval;
 }
 
-/** v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value from within a driver.
+/**
+ * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
+ *	from within a driver.
  * @ctrl:	The control.
  *
  * This returns the control's value safely by going through the control
@@ -740,10 +806,23 @@ static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
  */
 s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl);
 
-/** __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64(). */
+/**
+ * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64().
+ *
+ * @ctrl:	The control.
+ * @val:	The new value.
+ *
+ * This set the control's new value safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for 64-bit integer type controls only.
+ */
 int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val);
 
-/** v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value from within a driver.
+/** v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
+ *	from within a driver.
+ *
  * @ctrl:	The control.
  * @val:	The new value.
  *
@@ -764,10 +843,22 @@ static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
 	return rval;
 }
 
-/** __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string(). */
+/** __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
+ *
+ * @ctrl:	The control.
+ * @s:		The new string.
+ *
+ * This set the control's new string safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for string type controls only.
+ */
 int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s);
 
-/** v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value from within a driver.
+/** v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
+ *	 from within a driver.
+ *
  * @ctrl:	The control.
  * @s:		The new string.
  *