[linux-2.6-block.git] / Documentation / video4linux / uvcvideo.txt

Linux USB Video Class (UVC) driver
==================================

This file documents some driver-specific aspects of the UVC driver, such as
driver-specific ioctls and implementation notes.

Questions and remarks can be sent to the Linux UVC development mailing list at
linux-uvc-devel@lists.berlios.de.


Extension Unit (XU) support
---------------------------

1. Introduction

The UVC specification allows for vendor-specific extensions through extension
units (XUs). The Linux UVC driver supports extension unit controls (XU controls)
through two separate mechanisms:

  - through mappings of XU controls to V4L2 controls
  - through a driver-specific ioctl interface

The first one allows generic V4L2 applications to use XU controls by mapping
certain XU controls onto V4L2 controls, which then show up during ordinary
control enumeration.

The second mechanism requires uvcvideo-specific knowledge for the application to
access XU controls but exposes the entire UVC XU concept to user space for
maximum flexibility.

Both mechanisms complement each other and are described in more detail below.


2. Control mappings

The UVC driver provides an API for user space applications to define so-called
control mappings at runtime. These allow for individual XU controls or byte
ranges thereof to be mapped to new V4L2 controls. Such controls appear and
function exactly like normal V4L2 controls (i.e. the stock controls, such as
brightness, contrast, etc.). However, reading or writing of such a V4L2 controls
triggers a read or write of the associated XU control.

The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP.
Previous driver versions (before 0.2.0) required another ioctl to be used
beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver.
This is no longer necessary as newer uvcvideo versions query the information
directly from the device.

For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled
"IOCTL reference" below.


3. Driver specific XU control interface

For applications that need to access XU controls directly, e.g. for testing
purposes, firmware upload, or accessing binary controls, a second mechanism to
access XU controls is provided in the form of a driver-specific ioctl, namely
UVCIOC_CTRL_QUERY.

A call to this ioctl allows applications to send queries to the UVC driver that
directly map to the low-level UVC control requests.

In order to make such a request the UVC unit ID of the control's extension unit
and the control selector need to be known. This information either needs to be
hardcoded in the application or queried using other ways such as by parsing the
UVC descriptor or, if available, using the media controller API to enumerate a
device's entities.

Unless the control size is already known it is necessary to first make a
UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer
and set the buffer size to the correct value. Similarly, to find out whether
UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a
UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET
supported) of the resulting byte indicate which requests are valid.

With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and
UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a
subset of the former ioctl. For the time being they are still supported but
application developers are encouraged to use UVCIOC_CTRL_QUERY instead.

For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled
"IOCTL reference" below.


4. Security

The API doesn't currently provide a fine-grained access control facility. The
UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions.

Suggestions on how to improve this are welcome.


5. Debugging

In order to debug problems related to XU controls or controls in general it is
recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'.
This causes extra output to be written into the system log.


6. IOCTL reference

---- 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 independently 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.
	EPERM
		Insufficient privileges (super user privileges are required).
	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
	struct uvc_menu_info
		*menu_info	Array of menu entries (for menu controls only)
	__u32	menu_count	Number of menu entries (for menu controls only)

	* struct uvc_menu_info

	__u32	value		Menu entry value used by the device
	__u8	name[32]	Menu entry name


	* 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_QUERY - Query a UVC XU control ----

Argument: struct uvc_xu_control_query

Description:
	This ioctl queries a UVC XU control identified by its extension unit ID
	and control selector.

	There are a number of different queries available that closely
	correspond to the low-level control requests described in the UVC
	specification. These requests are:

	UVC_GET_CUR
		Obtain the current value of the control.
	UVC_GET_MIN
		Obtain the minimum value of the control.
	UVC_GET_MAX
		Obtain the maximum value of the control.
	UVC_GET_DEF
		Obtain the default value of the control.
	UVC_GET_RES
		Query the resolution of the control, i.e. the step size of the
		allowed control values.
	UVC_GET_LEN
		Query the size of the control in bytes.
	UVC_GET_INFO
		Query the control information bitmap, which indicates whether
		get/set requests are supported.
	UVC_SET_CUR
		Update the value of the control.

	Applications must set the 'size' field to the correct length for the
	control. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, for
	which the size must be set to 2 and 1, respectively. The 'data' field
	must point to a valid writable buffer big enough to hold the indicated
	number of data bytes.

	Data is copied directly from the device without any driver-side
	processing. Applications are responsible for data buffer formatting,
	including little-endian/big-endian conversion. This is particularly
	important for the result of the UVC_GET_LEN requests, which is always
	returned as a little-endian 16-bit integer by the device.

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

	ENOENT
		The device does not support the given control or the specified
		extension unit could not be found.
	ENOBUFS
		The specified buffer size is incorrect (too big or too small).
	EINVAL
		An invalid request code was passed.
	EBADRQC
		The given request is not supported by the given control.
	EFAULT
		The data pointer references an inaccessible memory area.

