4 #include <linux/kernel.h>
5 #include <linux/videodev2.h>
9 * This header provides binary compatibility with applications using the private
10 * uvcvideo API. This API is deprecated and will be removed in 2.6.42.
11 * Applications should be recompiled against the public linux/uvcvideo.h header.
13 #warn "The uvcvideo.h header is deprecated, use linux/uvcvideo.h instead."
19 /* Data types for UVC control data */
20 #define UVC_CTRL_DATA_TYPE_RAW 0
21 #define UVC_CTRL_DATA_TYPE_SIGNED 1
22 #define UVC_CTRL_DATA_TYPE_UNSIGNED 2
23 #define UVC_CTRL_DATA_TYPE_BOOLEAN 3
24 #define UVC_CTRL_DATA_TYPE_ENUM 4
25 #define UVC_CTRL_DATA_TYPE_BITMASK 5
28 #define UVC_CONTROL_SET_CUR (1 << 0)
29 #define UVC_CONTROL_GET_CUR (1 << 1)
30 #define UVC_CONTROL_GET_MIN (1 << 2)
31 #define UVC_CONTROL_GET_MAX (1 << 3)
32 #define UVC_CONTROL_GET_RES (1 << 4)
33 #define UVC_CONTROL_GET_DEF (1 << 5)
34 #define UVC_CONTROL_RESTORE (1 << 6)
35 #define UVC_CONTROL_AUTO_UPDATE (1 << 7)
37 #define UVC_CONTROL_GET_RANGE (UVC_CONTROL_GET_CUR | UVC_CONTROL_GET_MIN | \
38 UVC_CONTROL_GET_MAX | UVC_CONTROL_GET_RES | \
41 struct uvc_menu_info {
46 struct uvc_xu_control_mapping {
57 struct uvc_menu_info __user *menu_info;
65 struct uvc_xu_control_info {
73 struct uvc_xu_control_mapping_old {
77 struct uvc_xu_control {
85 #define UVCIOC_CTRL_ADD _IOW('U', 1, struct uvc_xu_control_info)
86 #define UVCIOC_CTRL_MAP_OLD _IOWR('U', 2, struct uvc_xu_control_mapping_old)
87 #define UVCIOC_CTRL_MAP _IOWR('U', 2, struct uvc_xu_control_mapping)
88 #define UVCIOC_CTRL_GET _IOWR('U', 3, struct uvc_xu_control)
89 #define UVCIOC_CTRL_SET _IOW('U', 4, struct uvc_xu_control)
91 #define __UVCIOC_CTRL_ADD _IOW('U', 1, struct uvc_xu_control_info)
92 #define __UVCIOC_CTRL_MAP_OLD _IOWR('U', 2, struct uvc_xu_control_mapping_old)
93 #define __UVCIOC_CTRL_MAP _IOWR('U', 2, struct uvc_xu_control_mapping)
94 #define __UVCIOC_CTRL_GET _IOWR('U', 3, struct uvc_xu_control)
95 #define __UVCIOC_CTRL_SET _IOW('U', 4, struct uvc_xu_control)
100 #include <linux/poll.h>
101 #include <linux/usb.h>
102 #include <linux/usb/video.h>
103 #include <linux/uvcvideo.h>
104 #include <media/media-device.h>
105 #include <media/v4l2-device.h>
107 /* --------------------------------------------------------------------------
111 #define UVC_TERM_INPUT 0x0000
112 #define UVC_TERM_OUTPUT 0x8000
113 #define UVC_TERM_DIRECTION(term) ((term)->type & 0x8000)
115 #define UVC_ENTITY_TYPE(entity) ((entity)->type & 0x7fff)
116 #define UVC_ENTITY_IS_UNIT(entity) (((entity)->type & 0xff00) == 0)
117 #define UVC_ENTITY_IS_TERM(entity) (((entity)->type & 0xff00) != 0)
118 #define UVC_ENTITY_IS_ITERM(entity) \
119 (UVC_ENTITY_IS_TERM(entity) && \
120 ((entity)->type & 0x8000) == UVC_TERM_INPUT)
121 #define UVC_ENTITY_IS_OTERM(entity) \
122 (UVC_ENTITY_IS_TERM(entity) && \
123 ((entity)->type & 0x8000) == UVC_TERM_OUTPUT)
126 /* ------------------------------------------------------------------------
129 #define UVC_GUID_UVC_CAMERA \
130 {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
131 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01}
132 #define UVC_GUID_UVC_OUTPUT \
133 {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
134 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02}
135 #define UVC_GUID_UVC_MEDIA_TRANSPORT_INPUT \
136 {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
137 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03}
138 #define UVC_GUID_UVC_PROCESSING \
139 {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
140 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x01}
141 #define UVC_GUID_UVC_SELECTOR \
142 {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, \
143 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02}
145 #define UVC_GUID_FORMAT_MJPEG \
146 { 'M', 'J', 'P', 'G', 0x00, 0x00, 0x10, 0x00, \
147 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
148 #define UVC_GUID_FORMAT_YUY2 \
149 { 'Y', 'U', 'Y', '2', 0x00, 0x00, 0x10, 0x00, \
150 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
151 #define UVC_GUID_FORMAT_YUY2_ISIGHT \
152 { 'Y', 'U', 'Y', '2', 0x00, 0x00, 0x10, 0x00, \
153 0x80, 0x00, 0x00, 0x00, 0x00, 0x38, 0x9b, 0x71}
154 #define UVC_GUID_FORMAT_NV12 \
155 { 'N', 'V', '1', '2', 0x00, 0x00, 0x10, 0x00, \
156 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
157 #define UVC_GUID_FORMAT_YV12 \
158 { 'Y', 'V', '1', '2', 0x00, 0x00, 0x10, 0x00, \
159 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
160 #define UVC_GUID_FORMAT_I420 \
161 { 'I', '4', '2', '0', 0x00, 0x00, 0x10, 0x00, \
162 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
163 #define UVC_GUID_FORMAT_UYVY \
164 { 'U', 'Y', 'V', 'Y', 0x00, 0x00, 0x10, 0x00, \
165 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
166 #define UVC_GUID_FORMAT_Y800 \
167 { 'Y', '8', '0', '0', 0x00, 0x00, 0x10, 0x00, \
168 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
169 #define UVC_GUID_FORMAT_Y16 \
170 { 'Y', '1', '6', ' ', 0x00, 0x00, 0x10, 0x00, \
171 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
172 #define UVC_GUID_FORMAT_BY8 \
173 { 'B', 'Y', '8', ' ', 0x00, 0x00, 0x10, 0x00, \
174 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
175 #define UVC_GUID_FORMAT_RGBP \
176 { 'R', 'G', 'B', 'P', 0x00, 0x00, 0x10, 0x00, \
177 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
178 #define UVC_GUID_FORMAT_M420 \
179 { 'M', '4', '2', '0', 0x00, 0x00, 0x10, 0x00, \
180 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71}
182 /* ------------------------------------------------------------------------
183 * Driver specific constants.
186 #define DRIVER_VERSION_NUMBER KERNEL_VERSION(1, 1, 0)
187 #define DRIVER_VERSION "v1.1.0"
189 /* Number of isochronous URBs. */
191 /* Maximum number of packets per URB. */
192 #define UVC_MAX_PACKETS 32
193 /* Maximum number of video buffers. */
194 #define UVC_MAX_VIDEO_BUFFERS 32
195 /* Maximum status buffer size in bytes of interrupt URB. */
196 #define UVC_MAX_STATUS_SIZE 16
198 #define UVC_CTRL_CONTROL_TIMEOUT 300
199 #define UVC_CTRL_STREAMING_TIMEOUT 5000
201 /* Maximum allowed number of control mappings per device */
202 #define UVC_MAX_CONTROL_MAPPINGS 1024
205 #define UVC_QUIRK_STATUS_INTERVAL 0x00000001
206 #define UVC_QUIRK_PROBE_MINMAX 0x00000002
207 #define UVC_QUIRK_PROBE_EXTRAFIELDS 0x00000004
208 #define UVC_QUIRK_BUILTIN_ISIGHT 0x00000008
209 #define UVC_QUIRK_STREAM_NO_FID 0x00000010
210 #define UVC_QUIRK_IGNORE_SELECTOR_UNIT 0x00000020
211 #define UVC_QUIRK_FIX_BANDWIDTH 0x00000080
212 #define UVC_QUIRK_PROBE_DEF 0x00000100
213 #define UVC_QUIRK_RESTRICT_FRAME_RATE 0x00000200
216 #define UVC_FMT_FLAG_COMPRESSED 0x00000001
217 #define UVC_FMT_FLAG_STREAM 0x00000002
219 /* ------------------------------------------------------------------------
225 /* TODO: Put the most frequently accessed fields at the beginning of
226 * structures to maximize cache efficiency.
228 struct uvc_control_info {
229 struct list_head mappings;
232 __u8 index; /* Bit index in bmControls */
239 struct uvc_control_mapping {
240 struct list_head list;
242 struct uvc_control_info *ctrl;
251 enum v4l2_ctrl_type v4l2_type;
254 struct uvc_menu_info *menu_info;
257 __s32 (*get) (struct uvc_control_mapping *mapping, __u8 query,
259 void (*set) (struct uvc_control_mapping *mapping, __s32 value,
264 struct uvc_entity *entity;
265 struct uvc_control_info info;
267 __u8 index; /* Used to match the uvc_control entry with a
278 struct uvc_format_desc {
284 /* The term 'entity' refers to both UVC units and UVC terminals.
286 * The type field is either the terminal type (wTerminalType in the terminal
287 * descriptor), or the unit type (bDescriptorSubtype in the unit descriptor).
288 * As the bDescriptorSubtype field is one byte long, the type value will
289 * always have a null MSB for units. All terminal types defined by the UVC
290 * specification have a non-null MSB, so it is safe to use the MSB to
291 * differentiate between units and terminals as long as the descriptor parsing
292 * code makes sure terminal types have a non-null MSB.
294 * For terminals, the type's most significant bit stores the terminal
295 * direction (either UVC_TERM_INPUT or UVC_TERM_OUTPUT). The type field should
296 * always be accessed with the UVC_ENTITY_* macros and never directly.
300 struct list_head list; /* Entity as part of a UVC device. */
301 struct list_head chain; /* Entity as part of a video device
307 /* Media controller-related fields. */
308 struct video_device *vdev;
309 struct v4l2_subdev subdev;
310 unsigned int num_pads;
311 unsigned int num_links;
312 struct media_pad *pads;
316 __u16 wObjectiveFocalLengthMin;
317 __u16 wObjectiveFocalLengthMax;
318 __u16 wOcularFocalLength;
326 __u8 bTransportModeSize;
327 __u8 *bmTransportModes;
334 __u16 wMaxMultiplier;
337 __u8 bmVideoStandards;
344 __u8 guidExtensionCode[16];
348 __u8 *bmControlsType;
355 unsigned int ncontrols;
356 struct uvc_control *controls;
366 __u32 dwMaxVideoFrameBufferSize;
367 __u8 bFrameIntervalType;
368 __u32 dwDefaultFrameInterval;
369 __u32 *dwFrameInterval;
382 unsigned int nframes;
383 struct uvc_frame *frame;
386 struct uvc_streaming_header {
388 __u8 bEndpointAddress;
392 /* The following fields are used by input headers only. */
394 __u8 bStillCaptureMethod;
395 __u8 bTriggerSupport;
399 enum uvc_buffer_state {
400 UVC_BUF_STATE_IDLE = 0,
401 UVC_BUF_STATE_QUEUED = 1,
402 UVC_BUF_STATE_ACTIVE = 2,
403 UVC_BUF_STATE_READY = 3,
404 UVC_BUF_STATE_DONE = 4,
405 UVC_BUF_STATE_ERROR = 5,
409 unsigned long vma_use_count;
410 struct list_head stream;
412 /* Touched by interrupt handler. */
413 struct v4l2_buffer buf;
414 struct list_head queue;
415 wait_queue_head_t wait;
416 enum uvc_buffer_state state;
420 #define UVC_QUEUE_STREAMING (1 << 0)
421 #define UVC_QUEUE_DISCONNECTED (1 << 1)
422 #define UVC_QUEUE_DROP_CORRUPTED (1 << 2)
424 struct uvc_video_queue {
425 enum v4l2_buf_type type;
431 unsigned int buf_size;
432 unsigned int buf_used;
433 struct uvc_buffer buffer[UVC_MAX_VIDEO_BUFFERS];
434 struct mutex mutex; /* protects buffers and mainqueue */
435 spinlock_t irqlock; /* protects irqqueue */
437 struct list_head mainqueue;
438 struct list_head irqqueue;
441 struct uvc_video_chain {
442 struct uvc_device *dev;
443 struct list_head list;
445 struct list_head entities; /* All entities */
446 struct uvc_entity *processing; /* Processing unit */
447 struct uvc_entity *selector; /* Selector unit */
449 struct mutex ctrl_mutex; /* Protects ctrl.info */
452 struct uvc_streaming {
453 struct list_head list;
454 struct uvc_device *dev;
455 struct video_device *vdev;
456 struct uvc_video_chain *chain;
459 struct usb_interface *intf;
463 struct uvc_streaming_header header;
464 enum v4l2_buf_type type;
466 unsigned int nformats;
467 struct uvc_format *format;
469 struct uvc_streaming_control ctrl;
470 struct uvc_format *cur_format;
471 struct uvc_frame *cur_frame;
472 /* Protect access to ctrl, cur_format, cur_frame and hardware video
477 unsigned int frozen : 1;
478 struct uvc_video_queue queue;
479 void (*decode) (struct urb *urb, struct uvc_streaming *video,
480 struct uvc_buffer *buf);
482 /* Context data used by the bulk completion handler. */
485 unsigned int header_size;
488 __u32 max_payload_size;
491 struct urb *urb[UVC_URBS];
492 char *urb_buffer[UVC_URBS];
493 dma_addr_t urb_dma[UVC_URBS];
494 unsigned int urb_size;
500 enum uvc_device_state {
501 UVC_DEV_DISCONNECTED = 1,
505 struct usb_device *udev;
506 struct usb_interface *intf;
507 unsigned long warnings;
512 enum uvc_device_state state;
516 /* Video control interface */
517 #ifdef CONFIG_MEDIA_CONTROLLER
518 struct media_device mdev;
520 struct v4l2_device vdev;
522 __u32 clock_frequency;
524 struct list_head entities;
525 struct list_head chains;
527 /* Video Streaming interfaces */
528 struct list_head streams;
531 /* Status Interrupt Endpoint */
532 struct usb_host_endpoint *int_ep;
535 struct input_dev *input;
539 enum uvc_handle_state {
540 UVC_HANDLE_PASSIVE = 0,
541 UVC_HANDLE_ACTIVE = 1,
545 struct uvc_video_chain *chain;
546 struct uvc_streaming *stream;
547 enum uvc_handle_state state;
551 struct usb_driver driver;
554 /* ------------------------------------------------------------------------
555 * Debugging, printing and logging
558 #define UVC_TRACE_PROBE (1 << 0)
559 #define UVC_TRACE_DESCR (1 << 1)
560 #define UVC_TRACE_CONTROL (1 << 2)
561 #define UVC_TRACE_FORMAT (1 << 3)
562 #define UVC_TRACE_CAPTURE (1 << 4)
563 #define UVC_TRACE_CALLS (1 << 5)
564 #define UVC_TRACE_IOCTL (1 << 6)
565 #define UVC_TRACE_FRAME (1 << 7)
566 #define UVC_TRACE_SUSPEND (1 << 8)
567 #define UVC_TRACE_STATUS (1 << 9)
568 #define UVC_TRACE_VIDEO (1 << 10)
570 #define UVC_WARN_MINMAX 0
571 #define UVC_WARN_PROBE_DEF 1
573 extern unsigned int uvc_clock_param;
574 extern unsigned int uvc_no_drop_param;
575 extern unsigned int uvc_trace_param;
576 extern unsigned int uvc_timeout_param;
578 #define uvc_trace(flag, msg...) \
580 if (uvc_trace_param & flag) \
581 printk(KERN_DEBUG "uvcvideo: " msg); \
584 #define uvc_warn_once(dev, warn, msg...) \
586 if (!test_and_set_bit(warn, &dev->warnings)) \
587 printk(KERN_INFO "uvcvideo: " msg); \
590 #define uvc_printk(level, msg...) \
591 printk(level "uvcvideo: " msg)
593 /* --------------------------------------------------------------------------
594 * Internal functions.
598 extern struct uvc_driver uvc_driver;
600 extern struct uvc_entity *uvc_entity_by_id(struct uvc_device *dev, int id);
602 /* Video buffers queue management. */
603 extern void uvc_queue_init(struct uvc_video_queue *queue,
604 enum v4l2_buf_type type, int drop_corrupted);
605 extern int uvc_alloc_buffers(struct uvc_video_queue *queue,
606 unsigned int nbuffers, unsigned int buflength);
607 extern int uvc_free_buffers(struct uvc_video_queue *queue);
608 extern int uvc_query_buffer(struct uvc_video_queue *queue,
609 struct v4l2_buffer *v4l2_buf);
610 extern int uvc_queue_buffer(struct uvc_video_queue *queue,
611 struct v4l2_buffer *v4l2_buf);
612 extern int uvc_dequeue_buffer(struct uvc_video_queue *queue,
613 struct v4l2_buffer *v4l2_buf, int nonblocking);
614 extern int uvc_queue_enable(struct uvc_video_queue *queue, int enable);
615 extern void uvc_queue_cancel(struct uvc_video_queue *queue, int disconnect);
616 extern struct uvc_buffer *uvc_queue_next_buffer(struct uvc_video_queue *queue,
617 struct uvc_buffer *buf);
618 extern int uvc_queue_mmap(struct uvc_video_queue *queue,
619 struct vm_area_struct *vma);
620 extern unsigned int uvc_queue_poll(struct uvc_video_queue *queue,
621 struct file *file, poll_table *wait);
623 extern unsigned long uvc_queue_get_unmapped_area(struct uvc_video_queue *queue,
624 unsigned long pgoff);
626 extern int uvc_queue_allocated(struct uvc_video_queue *queue);
627 static inline int uvc_queue_streaming(struct uvc_video_queue *queue)
629 return queue->flags & UVC_QUEUE_STREAMING;
633 extern const struct v4l2_file_operations uvc_fops;
635 /* Media controller */
636 extern int uvc_mc_register_entities(struct uvc_video_chain *chain);
637 extern void uvc_mc_cleanup_entity(struct uvc_entity *entity);
640 extern int uvc_video_init(struct uvc_streaming *stream);
641 extern int uvc_video_suspend(struct uvc_streaming *stream);
642 extern int uvc_video_resume(struct uvc_streaming *stream);
643 extern int uvc_video_enable(struct uvc_streaming *stream, int enable);
644 extern int uvc_probe_video(struct uvc_streaming *stream,
645 struct uvc_streaming_control *probe);
646 extern int uvc_commit_video(struct uvc_streaming *stream,
647 struct uvc_streaming_control *ctrl);
648 extern int uvc_query_ctrl(struct uvc_device *dev, __u8 query, __u8 unit,
649 __u8 intfnum, __u8 cs, void *data, __u16 size);
652 extern int uvc_status_init(struct uvc_device *dev);
653 extern void uvc_status_cleanup(struct uvc_device *dev);
654 extern int uvc_status_start(struct uvc_device *dev);
655 extern void uvc_status_stop(struct uvc_device *dev);
656 extern int uvc_status_suspend(struct uvc_device *dev);
657 extern int uvc_status_resume(struct uvc_device *dev);
660 extern int uvc_query_v4l2_ctrl(struct uvc_video_chain *chain,
661 struct v4l2_queryctrl *v4l2_ctrl);
662 extern int uvc_query_v4l2_menu(struct uvc_video_chain *chain,
663 struct v4l2_querymenu *query_menu);
665 extern int uvc_ctrl_add_mapping(struct uvc_video_chain *chain,
666 const struct uvc_control_mapping *mapping);
667 extern int uvc_ctrl_init_device(struct uvc_device *dev);
668 extern void uvc_ctrl_cleanup_device(struct uvc_device *dev);
669 extern int uvc_ctrl_resume_device(struct uvc_device *dev);
671 extern int uvc_ctrl_begin(struct uvc_video_chain *chain);
672 extern int __uvc_ctrl_commit(struct uvc_video_chain *chain, int rollback);
673 static inline int uvc_ctrl_commit(struct uvc_video_chain *chain)
675 return __uvc_ctrl_commit(chain, 0);
677 static inline int uvc_ctrl_rollback(struct uvc_video_chain *chain)
679 return __uvc_ctrl_commit(chain, 1);
682 extern int uvc_ctrl_get(struct uvc_video_chain *chain,
683 struct v4l2_ext_control *xctrl);
684 extern int uvc_ctrl_set(struct uvc_video_chain *chain,
685 struct v4l2_ext_control *xctrl);
687 extern int uvc_xu_ctrl_query(struct uvc_video_chain *chain,
688 struct uvc_xu_control_query *xqry);
690 /* Utility functions */
691 extern void uvc_simplify_fraction(uint32_t *numerator, uint32_t *denominator,
692 unsigned int n_terms, unsigned int threshold);
693 extern uint32_t uvc_fraction_to_interval(uint32_t numerator,
694 uint32_t denominator);
695 extern struct usb_host_endpoint *uvc_find_endpoint(
696 struct usb_host_interface *alts, __u8 epaddr);
699 void uvc_video_decode_isight(struct urb *urb, struct uvc_streaming *stream,
700 struct uvc_buffer *buf);
702 #endif /* __KERNEL__ */