usbvc.h revision 7492:2387323b838f 
1/*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21/*
22 * Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
23 * Use is subject to license terms.
24 */
25
26#ifndef _SYS_USB_USBVC_H
27#define	_SYS_USB_USBVC_H
28
29
30#ifdef	__cplusplus
31extern "C" {
32#endif
33
34/* Video interface class code */
35#define	CC_VIDEO			0x0e
36
37/* Video interface subclass code */
38#define	SC_UNDEFINED			0x00
39#define	SC_VIDEOCONTROL 		0x01
40#define	SC_VIDEOSTREAMING		0x02
41#define	SC_VIDEO_INTERFACE_COLLECTION	0x03
42
43#define	PC_PROTOCOL_UNDEFINED		0x00
44
45/* Video class specific interface descriptor types */
46#define	CS_UNDEFINED			0x20
47#define	CS_DEVICE			0x21
48#define	CS_CONFIGURATION		0x22
49#define	CS_STRING			0x23
50#define	CS_INTERFACE			0x24
51#define	CS_ENDPOINT			0x25
52
53/* Video class specific, video control interface descriptor subtypes */
54#define	VC_DESCRIPTOR_UNDEFINED 	0x00
55#define	VC_HEADER			0x01
56#define	VC_INPUT_TERMINAL		0x02
57#define	VC_OUTPUT_TERMINAL		0x03
58#define	VC_SELECTOR_UNIT		0x04
59#define	VC_PROCESSING_UNIT		0x05
60#define	VC_EXTENSION_UNIT		0x06
61
62/* Video class specific, video stream interface descriptor subtypes */
63#define	VS_UNDEFINED			0x00
64#define	VS_INPUT_HEADER 		0x01
65#define	VS_OUTPUT_HEADER		0x02
66#define	VS_STILL_IMAGE_FRAME		0x03
67#define	VS_FORMAT_UNCOMPRESSED		0x04
68#define	VS_FRAME_UNCOMPRESSED		0x05
69#define	VS_FORMAT_MJPEG 		0x06
70#define	VS_FRAME_MJPEG			0x07
71#define	VS_FORMAT_MPEG2TS		0x0a
72#define	VS_FORMAT_DV			0x0c
73#define	VS_COLORFORMAT			0x0d
74#define	VS_FORMAT_FRAME_BASED		0x10
75#define	VS_FRAME_FRAME_BASED		0x11
76#define	VS_FORMAT_STREAM_BASED		0x12
77
78/* Endpoint type */
79#define	EP_UNDEFINED			0x00
80#define	EP_GENERAL			0x01
81#define	EP_ENDPOINT			0x02
82#define	EP_INTERRUPT			0x03
83
84/* Request codes, bRequest */
85#define	RC_UNDEFINED			0x00
86#define	SET_CUR 			0x01
87#define	GET_CUR 			0x81
88#define	GET_MIN 			0x82
89#define	GET_MAX 			0x83
90#define	GET_RES 			0x84
91#define	GET_LEN 			0x85
92#define	GET_INFO			0x86
93#define	GET_DEF 			0x87
94
95/* Control types of Video Control interface */
96#define	VC_CONTROL_UNDEFINED		0x00
97#define	VC_VIDEO_POWER_MODE_CONTROL	0x01
98#define	VC_REQUEST_ERROR_CODE_CONTROL	0x02
99
100/* Terminal controls */
101#define	TE_CONTROL_UNDEFINED		0x00
102
103/* Selector Unit controls */
104#define	SU_CONTROL_UNDEFINED		0x00
105#define	SU_INPUT_SELECT_CONTROL 	0x01
106
107/* Camera Terminal controls */
108#define	CT_CONTROL_UNDEFINED				0x00
109#define	CT_SCANNING_MODE_CONTROL			0x01
110#define	CT_AE_MODE_CONTROL				0x02
111#define	CT_AE_PRIORITY_CONTROL				0x03
112#define	CT_EXPOSURE_TIME_ABSOLUTE_CONTROL		0x04
113#define	CT_EXPOSURE_TIME_RELATIVE_CONTROL		0x05
114#define	CT_FOCUS_ABSOLUTE_CONTROL			0x06
115#define	CT_FOCUS_RELATIVE_CONTROL			0x07
116#define	CT_FOCUS_AUTO_CONTROL				0x08
117#define	CT_IRIS_ABSOLUTE_CONTROL			0x09
118#define	CT_IRIS_RELATIVE_CONTROL			0x0a
119#define	CT_ZOOM_ABSOLUTE_CONTROL			0x0b
120#define	CT_ZOOM_RELATIVE_CONTROL			0x0c
121#define	CT_PANTILT_ABSOLUTE_CONTROL			0x0d
122#define	CT_PANTILT_RELATIVE_CONTROL			0x0e
123#define	CT_ROLL_ABSOLUTE_CONTROL			0x0f
124#define	CT_ROLL_RELATIVE_CONTROL			0x10
125#define	CT_PRIVACY_CONTROL				0x11
126
127/* Processing Unit controls */
128#define	PU_CONTROL_UNDEFINED				0x00
129#define	PU_BACKLIGHT_COMPENSATION_CONTROL		0x01
130#define	PU_BRIGHTNESS_CONTROL				0x02
131#define	PU_CONTRAST_CONTROL				0x03
132#define	PU_GAIN_CONTROL 				0x04
133#define	PU_POWER_LINE_FREQUENCY_CONTROL 		0x05
134#define	PU_HUE_CONTROL					0x06
135#define	PU_SATURATION_CONTROL				0x07
136#define	PU_SHARPNESS_CONTROL				0x08
137#define	PU_GAMMA_CONTROL				0x09
138#define	PU_WHITE_BALANCE_TEMPERATURE_CONTROL		0x0a
139#define	PU_WHITE_BALANCE_TEMPERATURE_AUTO_CONTROL	0x0b
140#define	PU_WHITE_BALANCE_COMPONENT_CONTROL		0x0c
141#define	PU_WHITE_BALANCE_COMPONENT_AUTO_CONTROL 	0x0d
142#define	PU_DIGITAL_MULTIPLIER_CONTROL			0x0e
143#define	PU_DIGITAL_MULTIPLIER_LIMIT_CONTROL		0x0f
144#define	PU_HUE_AUTO_CONTROL				0x10
145#define	PU_ANALOG_VIDEO_STANDARD_CONTROL		0x11
146#define	PU_ANALOG_LOCK_STATUS_CONTROL			0x12
147
148/* VideoStreaming interface controls, wValue */
149#define	VS_CONTROL_UNDEFINED		0x00
150#define	VS_PROBE_CONTROL		0x01
151#define	VS_COMMIT_CONTROL		0x02
152#define	VS_STILL_PROBE_CONTROL		0x03
153#define	VS_STILL_COMMIT_CONTROL 	0x04
154#define	VS_STILL_IMAGE_TRIGGER_CONTROL	0x05
155#define	VS_STREAM_ERROR_CODE_CONTROL	0x06
156#define	VS_GENERATE_KEY_FRAME_CONTROL	0x07
157#define	VS_UPDATE_FRAME_SEGMENT_CONTROL 0x08
158#define	VS_SYNC_DELAY_CONTROL		0x09
159
160/* bmRequestType */
161#define	USBVC_SET_IF	0x21;
162#define	USBVC_GET_IF	0xA1;
163#define	USBVC_SET_EP	0x22;
164#define	USBVC_GET_EP	0xA2;
165
166/* Terminal types */
167#define	TT_VENDOR_SPECIFIC		0x0100
168#define	TT_STREAMING			0x0101
169
170/* Input Terminal types */
171#define	ITT_VENDOR_SPECIFIC		0x0200
172#define	ITT_CAMERA			0x0201
173#define	ITT_MEDIA_TRANSPORT_INPUT	0x0202
174
175/* Output Terminal types */
176#define	OTT_VENDOR_SPECIFIC		0x0300
177#define	OTT_DISPLAY			0x0301
178#define	OTT_MEDIA_TRANSPORT_OUTPUT	0x0302
179
180/* External terminal types */
181#define	EXTERNAL_VENDOR_SPECIFIC	0x0400
182#define	COMPOSITE_CONNECTOR		0x0401
183#define	SVIDEO_CONNECTOR		0x0402
184#define	COMPONENT_CONNECTOR		0x0403
185
186/*
187 * usb video class descriptors
188 */
189
190/* usb video class, video control interface, header descriptor */
191typedef struct usbvc_vc_header_descr {
192	uint8_t	bLength;
193	uint8_t	bDescriptorType;
194	uint8_t	bDescriptorSubtype;
195	uint8_t	bcdUVC[2];
196	uint8_t	wTotalLength[2];
197	uint8_t	dwClockFrequency[4];
198
199	/* Number of stream interfaces belong to this VC interface */
200	uint8_t	bInCollection;
201} usbvc_vc_header_descr_t;
202
203typedef struct usbvc_vc_header {
204	usbvc_vc_header_descr_t	*descr;
205
206	/* there might be multiple stream interface numbers */
207	uint8_t			*baInterfaceNr;
208} usbvc_vc_header_t;
209
210/* unit descriptor for all the three kinds of units */
211typedef struct usbvc_unit_descr {
212	uint8_t bLength;
213	uint8_t bDescriptorType;
214	uint8_t bDescriptorSubType;
215	uint8_t bUnitID;
216
217	union {
218		struct {
219			uint8_t bSourceID;
220			uint8_t wMaxMultiplier[2];
221			uint8_t bControlSize;
222		} processing;
223
224		struct {
225			uint8_t	bNrInPins;
226		} selector;
227
228		struct {
229			uint8_t	guidExtensionCode[16];
230			uint8_t	bNumControls;
231			uint8_t	bNrInPins;
232		} extension;
233	} unit;
234} usbvc_unit_descr_t;
235
236typedef struct usbvc_units {
237	/* Point to cvs_buf, for most elements of unit descriptor */
238	usbvc_unit_descr_t *descr;
239
240	uint8_t		*bmControls;	/* for processing or extention unit */
241	uint8_t		*baSourceID;	/* for selector or extention unit */
242	uint8_t		iSelector;	/* for selector  unit */
243	uint8_t		iProcessing;	/* for processing  unit */
244	uint8_t		bmVideoStandards; /* for processing unit */
245	uint8_t		bControlSize;	/* for extention unit */
246	uint8_t		iExtension;	/* for extention unit */
247	list_node_t	unit_node;
248} usbvc_units_t;
249
250/* Terminal descriptor for all the three kinds of video terminals */
251typedef struct		usbvc_term_descr {
252	uint8_t		bLength;
253	uint8_t		bDescriptorType;
254	uint8_t		bDescriptorSubType;
255	uint8_t		bTerminalID;
256	uint16_t	wTerminalType;
257	uint8_t		AssocTerminal;
258
259	union {
260		struct {
261			uint8_t iTerminal;
262		} input;
263
264		struct {
265			uint8_t	bSourceID;
266			uint8_t	iTerminal;
267		} output;
268
269		struct {
270			uint8_t		iTerminal;
271			uint16_t	wObjectiveFocalLengthMin;
272			uint16_t	wObjectiveFocalLengthMax;
273			uint16_t	wOcularFocalLength;
274			uint8_t		bControlSize;
275		} camera;
276	}term;
277} usbvc_term_descr_t;
278
279typedef struct usbvc_terms {
280	usbvc_term_descr_t	*descr;	/* interfaces for this cfg */
281
282	/* for input or output terminals, excluding camera terminals */
283	uint8_t			*bSpecific;
284
285	uint8_t			*bmControls;  /* for camera terminals only */
286	list_node_t		term_node;
287} usbvc_terms_t;
288
289/*
290 * Stream interface descriptors
291 */
292
293/* input header descriptor */
294typedef struct usbvc_input_header_descr {
295	uint8_t		bLength;
296	uint8_t		bDescriptorType;
297	uint8_t		bDescriptorSubType;
298	uint8_t		bNumFormats;
299	uint16_t	wTotalLength;
300	uint8_t		bEndpointAddress;
301	uint8_t		bmInfo;
302	uint8_t		bTerminalLink;
303	uint8_t		bStillCaptureMethod;
304	uint8_t		bTriggerSupport;
305	uint8_t		bTriggerUsage;
306	uint8_t		bControlSize;
307} usbvc_input_header_descr_t;
308
309/* UVC Spec: only one input header in one stream interface */
310typedef struct usbvc_input_header {
311	usbvc_input_header_descr_t	*descr;
312	uint8_t				*bmaControls;
313} usbvc_input_header_t;
314
315/* Do not support output video device at present */
316typedef struct usbvc_output_header_descr {
317	uint8_t		bLength;
318	uint8_t		bDescriptorType;
319	uint8_t		bDescriptorSubType;
320	uint8_t		bNumFormats;
321	uint16_t	wTotalLength;
322	uint8_t		bEndpointAddress;
323	uint8_t		bTerminalLink;
324	uint8_t		bControlSize;
325} usbvc_output_header_descr_t;
326
327typedef struct usbvc_output_header {
328	usbvc_output_header_descr_t	*descr;
329	uint8_t				*bmaControls;
330} usbvc_output_header_t;
331
332/*
333 * Except bDescriptorSubType value, MJPEG and uncompressed frame descriptor are
334 * all the same. So share one structure.
335 */
336typedef struct usbvc_frame_descr {
337	uint8_t bLength;
338	uint8_t bDescriptorType;
339	uint8_t bDescriptorSubType;
340	uint8_t bFrameIndex;
341	uint8_t bmCapabilities;
342	uint8_t wWidth[2];
343	uint8_t wHeight[2];
344	uint8_t dwMinBitRate[4];
345	uint8_t dwMaxBitRate[4];
346	uint8_t dwMaxVideoFrameBufferSize[4];
347	uint8_t dwDefaultFrameInterval[4];
348	uint8_t bFrameIntervalType;
349} usbvc_frame_descr_t;
350
351/*
352 * There may be several frame descriptors immediately follow a format
353 * descriptor.
354 */
355typedef struct usbvc_frames {
356	usbvc_frame_descr_t *descr;
357	uint32_t dwMinFrameInterval;	/* for continuous frame intervals */
358	uint32_t dwMaxFrameInterval;	/* for continuous frame intervals */
359	uint32_t dwFrameIntervalStep;	/* for continuous frame intervals */
360	uint8_t *dwFrameInterval;	/* for discrete frame intervals */
361} usbvc_frames_t;
362
363/* The first several fixed length fields of still image frame descriptor */
364typedef struct usbvc_still_image_frame_descr {
365	uint8_t	bLength;
366	uint8_t	bDescriptorType;
367	uint8_t	bDescriptorSubType;
368	uint8_t	bEndpointAddress;
369	uint8_t	bNumImageSizePatterns;
370} usbvc_still_image_frame_descr_t;
371
372/*
373 * Width and Hight of the still image.
374 * There might be multiple such value pairs in one still image frame descr.
375 */
376typedef struct width_height {
377	uint16_t wWidth;
378	uint16_t wHeight;
379} width_height_t;
380
381/*
382 * The whole still image frame descriptor.
383 * UVC Spec: only one still image descriptor for each format group.
384 */
385typedef struct usbvc_still_image_frame {
386	usbvc_still_image_frame_descr_t	*descr;
387	width_height_t			*width_height;
388	uint8_t				bNumCompressionPattern;
389	uint8_t				*bCompression;
390} usbvc_still_image_frame_t;
391
392/*
393 * All fields of this descr are fixed length.
394 * UVC Spec: only one color_matching_descr is allowed for a given format.
395 */
396typedef struct usbvc_color_matching_descr {
397	uint8_t	bLength;
398	uint8_t	bDescriptorType;
399	uint8_t	bDescriptorSubtype;
400	uint8_t	bColorPrimaries;
401	uint8_t	bTransferCharacteristics;
402	uint8_t	bMatrixCoefficients;
403} usbvc_color_matching_descr_t;
404
405/* Mjpeg and uncompressed format descriptor */
406typedef struct usbvc_format_descr {
407	uint8_t	bLength;
408	uint8_t	bDescriptorType;
409	uint8_t	bDescriptorSubType;
410	uint8_t	bFormatIndex;
411	uint8_t	bNumFrameDescriptors;
412	union {
413		struct {
414			uint8_t	bmFlags;
415			uint8_t	bDefaultFrameIndex;
416			uint8_t	bAspectRatioX;
417			uint8_t	bAspectRatioY;
418			uint8_t	bmInterlaceFlags;
419			uint8_t	bCopyProtect;
420		} mjpeg;
421
422		struct {
423			uint8_t	guidFormat[16];
424			uint8_t	bBitsPerPixel;
425			uint8_t	bDefaultFrameIndex;
426			uint8_t	bAspectRatioX;
427			uint8_t	bAspectRatioY;
428			uint8_t	bmInterlaceFlags;
429			uint8_t	bCopyProtect;
430		} uncompressed;
431	}fmt;
432} usbvc_format_descr_t;
433
434/*
435 *  usb video class requests
436 */
437typedef struct usbvc_vs_probe_commit {
438	uint8_t	bmHint[2];
439	uint8_t	bFormatIndex;
440	uint8_t	bFrameIndex;
441	uint8_t	dwFrameInterval[4];
442	uint8_t	wKeyFrameRate[2];
443	uint8_t	wPFrameRate[2];
444	uint8_t	wCompQuality[2];
445	uint8_t	wCompWindowSize[2];
446	uint8_t	wDelay[2];
447	uint8_t	dwMaxVideoFrameSize[4];
448	uint8_t	dwMaxPayloadTransferSize[4];
449	uint8_t	wClockFrequency[4];
450	uint8_t	bmFramingInfo;
451	uint8_t	bPreferedVersion;
452	uint8_t	bMinVersion;
453	uint8_t	bMaxVersion;
454} usbvc_vs_probe_commit_t;
455
456/* Table 2-1 of a sub video class spec: "uncompressed payload spec" */
457#define	USBVC_FORMAT_GUID_YUY2	{0x59, 0x55, 0x59, 0x32, 0x00, 0x00, 0x10, \
458				0x00, 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, \
459				0x9b, 0x71}
460#define	USBVC_FORMAT_GUID_NV12	{0x4e, 0x56, 0x31, 0x32, 0x00, 0x00, 0x10, \
461				0x00, 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, \
462				0x9b, 0x71}
463
464/* Stream frame's flag bits */
465#define	USBVC_STREAM_EOF	(1 << 1)
466#define	USBVC_STREAM_FID	(1 << 0)
467
468#ifdef __cplusplus
469}
470#endif
471
472#endif /* _SYS_USB_USBVC_H */
473