Data types:
	* struct uvc_xu_control_query

	__u8	unit		Extension unit ID
	__u8	selector	Control selector
	__u8	query		Request code to send to the device
	__u16	size		Control data size (in bytes)
	__u8	*data		Control value
Commit	Line	Data
fb08a5cd MR	1	Linux USB Video Class (UVC) driver
	2	==================================
	3
	4	This file documents some driver-specific aspects of the UVC driver, such as
	5	driver-specific ioctls and implementation notes.
	6
	7	Questions and remarks can be sent to the Linux UVC development mailing list at
	8	linux-uvc-devel@lists.berlios.de.
	9
	10
	11	Extension Unit (XU) support
	12	---------------------------
	13
	14	1. Introduction
	15
	16	The UVC specification allows for vendor-specific extensions through extension
	17	units (XUs). The Linux UVC driver supports extension unit controls (XU controls)
	18	through two separate mechanisms:
	19
	20	- through mappings of XU controls to V4L2 controls
	21	- through a driver-specific ioctl interface
	22
	23	The first one allows generic V4L2 applications to use XU controls by mapping
	24	certain XU controls onto V4L2 controls, which then show up during ordinary
	25	control enumeration.
	26
	27	The second mechanism requires uvcvideo-specific knowledge for the application to
	28	access XU controls but exposes the entire UVC XU concept to user space for
	29	maximum flexibility.
	30
	31	Both mechanisms complement each other and are described in more detail below.
	32
	33
	34	2. Control mappings
	35
	36	The UVC driver provides an API for user space applications to define so-called
	37	control mappings at runtime. These allow for individual XU controls or byte
	38	ranges thereof to be mapped to new V4L2 controls. Such controls appear and
	39	function exactly like normal V4L2 controls (i.e. the stock controls, such as
	40	brightness, contrast, etc.). However, reading or writing of such a V4L2 controls
	41	triggers a read or write of the associated XU control.
	42
	43	The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP.
	44	Previous driver versions (before 0.2.0) required another ioctl to be used
	45	beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver.
	46	This is no longer necessary as newer uvcvideo versions query the information
	47	directly from the device.
	48
	49	For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled
	50	"IOCTL reference" below.
	51
	52
	53	3. Driver specific XU control interface
	54
	55	For applications that need to access XU controls directly, e.g. for testing
	56	purposes, firmware upload, or accessing binary controls, a second mechanism to
	57	access XU controls is provided in the form of a driver-specific ioctl, namely
	58	UVCIOC_CTRL_QUERY.
	59
	60	A call to this ioctl allows applications to send queries to the UVC driver that
	61	directly map to the low-level UVC control requests.
	62
	63	In order to make such a request the UVC unit ID of the control's extension unit
	64	and the control selector need to be known. This information either needs to be
