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