Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 8c2721d5 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

[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: default avatarMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 2a86e373

Documentation/DocBook/device-drivers.tmpl

+1 −5
Original line number Diff line number Diff line
@@ -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

+551 −460
Original line number Diff line number Diff line
@@ -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.

 *