65	hardcoded in the application or queried using other ways such as by parsing the
66	UVC descriptor or, if available, using the media controller API to enumerate a
67	device's entities.
68
69	Unless the control size is already known it is necessary to first make a
70	UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer
71	and set the buffer size to the correct value. Similarly, to find out whether
72	UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a
73	UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET
74	supported) of the resulting byte indicate which requests are valid.
75
76	With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and
77	UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a
78	subset of the former ioctl. For the time being they are still supported but
79	application developers are encouraged to use UVCIOC_CTRL_QUERY instead.
80
81	For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled
82	"IOCTL reference" below.
83
84
85	4. Security
86
87	The API doesn't currently provide a fine-grained access control facility. The
88	UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions.
89
90	Suggestions on how to improve this are welcome.
91
92
93	5. Debugging
94
95	In order to debug problems related to XU controls or controls in general it is
96	recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'.
97	This causes extra output to be written into the system log.
98
99
100	6. IOCTL reference
101
102	---- UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control ----
103
104	Argument: struct uvc_xu_control_mapping
105
106	Description:
107	This ioctl creates a mapping between a UVC control or part of a UVC
108	control and a V4L2 control. Once mappings are defined, userspace
109	applications can access vendor-defined UVC control through the V4L2
110	control API.
111
112	To create a mapping, applications fill the uvc_xu_control_mapping
113	structure with information about an existing UVC control defined with
114	UVCIOC_CTRL_ADD and a new V4L2 control.
115
116	A UVC control can be mapped to several V4L2 controls. For instance,
117	a UVC pan/tilt control could be mapped to separate pan and tilt V4L2
118	controls. The UVC control is divided into non overlapping fields using
40e47125	119	the 'size' and 'offset' fields and are then independently mapped to
fb08a5cd MR	120	V4L2 control.
	121
	122	For signed integer V4L2 controls the data_type field should be set to
	123	UVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored.
	124
	125	Return value:
	126	On success 0 is returned. On error -1 is returned and errno is set
	127	appropriately.
	128
	129	ENOMEM
	130	Not enough memory to perform the operation.
	131	EPERM
	132	Insufficient privileges (super user privileges are required).
	133	EINVAL
	134	No such UVC control.
	135	EOVERFLOW
	136	The requested offset and size would overflow the UVC control.
	137	EEXIST
	138	Mapping already exists.
	139
	140	Data types:
	141	* struct uvc_xu_control_mapping
	142
	143	__u32 id V4L2 control identifier
	144	__u8 name[32] V4L2 control name
	145	__u8 entity[16] UVC extension unit GUID
	146	__u8 selector UVC control selector
	147	__u8 size V4L2 control size (in bits)
	148	__u8 offset V4L2 control offset (in bits)
	149	enum v4l2_ctrl_type
	150	v4l2_type V4L2 control type
	151	enum uvc_control_data_type
	152	data_type UVC control data type
	153	struct uvc_menu_info
	154	*menu_info Array of menu entries (for menu controls only)
	155	__u32 menu_count Number of menu entries (for menu controls only)
	156
	157	* struct uvc_menu_info
	158
	159	__u32 value Menu entry value used by the device
	160	__u8 name[32] Menu entry name
	161
	162
	163	* enum uvc_control_data_type
	164
	165	UVC_CTRL_DATA_TYPE_RAW Raw control (byte array)
	166	UVC_CTRL_DATA_TYPE_SIGNED Signed integer
	167	UVC_CTRL_DATA_TYPE_UNSIGNED Unsigned integer
	168	UVC_CTRL_DATA_TYPE_BOOLEAN Boolean
	169	UVC_CTRL_DATA_TYPE_ENUM Enumeration
	170	UVC_CTRL_DATA_TYPE_BITMASK Bitmask
	171
	172
	173	---- UVCIOC_CTRL_QUERY - Query a UVC XU control ----
	174
	175	Argument: struct uvc_xu_control_query
	176
	177	Description:
	178	This ioctl queries a UVC XU control identified by its extension unit ID
	179	and control selector.
	180
	181	There are a number of different queries available that closely
	182	correspond to the low-level control requests described in the UVC
	183	specification. These requests are:
184
185	UVC_GET_CUR
186	Obtain the current value of the control.
187	UVC_GET_MIN
188	Obtain the minimum value of the control.
189	UVC_GET_MAX
190	Obtain the maximum value of the control.
191	UVC_GET_DEF
192	Obtain the default value of the control.
193	UVC_GET_RES
194	Query the resolution of the control, i.e. the step size of the
195	allowed control values.
196	UVC_GET_LEN
197	Query the size of the control in bytes.
198	UVC_GET_INFO
199	Query the control information bitmap, which indicates whether
200	get/set requests are supported.
201	UVC_SET_CUR
202	Update the value of the control.
203
204	Applications must set the 'size' field to the correct length for the
205	control. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, for
206	which the size must be set to 2 and 1, respectively. The 'data' field
207	must point to a valid writable buffer big enough to hold the indicated
208	number of data bytes.
209
210	Data is copied directly from the device without any driver-side
211	processing. Applications are responsible for data buffer formatting,
212	including little-endian/big-endian conversion. This is particularly
213	important for the result of the UVC_GET_LEN requests, which is always
214	returned as a little-endian 16-bit integer by the device.
215
216	Return value:
217	On success 0 is returned. On error -1 is returned and errno is set
218	appropriately.
219
220	ENOENT
221	The device does not support the given control or the specified
222	extension unit could not be found.
223	ENOBUFS
224	The specified buffer size is incorrect (too big or too small).
225	EINVAL
226	An invalid request code was passed.
227	EBADRQC
228	The given request is not supported by the given control.
229	EFAULT
230	The data pointer references an inaccessible memory area.
231
232	Data types:
233	* struct uvc_xu_control_query
234
235	__u8 unit Extension unit ID
236	__u8 selector Control selector
237	__u8 query Request code to send to the device
238	__u16 size Control data size (in bytes)
239	__u8 *data Control value