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
31 extern "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 */
191 typedef 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 
203 typedef 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 */
211 typedef 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 
236 typedef 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 */
251 typedef 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 
279 typedef 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 */
294 typedef 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 */
310 typedef 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 */
316 typedef 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 
327 typedef 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  */
336 typedef 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  */
355 typedef 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 */
364 typedef 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  */
376 typedef 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  */
385 typedef 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  */
396 typedef 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 */
406 typedef 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  */
437 typedef 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