dynctrl.txt

Dynamic controls API
--------------------

This file documents the dynamic controls API and its associated ioctls. Please
keep in mind that this is a work in progress. The API can change at any time,
and the documentation is probably unaccurate. Questions and remarks can be
sent to the Linux UVC development mailing list at linux-uvc-devel@lists.berlios.de.

1. Introduction

The UVC specification allows for vendor-specific extensions through extension
units. With more and more products being UVC compliant, the number of controls
defined through extension units is expected to grow rapidly.

The Linux UVC driver supports extension unit controls (XU controls) through a
hardcode control list. This implementation requires vendors to submit a list
of their controls to the Linux UVC project, and wastes kernel memory to store
control information that are useful for a small number of cameras only. The
dynamic controls API aims at solving those issues.

The basic idea is to provide a userspace API through which applications can
add control definitions at runtime.

2. Security

The API doesn't currently provide any access control facility. Any application
allowed to access a UVC device will be able to add control definitions with no
limit. Suggestions are welcome.

3. IOCTLs

---- UVCIOC_CTRL_ADD - Define a vendor UVC control ----

Argument: struct uvc_xu_control_info

Description:
	This ioctl allows userspace applications to add an Extension Unit UVC
	control definition to the driver.

Return value:
	On success 0 is returned. On error -1 is returned and errno is set
	appropriately.

	ENOMEM
		Not enough memory to perform the operation.
	EEXIST
		Control is already defined.

Data types:
	* struct uvc_xu_control_info

	__u8	entity[16]	Extension unit GUID
	__u8	index		Control index in the unit's bmControl bit field
	__u8	selector	Control selector
	__u16	size		Control size (in bytes)
	__u32	flags		See below

	* struct uvc_xu_control_info flags field

	UVC_CONTROL_SET_CUR	Control is writable.
	UVC_CONTROL_GET_CUR	Control is readable.
	UVC_CONTROL_GET_MIN	Control supports GET MIN queries.
	UVC_CONTROL_GET_MAX	Control supports GET MAX queries.
	UVC_CONTROL_GET_RES	Control supports GET RES queries.
	UVC_CONTROL_GET_DEF	Control supports GET DEF queries.
	UVC_CONTROL_RESTORE	Control should be restored when resuming from
				sleep.


---- UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control ----

Argument: struct uvc_xu_control_mapping

Description:
	This ioctl creates a mapping between a UVC control or part of a UVC
	control and a V4L2 control. Once mappings are defined, userspace
	applications can access vendor-defined UVC control through the V4L2
	control API.

	To create a mapping, applications fill the uvc_xu_control_mapping
	structure with information about an existing UVC control defined with
	UVCIOC_CTRL_ADD and a new V4L2 control.

	A UVC control can be mapped to several V4L2 controls. For instance,
	a UVC pan/tilt control could be mapped to separate pan and tilt V4L2
	controls. The UVC control is divided into non overlapping fields using
	the 'size' and 'offset' fields and are then independantly mapped to
	V4L2 control.

	For signed integer V4L2 controls the data_type field should be set to
	UVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored.

Return value:
	On success 0 is returned. On error -1 is returned and errno is set
	appropriately.

	ENOMEM
		Not enough memory to perform the operation.
	EINVAL
		No such UVC control.
	EOVERFLOW
		The requested offset and size would overflow the UVC control.
	EEXIST
		Mapping already exists.

Data types:
	* struct uvc_xu_control_mapping

	__u32	id		V4L2 control identifier
	__u8	name[32]	V4L2 control name
	__u8	entity[16]	UVC extension unit GUID
	__u8	selector	UVC control selector
	__u8	size		V4L2 control size (in bits)
	__u8	offset		V4L2 control offset (in bits)
	enum v4l2_ctrl_type
		v4l2_type	V4L2 control type
	enum uvc_control_data_type
		data_type	UVC control data type

	* enum uvc_control_data_type

	UVC_CTRL_DATA_TYPE_RAW		Raw control (byte array)
	UVC_CTRL_DATA_TYPE_SIGNED	Signed integer
	UVC_CTRL_DATA_TYPE_UNSIGNED	Unsigned integer
	UVC_CTRL_DATA_TYPE_BOOLEAN	Boolean
	UVC_CTRL_DATA_TYPE_ENUM		Enumeration
	UVC_CTRL_DATA_TYPE_BITMASK	Bitmask


---- UVCIOC_CTRL_GET - Get the value of a UVC control ----

Argument: struct uvc_xu_control

Description:
	This ioctl retrieves the current value of the UVC control identified
	by its extension unit ID and control selector. Applications must set
	the control size and provide a pointer to a writable buffer big enough
	to fit the data.

	Data are taken directly from the device without any driver-side
	processing. Applications are responsible for data buffer formatting,
	including little-endian/big-endian conversion.

Return value:
	On success 0 is returned. On error -1 is returned and errno is set
	appropriately.

	EINVAL
		No such UVC control, or control isn't readable.
	EFAULT
		data references an inaccessible memory area.

Data types:
	* struct uvc_xu_control

	__u8	unit		Extension unit ID
	__u8	selector	Control selector
	__u16	size		Control data size (in bytes)
	__u8	*data		Control value


---- UVCIOC_CTRL_SET - Set the value of a UVC control ----

Argument: struct uvc_xu_control

Description:
	This ioctl sets the value of the UVC control identified by its
	extension unit ID and control selector. Applications must set the
	control size and provide a pointer to a readable buffer containing the
	data.

	Data are passed directly to the device without any driver-side
	processing. Applications are responsible for data buffer formatting,
	including little-endian/big-endian conversion.

Return value:
	On success 0 is returned. On error -1 is returned and errno is set
	appropriately.

	EINVAL
		No such UVC control, or control isn't writable.
	EFAULT
		data references an inaccessible memory area.

Data types:
	* struct uvc_xu_control

	See UVCIOC_CTRL_GET