xref: /netbsd/sys/dev/usb/uvideoreg.h (revision 3e58ce79)
1 /*	$NetBSD: uvideoreg.h,v 1.8 2023/04/10 15:26:56 mlelstv Exp $	*/
2 
3 /*
4  * Copyright (c) 2008 Patrick Mahoney
5  * All rights reserved.
6  *
7  * This code was written by Patrick Mahoney (pat@polycrystal.org) as
8  * part of Google Summer of Code 2008.
9  *
10  * Redistribution and use in source and binary forms, with or without
11  * modification, are permitted provided that the following conditions
12  * are met:
13  * 1. Redistributions of source code must retain the above copyright
14  *    notice, this list of conditions and the following disclaimer.
15  * 2. Redistributions in binary form must reproduce the above copyright
16  *    notice, this list of conditions and the following disclaimer in the
17  *    documentation and/or other materials provided with the distribution.
18  * 3. All advertising materials mentioning features or use of this software
19  *    must display the following acknowledgement:
20  *        This product includes software developed by the NetBSD
21  *        Foundation, Inc. and its contributors.
22  * 4. Neither the name of The NetBSD Foundation nor the names of its
23  *    contributors may be used to endorse or promote products derived
24  *    from this software without specific prior written permission.
25  *
26  * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
27  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
28  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
29  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
30  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
31  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
32  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
33  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
34  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
35  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36  * POSSIBILITY OF SUCH DAMAGE.
37  */
38 
39 #define UVIDEO_VERSION		0x001
40 
41 /* This is the standard GUID / UUID.  In USB, it comes in the usual
42  * little-endian packed format. */
43 
44 typedef struct {
45 	uDWord		data1;
46 	uWord		data2;
47 	uWord		data3;
48 	uByte		data4[8];
49 } UPACKED usb_guid_t;
50 
51 typedef struct {
52 	uint32_t	data1;
53 	uint16_t	data2;
54 	uint16_t	data3;
55 	uint8_t		data4[8];
56 } guid_t;
57 #define GUID_LEN 16
58 
59 /*
60  * Video Control descriptors
61  */
62 
63 #define UDESC_VC_HEADER		0x01
64 #define UDESC_INPUT_TERMINAL	0x02
65 #define UDESC_OUTPUT_TERMINAL	0x03
66 #define UDESC_SELECTOR_UNIT	0x04
67 #define UDESC_PROCESSING_UNIT	0x05
68 #define UDESC_EXTENSION_UNIT	0x06
69 
70 #define UDESC_VC_INTERRUPT_ENDPOINT	0x03
71 
72 /* Terminal Types */
73 #define UVDIEO_TT_VENDOR_SPECIFIC	0x0100
74 #define UVIDEO_TT_STREAMING		0x0101
75 
76 /* Input Terminal Types */
77 #define UVIDEO_ITT_VENDOR_SPECIFIC	0x0200
78 #define UVIDEO_ITT_CAMERA		0x0201
79 #define UVIDEO_ITT_MEDIA_TRANSPORT_INPUT 0x0202
80 
81 /* Output Terminal Types */
82 #define UVIDEO_OTT_VENDOR_SPECIFIC	0x0300
83 #define UVIDEO_OTT_DISPLAY		0x0301
84 #define UVIDEO_OTT_MEDIA_TRANSPORT_OUTPUT 0x0302
85 
86 /* generic descriptor with Subtype */
87 typedef struct {
88 	uByte	bLength;
89 	uByte	bDescriptorType;
90 	uByte	bDescriptorSubtype;
91 } uvideo_descriptor_t;
92 
93 /* Class-specific Video Control Interface Header Descriptor */
94 typedef struct {
95 	uByte		bLength;
96 	uByte		bDescriptorType;
97 	uByte		bDescriptorSubtype;
98 	uWord		bcdUVC;
99 	uWord		wTotalLength;
100 	uDWord		dwClockFrequency;
101 	uByte		bInCollection;
102 	/* followed by n bytes where n is equal to value of bInCollection */
103 	uByte		baInterfaceNr[];
104 } UPACKED uvideo_vc_header_descriptor_t;
105 
106 /* Input Terminal Descriptor */
107 typedef struct {
108 	uByte		bLength;
109 	uByte		bDescriptorType;
110 	uByte		bDescriptorSubtype;
111 	uByte		bTerminalID;
112 	uWord		wTerminalType;
113 	uByte		bAssocTerminal;
114 	uByte		iTerminal;
115 	/* possibly more, depending on Terminal type */
116 } UPACKED uvideo_input_terminal_descriptor_t;
117 
118 /* Output Terminal Descriptor */
119 typedef struct {
120 	uByte		bLength;
121 	uByte		bDescriptorType;
122 	uByte		bDescriptorSubtype;
123 	uByte		bTerminalID;
124 	uWord		wTerminalType;
125 	uByte		bAssocTerminal;
126 	uByte		bSourceID;
127 	uByte		iTerminal;
128 } UPACKED uvideo_output_terminal_descriptor_t;
129 
130 /* Camera Terminal Descriptor */
131 typedef struct {
132 	uByte		bLength;
133 	uByte		bDescriptorType;
134 	uByte		bDescriptorSubtype; 	/* UDESC_VC_INPUT_TERMINAL */
135 	uByte		bTerminalID;
136 	uWord		wTerminalType;		/* UVIDEO_ITT_CAMERA */
137 	uByte		bAssocTerminal;
138 	uByte		iTerminal;
139 	uWord		wObjectiveFocalLengthMin;
140 	uWord		wObjectiveFocalLengthMax;
141 	uWord		wOcularFocalLength;
142 	uByte		bControlSize;
143 	uByte		bmControls[];
144 } UPACKED uvideo_camera_terminal_descriptor_t;
145 
146 /* bmControls fields of uvideo_camera_terminal_descriptor_t */
147 #define UVIDEO_CAMERA_CONTROL_SCANNING_MODE		(1<<0)
148 #define UVIDEO_CAMERA_CONTROL_AUTO_EXPOSURE_MODE	(1<<1)
149 #define UVIDEO_CAMERA_CONTROL_AUTO_EXPOSURE_PRIO	(1<<2)
150 #define UVIDEO_CAMERA_CONTROL_EXPOSURE_TIME_ABSOLUTE	(1<<3)
151 #define UVIDEO_CAMERA_CONTROL_EXPOSURE_TIME_RELATIVE	(1<<4)
152 #define UVIDEO_CAMERA_CONTROL_FOCUS_ABSOLUTE		(1<<5)
153 #define UVIDEO_CAMERA_CONTROL_FOCUS_RELATIVE		(1<<6)
154 #define UVIDEO_CAMERA_CONTROL_IRIS_ABSOLUTE		(1<<7)
155 #define UVIDEO_CAMERA_CONTROL_IRIS_RELATIVE		(1<<8)
156 #define UVIDEO_CAMERA_CONTROL_ZOOM_ABSOLUTE		(1<<9)
157 #define UVIDEO_CAMERA_CONTROL_ZOOM_RELATIVE		(1<<10)
158 #define UVIDEO_CAMERA_CONTROL_PANTILT_ABSOLUTE		(1<<11)
159 #define UVIDEO_CAMERA_CONTROL_PANTILT_RELATIVE		(1<<12)
160 #define UVIDEO_CAMERA_CONTROL_ROLL_ABSOLUTE		(1<<13)
161 #define UVIDEO_CAMERA_CONTROL_ROLL_RELATIVE		(1<<14)
162 /* 15,16 reserved */
163 #define UVIDEO_CAMERA_CONTROL_FOCUS_AUTO		(1<<17)
164 #define UVIDEO_CAMERA_CONTROL_PRIVACY			(1<<18)
165 
166 typedef struct {
167 	uByte		bLength;
168 	uByte		bDescriptorType;
169 	uByte		bDescriptorSubtype;
170 	uByte		bUnitID;
171 	uByte		bNrInPins;
172 	uByte		baSourceID[];
173 	/* The position of the next field is baSourceID[0] + bNrInPins
174 	 * and should be accessed via a function. */
175 /*      uByte           iSelector */
176 } UPACKED uvideo_selector_unit_descriptor_t;
177 
178 typedef struct {
179 	uByte		bLength;
180 	uByte		bDescriptorType;
181 	uByte		bDescriptorSubtype;
182 	uByte		bUnitID;
183 	uByte		bSourceID;
184 	uWord		wMaxMultiplier;
185 	uByte		bControlSize;
186 	uByte		bmControls[];
187 /*      uByte           iProcessing */
188 /*      uByte           bmVideoStandards */
189 #define PU_GET_VIDEO_STANDARDS(desc)	\
190 	(*((desc)->bmControls + (desc)->bControlSize))
191 #define UVIDEO_STANDARD_NONE		(1<<0)
192 #define UVIDEO_STANDARD_NTSC_525_60	(1<<1)
193 #define UVIDEO_STANDARD_PAL_625_50	(1<<2)
194 #define UVIDEO_STANDARD_SECAM_625_50	(1<<3)
195 #define UVIDEO_STANDARD_NTSC_625_50	(1<<4)
196 #define UVIDEO_STANDARD_PAL_525_60	(1<<5)
197 } UPACKED uvideo_processing_unit_descriptor_t;
198 
199 typedef struct {
200 	uByte		bLength;
201 	uByte		bDescriptorType;
202 	uByte		bDescriptorSubtype;
203 	uByte		bUnitID;
204 	usb_guid_t	guidExtensionCode;
205 	uByte		bNumControls;
206 	uByte		bNrInPins;
207 	uByte		baSourceID[];
208 /*      uByte           bControlSize */
209 /*      uByte           bmControls */
210 #define XU_GET_CONTROL_SIZE(desc)			\
211 	(*((desc)->baSourceID + (desc)->bNrInPins))
212 #define XU_GET_CONTROLS(desc)				\
213 	((desc)->baSourceID + (desc)->bNrInPins + 1)
214 /*      uByte           iExtension */
215 } UPACKED uvideo_extension_unit_descriptor_t;
216 
217 typedef struct {
218 	uByte		bLength;
219 	uByte		bDescriptorType; /* UDESC_ENDPOINT */
220 	uByte		bDescriptorSubtype;
221 	uWord		wMaxTransferSize;
222 } UPACKED uvideo_vc_interrupt_endpoint_descriptor_t;
223 
224 
225 
226 /*
227  * Video Streaming descriptors
228  */
229 
230 #define UDESC_VS_INPUT_HEADER		0x01
231 #define UDESC_VS_OUTPUT_HEADER		0x02
232 #define UDESC_VS_STILL_IMAGE_FRAME	0x03
233 #define UDESC_VS_FORMAT_UNCOMPRESSED	0x04
234 #define UDESC_VS_FRAME_UNCOMPRESSED	0x05
235 #define UDESC_VS_FORMAT_MJPEG		0x06
236 #define UDESC_VS_FRAME_MJPEG		0x07
237 /* reserved in spec v1.1		0x08 */
238 /* reserved in spec v1.1		0x09 */
239 #define UDESC_VS_FORMAT_MPEG2TS		0x0A
240 /* reserved in spec v 1.1		0x0B */
241 #define UDESC_VS_FORMAT_DV		0x0C
242 #define UDESC_VS_COLORFORMAT		0x0D
243 /* reserved in spec v1.1		0x0E */
244 /* reserved in spec v1.1		0x0F */
245 #define UDESC_VS_FORMAT_FRAME_BASED	0x10
246 #define UDESC_VS_FRAME_FRAME_BASED	0x11
247 #define UDESC_VS_FORMAT_STREAM_BASED	0x12
248 
249 /* Copy protection state */
250 #define UVIDEO_NO_RESTRICTIONS		0
251 #define UVIDEO_RESTRICT_DUP		1
252 
253 typedef struct {
254 	uByte		bLength;
255 	uByte		bDescriptorType;
256 	uByte		bDescriptorSubtype;
257 	uByte		bNumFormats;
258 	uWord		wTotalLength;
259 	uByte		bEndpointAddress;
260 	uByte		bmInfo;
261 	uByte		bTerminalLink;
262 	uByte		bStillCaptureMethod;
263 	uByte		bTriggerSupport;
264 	uByte		bTriggerUsage;
265 	uByte		bControlSize;
266 	uByte		bmaControls[];
267 #define UVIDEO_VS_KEYFRAME_RATE	(1<<0)
268 #define UVIDEO_VS_PFRAME_RATE	(1<<1)
269 #define UVIDEO_VS_COMP_QUALITY	(1<<2)
270 #define UVIDEO_VS_COMP_WINDOW_SIZE	(1<<3)
271 #define UVIDEO_VS_GENERATE_KEYFRAME	(1<<4)
272 #define UVIDEO_VS_UPDATE_FRAME_SEGMENT	(1<<5)
273 } UPACKED uvideo_vs_input_header_descriptor_t;
274 
275 typedef struct {
276 	uByte		bLength;
277 	uByte		bDescriptorType;
278 	uByte		bDescriptorSubtype;
279 	uByte		bNumFormats;
280 	uWord		wTotalLength;
281 	uByte		bEndpointAddress;
282 	uByte		bTerminalLink;
283 	uByte		bControlSize;
284 	uByte		bmaControls[];
285 } UPACKED uvideo_vs_output_header_descriptor_t;
286 
287 
288 typedef struct {
289 	uWord		wWidth;
290 	uWord		wHeight;
291 } UPACKED uvideo_still_image_frame_dimensions_t;
292 
293 typedef struct {
294 	uByte		bLength;
295 	uByte		bDescriptorType;
296 	uByte		bDescriptorSubtype;
297 	uByte		bEndpointAddress;
298 	uByte		bNumImageSizePatterns;
299 	uvideo_still_image_frame_dimensions_t wwaDimensions[];
300 	/* position dependent on size of previous item */
301 	/* uByte	bNumCompressionPattern */
302 	/* uByte	bCompression[] */
303 } UPACKED uvideo_still_image_frame_descriptor_t;
304 
305 
306 /* Color matching information */
307 
308 /* bColroPrimaries */
309 #define UVIDEO_COLOR_PRIMARIES_UNSPECIFIED	0
310 #define UVIDEO_COLOR_PRIMARIES_sRGB		1 /* same as BT709 */
311 #define UVIDEO_COLOR_PRIMARIES_BT709		1 /* default */
312 #define UVIDEO_COLOR_PRIMARIES_BT470_2_M       	2
313 #define UVIDEO_COLOR_PRIMARIES_BT470_2_BG      	3
314 #define UVIDEO_COLOR_PRIMARIES_SMPTE_170M      	4
315 #define UVIDEO_COLOR_PRIMARIES_SMPTE_240M      	5
316 
317 /* bTransferCharacteristics */
318 #define UVIDEO_GAMMA_FUNCTION_UNSPECIFIED	0
319 #define UVIDEO_GAMMA_FUNCTION_BT709		1 /* default */
320 #define UVIDEO_GAMMA_FUNCTION_BT470_2_M       	2
321 #define UVIDEO_GAMMA_FUNCTION_BT470_2_BG      	3
322 #define UVIDEO_GAMMA_FUNCTION_SMPTE_170M      	4
323 #define UVIDEO_GAMMA_FUNCTION_SMPTE_240M      	5
324 #define UVIDEO_GAMMA_FUNCTION_LINEAR		6
325 #define UVIDEO_GAMMA_FUNCTION_sRGB		7 /* similar to BT709 */
326 
327 /* bMatrixCoefficients */
328 #define UVIDEO_LUMA_CHROMA_MATRIX_UNSPECIFIED	0
329 #define UVIDEO_LUMA_CHROMA_MATRIX_BT709		1
330 #define UVIDEO_LUMA_CHROMA_MATRIX_FCC       	2
331 #define UVIDEO_LUMA_CHROMA_MATRIX_BT470_2_BG	3
332 #define UVIDEO_LUMA_CHROMA_MATRIX_SMPTE_170M	4 /* default */
333 #define UVIDEO_LUMA_CHROMA_MATRIX_SMPTE_240M	5
334 
335 typedef struct {
336 	uByte		bLength;
337 	uByte		bDescriptorType;
338 	uByte		bDescriptorSubtype;
339 	uByte		bColorPrimaries;
340 	uByte		bTransferCharacteristics;
341 	uByte		bMatrixCoefficients;
342 } UPACKED uvideo_color_matching_descriptor_t;
343 
344 /*
345  * Format and Frame descriptors
346  */
347 
348 #define UVIDEO_FRAME_CAP_STILL_IMAGE	1<<0
349 #define UVIDEO_FRAME_CAP_FIXED_RATE	1<<1
350 
351 #define UVIDEO_FRAME_INTERVAL_CONTINUOUS 0
352 
353 /* TODO: interlace flags */
354 
355 
356 typedef struct {
357 	uDWord		dwMinFrameInterval;
358 	uDWord		dwMaxFrameInterval;
359 	uDWord		dwFrameIntervalStep;
360 } UPACKED uvideo_frame_interval_continuous_t;
361 
362 typedef struct {
363 	uDWord	dwFrameInterval[1]; /* length depends on bFrameIntervalType */
364 } UPACKED uvideo_frame_interval_discrete_t;
365 
366 typedef union {
367 	uvideo_frame_interval_continuous_t	continuous;
368 	uvideo_frame_interval_discrete_t	discrete;
369 } uvideo_frame_interval_t;
370 
371 /* generic format descriptor header */
372 typedef struct {
373 	uByte		bLength;
374 	uByte		bDescriptorType;
375 	uByte		bDescriptorSubtype;
376 	uByte		bFormatIndex;
377 } UPACKED uvideo_vs_format_descriptor_t;
378 
379 /* generic frame descriptor header */
380 typedef struct {
381 	uByte		bLength;
382 	uByte		bDescriptorType;
383 	uByte		bDescriptorSubtype;
384 	uByte		bFrameIndex;
385 } UPACKED uvideo_vs_frame_descriptor_t;
386 
387 
388 /*  uncompressed format and frame descriptors */
389 static const guid_t uvideo_guid_format_yuy2 = {
390 	0x32595559,
391 	0x0000,
392 	0x0010,
393 	{0x80, 0x00, 0x00, 0xAA, 0x00, 0x38, 0x9B, 0x71}
394 };
395 
396 static const guid_t uvideo_guid_format_nv12 = {
397 	0x3231564E,
398 	0x0000,
399 	0x0010,
400 	{0x80, 0x00, 0x00, 0xAA, 0x00, 0x38, 0x9B, 0x71}
401 };
402 
403 static const guid_t uvideo_guid_format_uyvy = {
404 	0x59565955,
405 	0x0000,
406 	0x0010,
407 	{0x80, 0x00, 0x00, 0xAA, 0x00, 0x38, 0x9B, 0x71}
408 };
409 
410 typedef struct {
411 	uByte		bLength;
412 	uByte		bDescriptorType;
413 	uByte		bDescriptorSubtype;
414 	uByte		bFormatIndex;
415 	uByte		bNumFrameDescriptors;
416 	usb_guid_t	guidFormat;
417 	uByte		bBitsPerPixel;
418 	uByte		bDefaultFrameIndex;
419 	uByte		bAspectRatioX;
420 	uByte		bAspectRatioY;
421 	uByte		bmInterlaceFlags;
422 	uByte		bCopyProtect;
423 } UPACKED uvideo_vs_format_uncompressed_descriptor_t;
424 
425 typedef struct {
426 	uByte		bLength;
427 	uByte		bDescriptorType;
428 	uByte		bDescriptorSubtype;
429 	uByte		bFrameIndex;
430 	uByte		bmCapabilities;
431 	uWord		wWidth;
432 	uWord		wHeight;
433 	uDWord		dwMinBitRate;
434 	uDWord		dwMaxBitRate;
435 	uDWord		dwMaxVideoFrameBufferSize;
436 	uDWord		dwDefaultFrameInterval;
437 	uByte		bFrameIntervalType;
438 	uvideo_frame_interval_t uFrameInterval;
439 } UPACKED uvideo_vs_frame_uncompressed_descriptor_t;
440 
441 
442 /* Frame based Format and Frame descriptors.  This is for generic
443  * frame based payloads not covered by other types (e.g, uncompressed
444  * or MJPEG). */
445 
446 typedef struct {
447 	uByte		bLength;
448 	uByte		bDescriptorType;
449 	uByte		bDescriptorSubtype;
450 	uByte		bFormatIndex;
451 	uByte		bNumFrameDescriptors;
452 	usb_guid_t	guidFormat;
453 	uByte		bBitsPerPixel;
454 	uByte		bDefaultFrameIndex;
455 	uByte		bAspectRatioX;
456 	uByte		bAspectRatioY;
457 	uByte		bmInterlaceFlags;
458 	uByte		bCopyProtect;
459 } UPACKED uvideo_format_frame_based_descriptor_t;
460 
461 typedef struct {
462 	uByte		bLength;
463 	uByte		bDescriptorType;
464 	uByte		bDescriptorSubtype;
465 	uByte		bFrameIndex;
466 	uByte		bmCapabilities;
467 	uWord		wWidth;
468 	uWord		wHeight;
469 	uDWord		dwMinBitRate;
470 	uDWord		dwMaxBitRate;
471 	uDWord		dwDefaultFrameInterval;
472 	uByte		bFrameIntervalType;
473 	uDWord		dwBytesPerLine;
474 	uvideo_frame_interval_t uFrameInterval;
475 } UPACKED uvideo_frame_frame_based_descriptor_t;
476 
477 
478 /* MJPEG format and frame descriptors */
479 
480 typedef struct {
481 	uByte		bLength;
482 	uByte		bDescriptorType;
483 	uByte		bDescriptorSubtype;
484 	uByte		bFormatIndex;
485 	uByte		bNumFrameDescriptors;
486 	uByte		bmFlags;
487 #define UVIDEO_NO_FIXED_SIZE_SAMPLES 0
488 #define UVIDEO_FIXED_SIZE_SAMPLES 1
489 	uByte		bDefaultFrameIndex;
490 	uByte		bAspectRatioX;
491 	uByte		bAspectRatioY;
492 	uByte		bmInterlaceFlags;
493 	uByte		bCopyProtect;
494 } UPACKED uvideo_vs_format_mjpeg_descriptor_t;
495 
496 typedef struct {
497 	uByte		bLength;
498 	uByte		bDescriptorType;
499 	uByte		bDescriptorSubtype;
500 	uByte		bFrameIndex;
501 	uByte		bmCapabilities;
502 	uWord		wWidth;
503 	uWord		wHeight;
504 	uDWord		dwMinBitRate;
505 	uDWord		dwMaxBitRate;
506 	uDWord		dwMaxVideoFrameBufferSize;
507 	uDWord		dwDefaultFrameInterval;
508 	uByte		bFrameIntervalType;
509 	uvideo_frame_interval_t uFrameInterval;
510 } UPACKED uvideo_vs_frame_mjpeg_descriptor_t;
511 
512 
513 typedef struct {
514 	uByte		bLength;
515 	uByte		bDescriptorType;
516 	uByte		bDescriptorSubtype;
517 	uByte		bFormatIndex;
518 	uDWord		dwMaxVideoFrameBufferSize;
519 	uByte		bFormatType;
520 #define UVIDEO_GET_DV_FREQ(ubyte) (((ubyte)>>7) & 1)
521 #define UVIDEO_DV_FORMAT_FREQ_50HZ 0
522 #define UVIDEO_DV_FORMAT_FREQ_60HZ 1
523 #define UVIDEO_GET_DV_FORMAT(ubyte) ((ubyte) & 0x3f)
524 #define UVIDEO_DV_FORMAT_SD_DV	0
525 #define UVIDEO_DV_FORMAT_SDL_DV	1
526 #define UVIDEO_DV_FORMAT_HD_DV	2
527 } UPACKED uvideo_vs_format_dv_descriptor_t;
528 
529 
530 
531 /*
532  * Video Control requests
533  */
534 
535 /* Pseudo bitmasks that only work when bitwise OR onto a zeroed value */
536 #define UVIDEO_REQUEST_TYPE_INTERFACE		(0x0001)
537 #define UVIDEO_REQUEST_TYPE_ENDPOINT		(0x0010)
538 #define UVIDEO_REQUEST_TYPE_CLASS_SPECIFIC	(0x01 << 5)
539 #define UVIDEO_REQUEST_TYPE_SET			(0x0 << 7)
540 #define UVIDEO_REQUEST_TYPE_GET			(0x1 << 7)
541 
542 typedef enum {
543 	UVIDEO_REQUEST_DESC_INTERFACE,
544 	UVIDEO_REQUEST_DESC_ENDPOINT
545 } uvideo_request_descriptor;
546 
547 typedef enum {
548 	UR_RC_UNDEFINED = 0x00,
549 	UR_SET_CUR	= 0x01,
550 	UR_GET_CUR	= 0x81,
551 	UR_GET_MIN	= 0x82,
552 	UR_GET_MAX	= 0x83,
553 	UR_GET_RES	= 0x84,
554 	UR_GET_LEN	= 0x85,
555 	UR_GET_INFO	= 0x86,
556 	UR_GET_DEF	= 0x87,
557 } uvideo_request;
558 
559 /* camera terminal control selectors */
560 #define UVIDEO_CT_CONTROL_UNDEFINED		0x00
561 #define UVIDEO_CT_SCANNING_MODE_CONTROL		0x01
562 #define UVIDEO_CT_AE_MODE_CONTROL		0x02
563 #define UVIDEO_CT_EXPOSURE_TIME_ABSOLUTE_CONTROL 0x04
564 #define UVIDEO_CT_EXPOSURE_TIME_RELATIVE_CONTROL 0x05
565 #define UVIDEO_CT_FOCUS_ABSOLUTE_CONTROL	0x06
566 #define UVIDEO_CT_FOCUS_RELATIVE_CONTROL	0x07
567 #define UVIDEO_CT_IRIS_ABSOLUTE_CONTROL		0x09
568 #define UVIDEO_CT_IRIS_RELATIVE_CONTROL		0x0A
569 #define UVIDEO_CT_ZOOM_ABSOLUTE_CONTROL		0x0B
570 #define UVIDEO_CT_ZOOM_RELATIVE_CONTROL		0x0C
571 #define UVIDEO_CT_PANTILT_ABSOLUTE_CONTROL	0x0D
572 #define UVIDEO_CT_PANTILT_RELATIVE_CONTROL	0x0E
573 #define UVIDEO_CT_ROLL_ABSOLUTE_CONTROL		0x0F
574 #define UVIDEO_CT_ROLL_RELATIVE_CONTROL		0x10
575 #define UVIDEO_CT_PRIVACY_CONTROL		0x11
576 
577 /* processing unit control selectors */
578 #define UVIDEO_PU_CONTROL_UNDEFINED			0x00
579 #define UVIDEO_PU_BACKLIGHT_COMPENSATION_CONTROL	0x01
580 #define UVIDEO_PU_BRIGHTNESS_CONTROL			0x02
581 #define UVIDEO_PU_CONTRAST_CONTROL			0x03
582 #define UVIDEO_PU_GAIN_CONTROL				0x04
583 #define UVIDEO_PU_POWER_LINE_FREQUENCY_CONTROL		0x05
584 #define UVIDEO_PU_HUE_CONTROL				0x06
585 #define UVIDEO_PU_SATURATION_CONTROL			0x07
586 #define UVIDEO_PU_SHARPNESS_CONTROL			0x08
587 #define UVIDEO_PU_GAMMA_CONTROL				0x09
588 #define UVIDEO_PU_WHITE_BALANCE_TEMPERATURE_CONTROL	0x0A
589 #define UVIDEO_PU_WHITE_BALANCE_TEMPERATURE_AUTO_CONTROL 0x0B
590 #define UVIDEO_PU_WHITE_BALANCE_COMPONENT_CONTROL	0x0C
591 #define UVIDEO_PU_WHITE_BALANCE_COMPONENT_AUTO_CONTROL	0x0D
592 #define UVIDEO_PU_DIGITAL_MULTIPLIER_CONTROL		0x0E
593 #define UVIDEO_PU_DIGITAL_MULTIPLIER_LIMIT_CONTROL	0x0F
594 #define UVIDEO_PU_HUE_AUTO_CONTROL			0x10
595 #define UVIDEO_PU_ANALOG_VIDEO_STANDARD_CONTROL		0x11
596 #define UVIDEO_PU_ANALOG_LOCK_STATUS_CONTROL		0x12
597 
598 /* extension unit control selectors */
599 #define UVIDEO_XU_CONTROL_UNDEFINED	0x00
600 
601 /* VideoStreaming Interface control selectors */
602 #define UVIDEO_VS_CONTROL_UNDEFINED		0x00
603 #define UVIDEO_VS_PROBE_CONTROL			0x01
604 #define UVIDEO_VS_COMMIT_CONTROL		0x02
605 #define UVIDEO_VS_STILL_PROBE_CONTROL		0x03
606 #define UVIDEO_VS_STILL_COMMIT_CONTROL		0x04
607 #define UVIDEO_VS_STILL_IMAGE_TRIGGER_CONTROL	0x05
608 #define UVIDEO_VS_STREAM_ERROR_CODE_CONTROL	0x06
609 #define UVIDEO_VS_GENERATE_KEY_FRAME_CONTROL	0x07
610 #define UVIDEO_VS_UPDATE_FRAME_SEGMENT_CONTROL	0x08
611 #define UVIDEO_VS_SYNCH_DELAY_CONTROL		0x09
612 
613 /* bitmask result of GET_INFO on a control */
614 #define UVIDEO_CONTROL_INFO_SUPPORTS_GET	(1<<0)
615 #define UVIDEO_CONTROL_INFO_SUPPORTS_SET	(1<<1)
616 #define UVIDEO_CONTROL_INFO_DISABLED		(1<<2)
617 #define UVIDEO_CONTROL_INFO_AUTOUPDATE		(1<<3)
618 #define UVIDEO_CONTROL_INFO_ASYNC		(1<<4)
619 
620 
621 /* Video Probe and Commit Controls request data */
622 typedef struct {
623 	uWord		bmHint;
624 #define UVIDEO_HINT_FRAME_INTERVAL	(1<<0)
625 #define UVIDEO_HINT_KEYFRAME_RATE	(1<<1)
626 #define UVIDEO_HINT_PFRAME_RATE		(1<<2)
627 #define UVIDEO_HINT_COMP_QUALITY	(1<<3)
628 #define UVIDEO_HINT_COMP_WINDOW_SIZE	(1<<4)
629 	uByte		bFormatIndex;
630 	uByte		bFrameIndex;
631 	uDWord		dwFrameInterval;
632 #define UVIDEO_100NS_PER_MS 10000
633 #define UVIDEO_FRAME_INTERVAL_UNITS_PER_USB_FRAME UVIDEO_100NS_PER_MS
634 	uWord		wKeyFrameRate;
635 	uWord		wPFrameRate;
636 	uWord		wCompQuality;
637 	uWord		wCompWindowSize;
638 	uWord		wDelay;
639 	uDWord		dwMaxVideoFrameSize;
640 	uDWord		dwMaxPayloadTransferSize;
641 	/* Following fields are not in v1.0 of UVC.  Will have to do
642 	 * UR_GET_LEN to discover the length of this descriptor. */
643 	uDWord		dwClockFrequency;
644 	uByte		bmFramingInfo;
645 #define UVIDEO_FRAMING_INFO_FID	(1<<0)
646 #define UVIDEO_FRAMING_INFO_EOF	(1<<1)
647 	uByte		bPreferedVersion;
648 	uByte		bMinVersion;
649 	uByte		bMaxVersion;
650 } UPACKED uvideo_probe_and_commit_data_t;
651 
652 /* Video Still Probe and Still Commit Controls request data */
653 typedef struct {
654 	uByte		bFormatIndex;
655 	uByte		bFrameIndex;
656 	uByte		bCompressionIndex;
657 	uDWord		dwMaxVideoFrameSize;
658 	uDWord		dwMaxPayloadTransferSize;
659 } UPACKED uvideo_still_probe_and_still_commit_data_t;
660 #define UVIDEO_STILL_PROBE_AND_STILL_COMMIT_DATA_SIZE 11;
661 
662 
663 
664 /* common header for Video Control and Video Stream status */
665 typedef struct {
666 	uByte		bStatusType;
667 #define UV_STATUS_TYPE_CONTROL	0x02
668 #define UV_STATUS_TYPE_STREAM	0x04
669 	uByte		bOriginator;
670 } UPACKED uvideo_status_t;
671 
672 typedef struct {
673 	uByte		bStatusType;
674 	uByte		bOriginator;
675 	uByte		bEvent;
676 #define UV_CONTROL_CHANGE	0x00 /* any other value is Reserved */
677 	uByte		bSelector;
678 	uByte		bAttribute;
679 #define UV_CONTROL_VALUE_CHANGE		0x00
680 #define UV_CONTROL_INFO_CHANGE		0x01
681 #define UV_CONTROL_FAILURE_CHANGE	0x02
682 	uByte		bValue;
683 } UPACKED uvideo_control_status_t;
684 
685 typedef struct {
686 	uByte		bStatusType;
687 	uByte		bOriginator;
688 	uByte		bEvent;
689 #define UV_BUTTON_PRESS	0x00 /* any other value is Stream Error */
690 	uByte		bValue;
691 #define UV_BUTTON_RELEASED	0x00
692 #define UV_BUTTON_PRESSED	0x01
693 } UPACKED uvideo_streaming_status_t;
694 
695 typedef struct {
696 	uByte		bHeaderLength;
697 	uByte		bmHeaderInfo;
698 #define UV_FRAME_ID	1<<0
699 #define UV_END_OF_FRAME	1<<1
700 #define UV_PRES_TIME	1<<2
701 #define UV_SRC_CLOCK	1<<3
702 /* D4: Reserved */
703 #define UV_STILL_IMAGE	1<<5
704 #define UV_ERROR	1<<6
705 #define UV_END_OF_HDR	1<<7
706 /* other fields depend on which bits are set above and have no fixed offset */
707 /*	uDWord		dwPresentationTime; */
708 #define UVIDEO_PTS_SIZE 4
709 /*	uByte		scrSourceClock[UVIDEO_SOURCE_CLOCK_SIZE]; */
710 #define UVIDEO_SOURCE_CLOCK_SIZE 6
711 #define UV_GET_SOURCE_TIME_CLOCK(sc) (UGETDW(sc))
712 /* bits 42..32 */
713 #define UV_GET_SOF_COUNTER(sc) (((sc)[4] | ((sc)[5] << 8)) &0x7ff)
714 } UPACKED uvideo_payload_header_t;
715 
716 /* Note: this might be larger depending on presence of source clock,
717    SOF counter, or other things... bHeaderLength is actual length. */
718 #define UVIDEO_PAYLOAD_HEADER_SIZE 12
719 
720