xref: /openbmc/linux/drivers/media/usb/uvc/uvcvideo.h (revision 462cd772)
1 /* SPDX-License-Identifier: GPL-2.0 */
2 #ifndef _USB_VIDEO_H_
3 #define _USB_VIDEO_H_
4 
5 #ifndef __KERNEL__
6 #error "The uvcvideo.h header is deprecated, use linux/uvcvideo.h instead."
7 #endif /* __KERNEL__ */
8 
9 #include <linux/atomic.h>
10 #include <linux/kernel.h>
11 #include <linux/poll.h>
12 #include <linux/usb.h>
13 #include <linux/usb/video.h>
14 #include <linux/uvcvideo.h>
15 #include <linux/videodev2.h>
16 #include <linux/workqueue.h>
17 #include <media/media-device.h>
18 #include <media/v4l2-device.h>
19 #include <media/v4l2-event.h>
20 #include <media/v4l2-fh.h>
21 #include <media/videobuf2-v4l2.h>
22 
23 /* --------------------------------------------------------------------------
24  * UVC constants
25  */
26 
27 #define UVC_TERM_INPUT			0x0000
28 #define UVC_TERM_OUTPUT			0x8000
29 #define UVC_TERM_DIRECTION(term)	((term)->type & 0x8000)
30 
31 #define UVC_ENTITY_TYPE(entity)		((entity)->type & 0x7fff)
32 #define UVC_ENTITY_IS_UNIT(entity)	(((entity)->type & 0xff00) == 0)
33 #define UVC_ENTITY_IS_TERM(entity)	(((entity)->type & 0xff00) != 0)
34 #define UVC_ENTITY_IS_ITERM(entity) \
35 	(UVC_ENTITY_IS_TERM(entity) && \
36 	((entity)->type & 0x8000) == UVC_TERM_INPUT)
37 #define UVC_ENTITY_IS_OTERM(entity) \
38 	(UVC_ENTITY_IS_TERM(entity) && \
39 	((entity)->type & 0x8000) == UVC_TERM_OUTPUT)
40 
41 #define UVC_EXT_GPIO_UNIT		0x7ffe
42 #define UVC_EXT_GPIO_UNIT_ID		0x100
43 
44 /* ------------------------------------------------------------------------
45  * GUIDs
46  */
47 #define UVC_GUID_UVC_CAMERA \
48 	{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
49 	 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01}
50 #define UVC_GUID_UVC_OUTPUT \
51 	{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
52 	 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02}
53 #define UVC_GUID_UVC_MEDIA_TRANSPORT_INPUT \
54 	{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
55 	 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03}
56 #define UVC_GUID_UVC_PROCESSING \
57 	{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
58 	 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x01}
59 #define UVC_GUID_UVC_SELECTOR \
60 	{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
61 	 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02}
62 #define UVC_GUID_EXT_GPIO_CONTROLLER \
63 	{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
64 	 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x03}
65 
66 #define UVC_GUID_FORMAT_MJPEG \
67 	{ 'M',  'J',  'P',  'G', 0x00, 0x00, 0x10, 0x00, \
68 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
69 #define UVC_GUID_FORMAT_YUY2 \
70 	{ 'Y',  'U',  'Y',  '2', 0x00, 0x00, 0x10, 0x00, \
71 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
72 #define UVC_GUID_FORMAT_YUY2_ISIGHT \
73 	{ 'Y',  'U',  'Y',  '2', 0x00, 0x00, 0x10, 0x00, \
74 	 0x80, 0x00, 0x00, 0x00, 0x00, 0x38, 0x9b, 0x71}
75 #define UVC_GUID_FORMAT_NV12 \
76 	{ 'N',  'V',  '1',  '2', 0x00, 0x00, 0x10, 0x00, \
77 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
78 #define UVC_GUID_FORMAT_YV12 \
79 	{ 'Y',  'V',  '1',  '2', 0x00, 0x00, 0x10, 0x00, \
80 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
81 #define UVC_GUID_FORMAT_I420 \
82 	{ 'I',  '4',  '2',  '0', 0x00, 0x00, 0x10, 0x00, \
83 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
84 #define UVC_GUID_FORMAT_UYVY \
85 	{ 'U',  'Y',  'V',  'Y', 0x00, 0x00, 0x10, 0x00, \
86 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
87 #define UVC_GUID_FORMAT_Y800 \
88 	{ 'Y',  '8',  '0',  '0', 0x00, 0x00, 0x10, 0x00, \
89 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
90 #define UVC_GUID_FORMAT_Y8 \
91 	{ 'Y',  '8',  ' ',  ' ', 0x00, 0x00, 0x10, 0x00, \
92 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
93 #define UVC_GUID_FORMAT_Y10 \
94 	{ 'Y',  '1',  '0',  ' ', 0x00, 0x00, 0x10, 0x00, \
95 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
96 #define UVC_GUID_FORMAT_Y12 \
97 	{ 'Y',  '1',  '2',  ' ', 0x00, 0x00, 0x10, 0x00, \
98 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
99 #define UVC_GUID_FORMAT_Y16 \
100 	{ 'Y',  '1',  '6',  ' ', 0x00, 0x00, 0x10, 0x00, \
101 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
102 #define UVC_GUID_FORMAT_BY8 \
103 	{ 'B',  'Y',  '8',  ' ', 0x00, 0x00, 0x10, 0x00, \
104 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
105 #define UVC_GUID_FORMAT_BA81 \
106 	{ 'B',  'A',  '8',  '1', 0x00, 0x00, 0x10, 0x00, \
107 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
108 #define UVC_GUID_FORMAT_GBRG \
109 	{ 'G',  'B',  'R',  'G', 0x00, 0x00, 0x10, 0x00, \
110 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
111 #define UVC_GUID_FORMAT_GRBG \
112 	{ 'G',  'R',  'B',  'G', 0x00, 0x00, 0x10, 0x00, \
113 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
114 #define UVC_GUID_FORMAT_RGGB \
115 	{ 'R',  'G',  'G',  'B', 0x00, 0x00, 0x10, 0x00, \
116 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
117 #define UVC_GUID_FORMAT_BG16 \
118 	{ 'B',  'G',  '1',  '6', 0x00, 0x00, 0x10, 0x00, \
119 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
120 #define UVC_GUID_FORMAT_GB16 \
121 	{ 'G',  'B',  '1',  '6', 0x00, 0x00, 0x10, 0x00, \
122 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
123 #define UVC_GUID_FORMAT_RG16 \
124 	{ 'R',  'G',  '1',  '6', 0x00, 0x00, 0x10, 0x00, \
125 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
126 #define UVC_GUID_FORMAT_GR16 \
127 	{ 'G',  'R',  '1',  '6', 0x00, 0x00, 0x10, 0x00, \
128 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
129 #define UVC_GUID_FORMAT_RGBP \
130 	{ 'R',  'G',  'B',  'P', 0x00, 0x00, 0x10, 0x00, \
131 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
132 #define UVC_GUID_FORMAT_BGR3 \
133 	{ 0x7d, 0xeb, 0x36, 0xe4, 0x4f, 0x52, 0xce, 0x11, \
134 	 0x9f, 0x53, 0x00, 0x20, 0xaf, 0x0b, 0xa7, 0x70}
135 #define UVC_GUID_FORMAT_M420 \
136 	{ 'M',  '4',  '2',  '0', 0x00, 0x00, 0x10, 0x00, \
137 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
138 
139 #define UVC_GUID_FORMAT_H264 \
140 	{ 'H',  '2',  '6',  '4', 0x00, 0x00, 0x10, 0x00, \
141 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
142 #define UVC_GUID_FORMAT_H265 \
143 	{ 'H',  '2',  '6',  '5', 0x00, 0x00, 0x10, 0x00, \
144 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
145 #define UVC_GUID_FORMAT_Y8I \
146 	{ 'Y',  '8',  'I',  ' ', 0x00, 0x00, 0x10, 0x00, \
147 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
148 #define UVC_GUID_FORMAT_Y12I \
149 	{ 'Y',  '1',  '2',  'I', 0x00, 0x00, 0x10, 0x00, \
150 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
151 #define UVC_GUID_FORMAT_Z16 \
152 	{ 'Z',  '1',  '6',  ' ', 0x00, 0x00, 0x10, 0x00, \
153 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
154 #define UVC_GUID_FORMAT_RW10 \
155 	{ 'R',  'W',  '1',  '0', 0x00, 0x00, 0x10, 0x00, \
156 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
157 #define UVC_GUID_FORMAT_INVZ \
158 	{ 'I',  'N',  'V',  'Z', 0x90, 0x2d, 0x58, 0x4a, \
159 	 0x92, 0x0b, 0x77, 0x3f, 0x1f, 0x2c, 0x55, 0x6b}
160 #define UVC_GUID_FORMAT_INZI \
161 	{ 'I',  'N',  'Z',  'I', 0x66, 0x1a, 0x42, 0xa2, \
162 	 0x90, 0x65, 0xd0, 0x18, 0x14, 0xa8, 0xef, 0x8a}
163 #define UVC_GUID_FORMAT_INVI \
164 	{ 'I',  'N',  'V',  'I', 0xdb, 0x57, 0x49, 0x5e, \
165 	 0x8e, 0x3f, 0xf4, 0x79, 0x53, 0x2b, 0x94, 0x6f}
166 #define UVC_GUID_FORMAT_CNF4 \
167 	{ 'C',  ' ',  ' ',  ' ', 0x00, 0x00, 0x10, 0x00, \
168 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
169 
170 #define UVC_GUID_FORMAT_D3DFMT_L8 \
171 	{0x32, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, \
172 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
173 #define UVC_GUID_FORMAT_KSMEDIA_L8_IR \
174 	{0x32, 0x00, 0x00, 0x00, 0x02, 0x00, 0x10, 0x00, \
175 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
176 
177 #define UVC_GUID_FORMAT_HEVC \
178 	{ 'H',  'E',  'V',  'C', 0x00, 0x00, 0x10, 0x00, \
179 	 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
180 
181 
182 /* ------------------------------------------------------------------------
183  * Driver specific constants.
184  */
185 
186 #define DRIVER_VERSION		"1.1.1"
187 
188 /* Number of isochronous URBs. */
189 #define UVC_URBS		5
190 /* Maximum number of packets per URB. */
191 #define UVC_MAX_PACKETS		32
192 /* Maximum status buffer size in bytes of interrupt URB. */
193 #define UVC_MAX_STATUS_SIZE	16
194 
195 #define UVC_CTRL_CONTROL_TIMEOUT	5000
196 #define UVC_CTRL_STREAMING_TIMEOUT	5000
197 
198 /* Maximum allowed number of control mappings per device */
199 #define UVC_MAX_CONTROL_MAPPINGS	1024
200 #define UVC_MAX_CONTROL_MENU_ENTRIES	32
201 
202 /* Devices quirks */
203 #define UVC_QUIRK_STATUS_INTERVAL	0x00000001
204 #define UVC_QUIRK_PROBE_MINMAX		0x00000002
205 #define UVC_QUIRK_PROBE_EXTRAFIELDS	0x00000004
206 #define UVC_QUIRK_BUILTIN_ISIGHT	0x00000008
207 #define UVC_QUIRK_STREAM_NO_FID		0x00000010
208 #define UVC_QUIRK_IGNORE_SELECTOR_UNIT	0x00000020
209 #define UVC_QUIRK_FIX_BANDWIDTH		0x00000080
210 #define UVC_QUIRK_PROBE_DEF		0x00000100
211 #define UVC_QUIRK_RESTRICT_FRAME_RATE	0x00000200
212 #define UVC_QUIRK_RESTORE_CTRLS_ON_INIT	0x00000400
213 #define UVC_QUIRK_FORCE_Y8		0x00000800
214 #define UVC_QUIRK_FORCE_BPP		0x00001000
215 
216 /* Format flags */
217 #define UVC_FMT_FLAG_COMPRESSED		0x00000001
218 #define UVC_FMT_FLAG_STREAM		0x00000002
219 
220 /* ------------------------------------------------------------------------
221  * Structures.
222  */
223 
224 struct gpio_desc;
225 struct sg_table;
226 struct uvc_device;
227 
228 /*
229  * TODO: Put the most frequently accessed fields at the beginning of
230  * structures to maximize cache efficiency.
231  */
232 struct uvc_control_info {
233 	struct list_head mappings;
234 
235 	u8 entity[16];
236 	u8 index;	/* Bit index in bmControls */
237 	u8 selector;
238 
239 	u16 size;
240 	u32 flags;
241 };
242 
243 struct uvc_control_mapping {
244 	struct list_head list;
245 	struct list_head ev_subs;
246 
247 	u32 id;
248 	char *name;
249 	u8 entity[16];
250 	u8 selector;
251 
252 	u8 size;
253 	u8 offset;
254 	enum v4l2_ctrl_type v4l2_type;
255 	u32 data_type;
256 
257 	const struct uvc_menu_info *menu_info;
258 	u32 menu_count;
259 
260 	u32 master_id;
261 	s32 master_manual;
262 	u32 slave_ids[2];
263 
264 	s32 (*get)(struct uvc_control_mapping *mapping, u8 query,
265 		   const u8 *data);
266 	void (*set)(struct uvc_control_mapping *mapping, s32 value,
267 		    u8 *data);
268 };
269 
270 struct uvc_control {
271 	struct uvc_entity *entity;
272 	struct uvc_control_info info;
273 
274 	u8 index;	/* Used to match the uvc_control entry with a uvc_control_info. */
275 	u8 dirty:1,
276 	   loaded:1,
277 	   modified:1,
278 	   cached:1,
279 	   initialized:1;
280 
281 	u8 *uvc_data;
282 
283 	struct uvc_fh *handle;	/* File handle that last changed the control. */
284 };
285 
286 struct uvc_format_desc {
287 	char *name;
288 	u8 guid[16];
289 	u32 fcc;
290 };
291 
292 /*
293  * The term 'entity' refers to both UVC units and UVC terminals.
294  *
295  * The type field is either the terminal type (wTerminalType in the terminal
296  * descriptor), or the unit type (bDescriptorSubtype in the unit descriptor).
297  * As the bDescriptorSubtype field is one byte long, the type value will
298  * always have a null MSB for units. All terminal types defined by the UVC
299  * specification have a non-null MSB, so it is safe to use the MSB to
300  * differentiate between units and terminals as long as the descriptor parsing
301  * code makes sure terminal types have a non-null MSB.
302  *
303  * For terminals, the type's most significant bit stores the terminal
304  * direction (either UVC_TERM_INPUT or UVC_TERM_OUTPUT). The type field should
305  * always be accessed with the UVC_ENTITY_* macros and never directly.
306  */
307 
308 #define UVC_ENTITY_FLAG_DEFAULT		(1 << 0)
309 
310 struct uvc_entity {
311 	struct list_head list;		/* Entity as part of a UVC device. */
312 	struct list_head chain;		/* Entity as part of a video device chain. */
313 	unsigned int flags;
314 
315 	/*
316 	 * Entities exposed by the UVC device use IDs 0-255, extra entities
317 	 * implemented by the driver (such as the GPIO entity) use IDs 256 and
318 	 * up.
319 	 */
320 	u16 id;
321 	u16 type;
322 	char name[64];
323 	u8 guid[16];
324 
325 	/* Media controller-related fields. */
326 	struct video_device *vdev;
327 	struct v4l2_subdev subdev;
328 	unsigned int num_pads;
329 	unsigned int num_links;
330 	struct media_pad *pads;
331 
332 	union {
333 		struct {
334 			u16 wObjectiveFocalLengthMin;
335 			u16 wObjectiveFocalLengthMax;
336 			u16 wOcularFocalLength;
337 			u8  bControlSize;
338 			u8  *bmControls;
339 		} camera;
340 
341 		struct {
342 			u8  bControlSize;
343 			u8  *bmControls;
344 			u8  bTransportModeSize;
345 			u8  *bmTransportModes;
346 		} media;
347 
348 		struct {
349 		} output;
350 
351 		struct {
352 			u16 wMaxMultiplier;
353 			u8  bControlSize;
354 			u8  *bmControls;
355 			u8  bmVideoStandards;
356 		} processing;
357 
358 		struct {
359 		} selector;
360 
361 		struct {
362 			u8  bNumControls;
363 			u8  bControlSize;
364 			u8  *bmControls;
365 			u8  *bmControlsType;
366 		} extension;
367 
368 		struct {
369 			u8  bControlSize;
370 			u8  *bmControls;
371 			struct gpio_desc *gpio_privacy;
372 			int irq;
373 		} gpio;
374 	};
375 
376 	u8 bNrInPins;
377 	u8 *baSourceID;
378 
379 	int (*get_info)(struct uvc_device *dev, struct uvc_entity *entity,
380 			u8 cs, u8 *caps);
381 	int (*get_cur)(struct uvc_device *dev, struct uvc_entity *entity,
382 		       u8 cs, void *data, u16 size);
383 
384 	unsigned int ncontrols;
385 	struct uvc_control *controls;
386 };
387 
388 struct uvc_frame {
389 	u8  bFrameIndex;
390 	u8  bmCapabilities;
391 	u16 wWidth;
392 	u16 wHeight;
393 	u32 dwMinBitRate;
394 	u32 dwMaxBitRate;
395 	u32 dwMaxVideoFrameBufferSize;
396 	u8  bFrameIntervalType;
397 	u32 dwDefaultFrameInterval;
398 	u32 *dwFrameInterval;
399 };
400 
401 struct uvc_format {
402 	u8 type;
403 	u8 index;
404 	u8 bpp;
405 	enum v4l2_colorspace colorspace;
406 	enum v4l2_xfer_func xfer_func;
407 	enum v4l2_ycbcr_encoding ycbcr_enc;
408 	u32 fcc;
409 	u32 flags;
410 
411 	char name[32];
412 
413 	unsigned int nframes;
414 	struct uvc_frame *frame;
415 };
416 
417 struct uvc_streaming_header {
418 	u8 bNumFormats;
419 	u8 bEndpointAddress;
420 	u8 bTerminalLink;
421 	u8 bControlSize;
422 	u8 *bmaControls;
423 	/* The following fields are used by input headers only. */
424 	u8 bmInfo;
425 	u8 bStillCaptureMethod;
426 	u8 bTriggerSupport;
427 	u8 bTriggerUsage;
428 };
429 
430 enum uvc_buffer_state {
431 	UVC_BUF_STATE_IDLE	= 0,
432 	UVC_BUF_STATE_QUEUED	= 1,
433 	UVC_BUF_STATE_ACTIVE	= 2,
434 	UVC_BUF_STATE_READY	= 3,
435 	UVC_BUF_STATE_DONE	= 4,
436 	UVC_BUF_STATE_ERROR	= 5,
437 };
438 
439 struct uvc_buffer {
440 	struct vb2_v4l2_buffer buf;
441 	struct list_head queue;
442 
443 	enum uvc_buffer_state state;
444 	unsigned int error;
445 
446 	void *mem;
447 	unsigned int length;
448 	unsigned int bytesused;
449 
450 	u32 pts;
451 
452 	/* Asynchronous buffer handling. */
453 	struct kref ref;
454 };
455 
456 #define UVC_QUEUE_DISCONNECTED		(1 << 0)
457 #define UVC_QUEUE_DROP_CORRUPTED	(1 << 1)
458 
459 struct uvc_video_queue {
460 	struct vb2_queue queue;
461 	struct mutex mutex;			/* Protects queue */
462 
463 	unsigned int flags;
464 	unsigned int buf_used;
465 
466 	spinlock_t irqlock;			/* Protects irqqueue */
467 	struct list_head irqqueue;
468 };
469 
470 struct uvc_video_chain {
471 	struct uvc_device *dev;
472 	struct list_head list;
473 
474 	struct list_head entities;		/* All entities */
475 	struct uvc_entity *processing;		/* Processing unit */
476 	struct uvc_entity *selector;		/* Selector unit */
477 
478 	struct mutex ctrl_mutex;		/* Protects ctrl.info */
479 
480 	struct v4l2_prio_state prio;		/* V4L2 priority state */
481 	u32 caps;				/* V4L2 chain-wide caps */
482 	u8 ctrl_class_bitmap;			/* Bitmap of valid classes */
483 };
484 
485 struct uvc_stats_frame {
486 	unsigned int size;		/* Number of bytes captured */
487 	unsigned int first_data;	/* Index of the first non-empty packet */
488 
489 	unsigned int nb_packets;	/* Number of packets */
490 	unsigned int nb_empty;		/* Number of empty packets */
491 	unsigned int nb_invalid;	/* Number of packets with an invalid header */
492 	unsigned int nb_errors;		/* Number of packets with the error bit set */
493 
494 	unsigned int nb_pts;		/* Number of packets with a PTS timestamp */
495 	unsigned int nb_pts_diffs;	/* Number of PTS differences inside a frame */
496 	unsigned int last_pts_diff;	/* Index of the last PTS difference */
497 	bool has_initial_pts;		/* Whether the first non-empty packet has a PTS */
498 	bool has_early_pts;		/* Whether a PTS is present before the first non-empty packet */
499 	u32 pts;			/* PTS of the last packet */
500 
501 	unsigned int nb_scr;		/* Number of packets with a SCR timestamp */
502 	unsigned int nb_scr_diffs;	/* Number of SCR.STC differences inside a frame */
503 	u16 scr_sof;			/* SCR.SOF of the last packet */
504 	u32 scr_stc;			/* SCR.STC of the last packet */
505 };
506 
507 struct uvc_stats_stream {
508 	ktime_t start_ts;		/* Stream start timestamp */
509 	ktime_t stop_ts;		/* Stream stop timestamp */
510 
511 	unsigned int nb_frames;		/* Number of frames */
512 
513 	unsigned int nb_packets;	/* Number of packets */
514 	unsigned int nb_empty;		/* Number of empty packets */
515 	unsigned int nb_invalid;	/* Number of packets with an invalid header */
516 	unsigned int nb_errors;		/* Number of packets with the error bit set */
517 
518 	unsigned int nb_pts_constant;	/* Number of frames with constant PTS */
519 	unsigned int nb_pts_early;	/* Number of frames with early PTS */
520 	unsigned int nb_pts_initial;	/* Number of frames with initial PTS */
521 
522 	unsigned int nb_scr_count_ok;	/* Number of frames with at least one SCR per non empty packet */
523 	unsigned int nb_scr_diffs_ok;	/* Number of frames with varying SCR.STC */
524 	unsigned int scr_sof_count;	/* STC.SOF counter accumulated since stream start */
525 	unsigned int scr_sof;		/* STC.SOF of the last packet */
526 	unsigned int min_sof;		/* Minimum STC.SOF value */
527 	unsigned int max_sof;		/* Maximum STC.SOF value */
528 };
529 
530 #define UVC_METADATA_BUF_SIZE 10240
531 
532 /**
533  * struct uvc_copy_op: Context structure to schedule asynchronous memcpy
534  *
535  * @buf: active buf object for this operation
536  * @dst: copy destination address
537  * @src: copy source address
538  * @len: copy length
539  */
540 struct uvc_copy_op {
541 	struct uvc_buffer *buf;
542 	void *dst;
543 	const __u8 *src;
544 	size_t len;
545 };
546 
547 /**
548  * struct uvc_urb - URB context management structure
549  *
550  * @urb: the URB described by this context structure
551  * @stream: UVC streaming context
552  * @buffer: memory storage for the URB
553  * @dma: Allocated DMA handle
554  * @sgt: sgt_table with the urb locations in memory
555  * @async_operations: counter to indicate the number of copy operations
556  * @copy_operations: work descriptors for asynchronous copy operations
557  * @work: work queue entry for asynchronous decode
558  */
559 struct uvc_urb {
560 	struct urb *urb;
561 	struct uvc_streaming *stream;
562 
563 	char *buffer;
564 	dma_addr_t dma;
565 	struct sg_table *sgt;
566 
567 	unsigned int async_operations;
568 	struct uvc_copy_op copy_operations[UVC_MAX_PACKETS];
569 	struct work_struct work;
570 };
571 
572 struct uvc_streaming {
573 	struct list_head list;
574 	struct uvc_device *dev;
575 	struct video_device vdev;
576 	struct uvc_video_chain *chain;
577 	atomic_t active;
578 
579 	struct usb_interface *intf;
580 	int intfnum;
581 	u16 maxpsize;
582 
583 	struct uvc_streaming_header header;
584 	enum v4l2_buf_type type;
585 
586 	unsigned int nformats;
587 	struct uvc_format *format;
588 
589 	struct uvc_streaming_control ctrl;
590 	struct uvc_format *def_format;
591 	struct uvc_format *cur_format;
592 	struct uvc_frame *cur_frame;
593 
594 	/*
595 	 * Protect access to ctrl, cur_format, cur_frame and hardware video
596 	 * probe control.
597 	 */
598 	struct mutex mutex;
599 
600 	/* Buffers queue. */
601 	unsigned int frozen : 1;
602 	struct uvc_video_queue queue;
603 	struct workqueue_struct *async_wq;
604 	void (*decode)(struct uvc_urb *uvc_urb, struct uvc_buffer *buf,
605 		       struct uvc_buffer *meta_buf);
606 
607 	struct {
608 		struct video_device vdev;
609 		struct uvc_video_queue queue;
610 		u32 format;
611 	} meta;
612 
613 	/* Context data used by the bulk completion handler. */
614 	struct {
615 		u8 header[256];
616 		unsigned int header_size;
617 		int skip_payload;
618 		u32 payload_size;
619 		u32 max_payload_size;
620 	} bulk;
621 
622 	struct uvc_urb uvc_urb[UVC_URBS];
623 	unsigned int urb_size;
624 
625 	u32 sequence;
626 	u8 last_fid;
627 
628 	/* debugfs */
629 	struct dentry *debugfs_dir;
630 	struct {
631 		struct uvc_stats_frame frame;
632 		struct uvc_stats_stream stream;
633 	} stats;
634 
635 	/* Timestamps support. */
636 	struct uvc_clock {
637 		struct uvc_clock_sample {
638 			u32 dev_stc;
639 			u16 dev_sof;
640 			u16 host_sof;
641 			ktime_t host_time;
642 		} *samples;
643 
644 		unsigned int head;
645 		unsigned int count;
646 		unsigned int size;
647 
648 		u16 last_sof;
649 		u16 sof_offset;
650 
651 		u8 last_scr[6];
652 
653 		spinlock_t lock;
654 	} clock;
655 };
656 
657 #define for_each_uvc_urb(uvc_urb, uvc_streaming) \
658 	for ((uvc_urb) = &(uvc_streaming)->uvc_urb[0]; \
659 	     (uvc_urb) < &(uvc_streaming)->uvc_urb[UVC_URBS]; \
660 	     ++(uvc_urb))
661 
662 static inline u32 uvc_urb_index(const struct uvc_urb *uvc_urb)
663 {
664 	return uvc_urb - &uvc_urb->stream->uvc_urb[0];
665 }
666 
667 struct uvc_device_info {
668 	u32	quirks;
669 	u32	meta_format;
670 	u16	uvc_version;
671 	const struct uvc_control_mapping **mappings;
672 };
673 
674 struct uvc_device {
675 	struct usb_device *udev;
676 	struct usb_interface *intf;
677 	unsigned long warnings;
678 	u32 quirks;
679 	int intfnum;
680 	char name[32];
681 
682 	const struct uvc_device_info *info;
683 
684 	struct mutex lock;		/* Protects users */
685 	unsigned int users;
686 	atomic_t nmappings;
687 
688 	/* Video control interface */
689 #ifdef CONFIG_MEDIA_CONTROLLER
690 	struct media_device mdev;
691 #endif
692 	struct v4l2_device vdev;
693 	u16 uvc_version;
694 	u32 clock_frequency;
695 
696 	struct list_head entities;
697 	struct list_head chains;
698 
699 	/* Video Streaming interfaces */
700 	struct list_head streams;
701 	struct kref ref;
702 
703 	/* Status Interrupt Endpoint */
704 	struct usb_host_endpoint *int_ep;
705 	struct urb *int_urb;
706 	u8 *status;
707 	struct input_dev *input;
708 	char input_phys[64];
709 
710 	struct uvc_ctrl_work {
711 		struct work_struct work;
712 		struct urb *urb;
713 		struct uvc_video_chain *chain;
714 		struct uvc_control *ctrl;
715 		const void *data;
716 	} async_ctrl;
717 
718 	struct uvc_entity *gpio_unit;
719 };
720 
721 enum uvc_handle_state {
722 	UVC_HANDLE_PASSIVE	= 0,
723 	UVC_HANDLE_ACTIVE	= 1,
724 };
725 
726 struct uvc_fh {
727 	struct v4l2_fh vfh;
728 	struct uvc_video_chain *chain;
729 	struct uvc_streaming *stream;
730 	enum uvc_handle_state state;
731 };
732 
733 struct uvc_driver {
734 	struct usb_driver driver;
735 };
736 
737 /* ------------------------------------------------------------------------
738  * Debugging, printing and logging
739  */
740 
741 #define UVC_DBG_PROBE		(1 << 0)
742 #define UVC_DBG_DESCR		(1 << 1)
743 #define UVC_DBG_CONTROL		(1 << 2)
744 #define UVC_DBG_FORMAT		(1 << 3)
745 #define UVC_DBG_CAPTURE		(1 << 4)
746 #define UVC_DBG_CALLS		(1 << 5)
747 #define UVC_DBG_FRAME		(1 << 7)
748 #define UVC_DBG_SUSPEND		(1 << 8)
749 #define UVC_DBG_STATUS		(1 << 9)
750 #define UVC_DBG_VIDEO		(1 << 10)
751 #define UVC_DBG_STATS		(1 << 11)
752 #define UVC_DBG_CLOCK		(1 << 12)
753 
754 #define UVC_WARN_MINMAX		0
755 #define UVC_WARN_PROBE_DEF	1
756 #define UVC_WARN_XU_GET_RES	2
757 
758 extern unsigned int uvc_clock_param;
759 extern unsigned int uvc_no_drop_param;
760 extern unsigned int uvc_dbg_param;
761 extern unsigned int uvc_timeout_param;
762 extern unsigned int uvc_hw_timestamps_param;
763 
764 #define uvc_dbg(_dev, flag, fmt, ...)					\
765 do {									\
766 	if (uvc_dbg_param & UVC_DBG_##flag)				\
767 		dev_printk(KERN_DEBUG, &(_dev)->udev->dev, fmt,		\
768 			   ##__VA_ARGS__);				\
769 } while (0)
770 
771 #define uvc_dbg_cont(flag, fmt, ...)					\
772 do {									\
773 	if (uvc_dbg_param & UVC_DBG_##flag)				\
774 		pr_cont(fmt, ##__VA_ARGS__);				\
775 } while (0)
776 
777 #define uvc_warn_once(_dev, warn, fmt, ...)				\
778 do {									\
779 	if (!test_and_set_bit(warn, &(_dev)->warnings))			\
780 		dev_info(&(_dev)->udev->dev, fmt, ##__VA_ARGS__);	\
781 } while (0)
782 
783 /* --------------------------------------------------------------------------
784  * Internal functions.
785  */
786 
787 /* Core driver */
788 extern struct uvc_driver uvc_driver;
789 
790 struct uvc_entity *uvc_entity_by_id(struct uvc_device *dev, int id);
791 
792 /* Video buffers queue management. */
793 int uvc_queue_init(struct uvc_video_queue *queue, enum v4l2_buf_type type,
794 		   int drop_corrupted);
795 void uvc_queue_release(struct uvc_video_queue *queue);
796 int uvc_request_buffers(struct uvc_video_queue *queue,
797 			struct v4l2_requestbuffers *rb);
798 int uvc_query_buffer(struct uvc_video_queue *queue,
799 		     struct v4l2_buffer *v4l2_buf);
800 int uvc_create_buffers(struct uvc_video_queue *queue,
801 		       struct v4l2_create_buffers *v4l2_cb);
802 int uvc_queue_buffer(struct uvc_video_queue *queue,
803 		     struct media_device *mdev,
804 		     struct v4l2_buffer *v4l2_buf);
805 int uvc_export_buffer(struct uvc_video_queue *queue,
806 		      struct v4l2_exportbuffer *exp);
807 int uvc_dequeue_buffer(struct uvc_video_queue *queue,
808 		       struct v4l2_buffer *v4l2_buf, int nonblocking);
809 int uvc_queue_streamon(struct uvc_video_queue *queue, enum v4l2_buf_type type);
810 int uvc_queue_streamoff(struct uvc_video_queue *queue, enum v4l2_buf_type type);
811 void uvc_queue_cancel(struct uvc_video_queue *queue, int disconnect);
812 struct uvc_buffer *uvc_queue_next_buffer(struct uvc_video_queue *queue,
813 					 struct uvc_buffer *buf);
814 struct uvc_buffer *uvc_queue_get_current_buffer(struct uvc_video_queue *queue);
815 void uvc_queue_buffer_release(struct uvc_buffer *buf);
816 int uvc_queue_mmap(struct uvc_video_queue *queue,
817 		   struct vm_area_struct *vma);
818 __poll_t uvc_queue_poll(struct uvc_video_queue *queue, struct file *file,
819 			poll_table *wait);
820 #ifndef CONFIG_MMU
821 unsigned long uvc_queue_get_unmapped_area(struct uvc_video_queue *queue,
822 					  unsigned long pgoff);
823 #endif
824 int uvc_queue_allocated(struct uvc_video_queue *queue);
825 static inline int uvc_queue_streaming(struct uvc_video_queue *queue)
826 {
827 	return vb2_is_streaming(&queue->queue);
828 }
829 
830 static inline struct uvc_streaming *
831 uvc_queue_to_stream(struct uvc_video_queue *queue)
832 {
833 	return container_of(queue, struct uvc_streaming, queue);
834 }
835 
836 /* V4L2 interface */
837 extern const struct v4l2_ioctl_ops uvc_ioctl_ops;
838 extern const struct v4l2_file_operations uvc_fops;
839 
840 /* Media controller */
841 int uvc_mc_register_entities(struct uvc_video_chain *chain);
842 void uvc_mc_cleanup_entity(struct uvc_entity *entity);
843 
844 /* Video */
845 int uvc_video_init(struct uvc_streaming *stream);
846 int uvc_video_suspend(struct uvc_streaming *stream);
847 int uvc_video_resume(struct uvc_streaming *stream, int reset);
848 int uvc_video_start_streaming(struct uvc_streaming *stream);
849 void uvc_video_stop_streaming(struct uvc_streaming *stream);
850 int uvc_probe_video(struct uvc_streaming *stream,
851 		    struct uvc_streaming_control *probe);
852 int uvc_query_ctrl(struct uvc_device *dev, u8 query, u8 unit,
853 		   u8 intfnum, u8 cs, void *data, u16 size);
854 void uvc_video_clock_update(struct uvc_streaming *stream,
855 			    struct vb2_v4l2_buffer *vbuf,
856 			    struct uvc_buffer *buf);
857 int uvc_meta_register(struct uvc_streaming *stream);
858 
859 int uvc_register_video_device(struct uvc_device *dev,
860 			      struct uvc_streaming *stream,
861 			      struct video_device *vdev,
862 			      struct uvc_video_queue *queue,
863 			      enum v4l2_buf_type type,
864 			      const struct v4l2_file_operations *fops,
865 			      const struct v4l2_ioctl_ops *ioctl_ops);
866 
867 /* Status */
868 int uvc_status_init(struct uvc_device *dev);
869 void uvc_status_unregister(struct uvc_device *dev);
870 void uvc_status_cleanup(struct uvc_device *dev);
871 int uvc_status_start(struct uvc_device *dev, gfp_t flags);
872 void uvc_status_stop(struct uvc_device *dev);
873 
874 /* Controls */
875 extern const struct v4l2_subscribed_event_ops uvc_ctrl_sub_ev_ops;
876 
877 int uvc_query_v4l2_ctrl(struct uvc_video_chain *chain,
878 			struct v4l2_queryctrl *v4l2_ctrl);
879 int uvc_query_v4l2_menu(struct uvc_video_chain *chain,
880 			struct v4l2_querymenu *query_menu);
881 
882 int uvc_ctrl_add_mapping(struct uvc_video_chain *chain,
883 			 const struct uvc_control_mapping *mapping);
884 int uvc_ctrl_init_device(struct uvc_device *dev);
885 void uvc_ctrl_cleanup_device(struct uvc_device *dev);
886 int uvc_ctrl_restore_values(struct uvc_device *dev);
887 bool uvc_ctrl_status_event_async(struct urb *urb, struct uvc_video_chain *chain,
888 				 struct uvc_control *ctrl, const u8 *data);
889 void uvc_ctrl_status_event(struct uvc_video_chain *chain,
890 			   struct uvc_control *ctrl, const u8 *data);
891 
892 int uvc_ctrl_begin(struct uvc_video_chain *chain);
893 int __uvc_ctrl_commit(struct uvc_fh *handle, int rollback,
894 		      struct v4l2_ext_controls *ctrls);
895 static inline int uvc_ctrl_commit(struct uvc_fh *handle,
896 				  struct v4l2_ext_controls *ctrls)
897 {
898 	return __uvc_ctrl_commit(handle, 0, ctrls);
899 }
900 static inline int uvc_ctrl_rollback(struct uvc_fh *handle)
901 {
902 	return __uvc_ctrl_commit(handle, 1, NULL);
903 }
904 
905 int uvc_ctrl_get(struct uvc_video_chain *chain, struct v4l2_ext_control *xctrl);
906 int uvc_ctrl_set(struct uvc_fh *handle, struct v4l2_ext_control *xctrl);
907 int uvc_ctrl_is_accessible(struct uvc_video_chain *chain, u32 v4l2_id,
908 			   bool read);
909 
910 int uvc_xu_ctrl_query(struct uvc_video_chain *chain,
911 		      struct uvc_xu_control_query *xqry);
912 
913 /* Utility functions */
914 void uvc_simplify_fraction(u32 *numerator, u32 *denominator,
915 			   unsigned int n_terms, unsigned int threshold);
916 u32 uvc_fraction_to_interval(u32 numerator, u32 denominator);
917 struct usb_host_endpoint *uvc_find_endpoint(struct usb_host_interface *alts,
918 					    u8 epaddr);
919 u16 uvc_endpoint_max_bpi(struct usb_device *dev, struct usb_host_endpoint *ep);
920 
921 /* Quirks support */
922 void uvc_video_decode_isight(struct uvc_urb *uvc_urb,
923 			     struct uvc_buffer *buf,
924 			     struct uvc_buffer *meta_buf);
925 
926 /* debugfs and statistics */
927 void uvc_debugfs_init(void);
928 void uvc_debugfs_cleanup(void);
929 void uvc_debugfs_init_stream(struct uvc_streaming *stream);
930 void uvc_debugfs_cleanup_stream(struct uvc_streaming *stream);
931 
932 size_t uvc_video_stats_dump(struct uvc_streaming *stream, char *buf,
933 			    size_t size);
934 
935 #endif
936