// SPDX-License-Identifier: GPL-2.0-or-later /* * uvc_video.c -- USB Video Class driver - Video handling * * Copyright (C) 2005-2010 * Laurent Pinchart ([email protected]) */ #include <linux/dma-mapping.h> #include <linux/highmem.h> #include <linux/kernel.h> #include <linux/list.h> #include <linux/module.h> #include <linux/slab.h> #include <linux/usb.h> #include <linux/usb/hcd.h> #include <linux/videodev2.h> #include <linux/vmalloc.h> #include <linux/wait.h> #include <linux/atomic.h> #include <asm/unaligned.h> #include <media/v4l2-common.h> #include "uvcvideo.h" /* ------------------------------------------------------------------------ * UVC Controls */ static int __uvc_query_ctrl(struct uvc_device *dev, u8 query, u8 unit, u8 intfnum, u8 cs, void *data, u16 size, int timeout) { … } static const char *uvc_query_name(u8 query) { … } int uvc_query_ctrl(struct uvc_device *dev, u8 query, u8 unit, u8 intfnum, u8 cs, void *data, u16 size) { … } static const struct usb_device_id elgato_cam_link_4k = …; static void uvc_fixup_video_ctrl(struct uvc_streaming *stream, struct uvc_streaming_control *ctrl) { … } static size_t uvc_video_ctrl_size(struct uvc_streaming *stream) { … } static int uvc_get_video_ctrl(struct uvc_streaming *stream, struct uvc_streaming_control *ctrl, int probe, u8 query) { … } static int uvc_set_video_ctrl(struct uvc_streaming *stream, struct uvc_streaming_control *ctrl, int probe) { … } int uvc_probe_video(struct uvc_streaming *stream, struct uvc_streaming_control *probe) { … } static int uvc_commit_video(struct uvc_streaming *stream, struct uvc_streaming_control *probe) { … } /* ----------------------------------------------------------------------------- * Clocks and timestamps */ static inline ktime_t uvc_video_get_time(void) { … } static void uvc_video_clock_add_sample(struct uvc_clock *clock, const struct uvc_clock_sample *sample) { … } static void uvc_video_clock_decode(struct uvc_streaming *stream, struct uvc_buffer *buf, const u8 *data, int len) { … } static void uvc_video_clock_reset(struct uvc_clock *clock) { … } static int uvc_video_clock_init(struct uvc_clock *clock) { … } static void uvc_video_clock_cleanup(struct uvc_clock *clock) { … } /* * uvc_video_clock_host_sof - Return the host SOF value for a clock sample * * Host SOF counters reported by usb_get_current_frame_number() usually don't * cover the whole 11-bits SOF range (0-2047) but are limited to the HCI frame * schedule window. They can be limited to 8, 9 or 10 bits depending on the host * controller and its configuration. * * We thus need to recover the SOF value corresponding to the host frame number. * As the device and host frame numbers are sampled in a short interval, the * difference between their values should be equal to a small delta plus an * integer multiple of 256 caused by the host frame number limited precision. * * To obtain the recovered host SOF value, compute the small delta by masking * the high bits of the host frame counter and device SOF difference and add it * to the device SOF value. */ static u16 uvc_video_clock_host_sof(const struct uvc_clock_sample *sample) { … } /* * uvc_video_clock_update - Update the buffer timestamp * * This function converts the buffer PTS timestamp to the host clock domain by * going through the USB SOF clock domain and stores the result in the V4L2 * buffer timestamp field. * * The relationship between the device clock and the host clock isn't known. * However, the device and the host share the common USB SOF clock which can be * used to recover that relationship. * * The relationship between the device clock and the USB SOF clock is considered * to be linear over the clock samples sliding window and is given by * * SOF = m * PTS + p * * Several methods to compute the slope (m) and intercept (p) can be used. As * the clock drift should be small compared to the sliding window size, we * assume that the line that goes through the points at both ends of the window * is a good approximation. Naming those points P1 and P2, we get * * SOF = (SOF2 - SOF1) / (STC2 - STC1) * PTS * + (SOF1 * STC2 - SOF2 * STC1) / (STC2 - STC1) * * or * * SOF = ((SOF2 - SOF1) * PTS + SOF1 * STC2 - SOF2 * STC1) / (STC2 - STC1) (1) * * to avoid losing precision in the division. Similarly, the host timestamp is * computed with * * TS = ((TS2 - TS1) * SOF + TS1 * SOF2 - TS2 * SOF1) / (SOF2 - SOF1) (2) * * SOF values are coded on 11 bits by USB. We extend their precision with 16 * decimal bits, leading to a 11.16 coding. * * TODO: To avoid surprises with device clock values, PTS/STC timestamps should * be normalized using the nominal device clock frequency reported through the * UVC descriptors. * * Both the PTS/STC and SOF counters roll over, after a fixed but device * specific amount of time for PTS/STC and after 2048ms for SOF. As long as the * sliding window size is smaller than the rollover period, differences computed * on unsigned integers will produce the correct result. However, the p term in * the linear relations will be miscomputed. * * To fix the issue, we subtract a constant from the PTS and STC values to bring * PTS to half the 32 bit STC range. The sliding window STC values then fit into * the 32 bit range without any rollover. * * Similarly, we add 2048 to the device SOF values to make sure that the SOF * computed by (1) will never be smaller than 0. This offset is then compensated * by adding 2048 to the SOF values used in (2). However, this doesn't prevent * rollovers between (1) and (2): the SOF value computed by (1) can be slightly * lower than 4096, and the host SOF counters can have rolled over to 2048. This * case is handled by subtracting 2048 from the SOF value if it exceeds the host * SOF value at the end of the sliding window. * * Finally we subtract a constant from the host timestamps to bring the first * timestamp of the sliding window to 1s. */ void uvc_video_clock_update(struct uvc_streaming *stream, struct vb2_v4l2_buffer *vbuf, struct uvc_buffer *buf) { … } /* ------------------------------------------------------------------------ * Stream statistics */ static void uvc_video_stats_decode(struct uvc_streaming *stream, const u8 *data, int len) { … } static void uvc_video_stats_update(struct uvc_streaming *stream) { … } size_t uvc_video_stats_dump(struct uvc_streaming *stream, char *buf, size_t size) { … } static void uvc_video_stats_start(struct uvc_streaming *stream) { … } static void uvc_video_stats_stop(struct uvc_streaming *stream) { … } /* ------------------------------------------------------------------------ * Video codecs */ /* * Video payload decoding is handled by uvc_video_decode_start(), * uvc_video_decode_data() and uvc_video_decode_end(). * * uvc_video_decode_start is called with URB data at the start of a bulk or * isochronous payload. It processes header data and returns the header size * in bytes if successful. If an error occurs, it returns a negative error * code. The following error codes have special meanings. * * - EAGAIN informs the caller that the current video buffer should be marked * as done, and that the function should be called again with the same data * and a new video buffer. This is used when end of frame conditions can be * reliably detected at the beginning of the next frame only. * * If an error other than -EAGAIN is returned, the caller will drop the current * payload. No call to uvc_video_decode_data and uvc_video_decode_end will be * made until the next payload. -ENODATA can be used to drop the current * payload if no other error code is appropriate. * * uvc_video_decode_data is called for every URB with URB data. It copies the * data to the video buffer. * * uvc_video_decode_end is called with header data at the end of a bulk or * isochronous payload. It performs any additional header data processing and * returns 0 or a negative error code if an error occurred. As header data have * already been processed by uvc_video_decode_start, this functions isn't * required to perform sanity checks a second time. * * For isochronous transfers where a payload is always transferred in a single * URB, the three functions will be called in a row. * * To let the decoder process header data and update its internal state even * when no video buffer is available, uvc_video_decode_start must be prepared * to be called with a NULL buf parameter. uvc_video_decode_data and * uvc_video_decode_end will never be called with a NULL buffer. */ static int uvc_video_decode_start(struct uvc_streaming *stream, struct uvc_buffer *buf, const u8 *data, int len) { … } static inline enum dma_data_direction uvc_stream_dir( struct uvc_streaming *stream) { … } static inline struct device *uvc_stream_to_dmadev(struct uvc_streaming *stream) { … } static int uvc_submit_urb(struct uvc_urb *uvc_urb, gfp_t mem_flags) { … } /* * uvc_video_decode_data_work: Asynchronous memcpy processing * * Copy URB data to video buffers in process context, releasing buffer * references and requeuing the URB when done. */ static void uvc_video_copy_data_work(struct work_struct *work) { … } static void uvc_video_decode_data(struct uvc_urb *uvc_urb, struct uvc_buffer *buf, const u8 *data, int len) { … } static void uvc_video_decode_end(struct uvc_streaming *stream, struct uvc_buffer *buf, const u8 *data, int len) { … } /* * Video payload encoding is handled by uvc_video_encode_header() and * uvc_video_encode_data(). Only bulk transfers are currently supported. * * uvc_video_encode_header is called at the start of a payload. It adds header * data to the transfer buffer and returns the header size. As the only known * UVC output device transfers a whole frame in a single payload, the EOF bit * is always set in the header. * * uvc_video_encode_data is called for every URB and copies the data from the * video buffer to the transfer buffer. */ static int uvc_video_encode_header(struct uvc_streaming *stream, struct uvc_buffer *buf, u8 *data, int len) { … } static int uvc_video_encode_data(struct uvc_streaming *stream, struct uvc_buffer *buf, u8 *data, int len) { … } /* ------------------------------------------------------------------------ * Metadata */ /* * Additionally to the payload headers we also want to provide the user with USB * Frame Numbers and system time values. The resulting buffer is thus composed * of blocks, containing a 64-bit timestamp in nanoseconds, a 16-bit USB Frame * Number, and a copy of the payload header. * * Ideally we want to capture all payload headers for each frame. However, their * number is unknown and unbound. We thus drop headers that contain no vendor * data and that either contain no SCR value or an SCR value identical to the * previous header. */ static void uvc_video_decode_meta(struct uvc_streaming *stream, struct uvc_buffer *meta_buf, const u8 *mem, unsigned int length) { … } /* ------------------------------------------------------------------------ * URB handling */ /* * Set error flag for incomplete buffer. */ static void uvc_video_validate_buffer(const struct uvc_streaming *stream, struct uvc_buffer *buf) { … } /* * Completion handler for video URBs. */ static void uvc_video_next_buffers(struct uvc_streaming *stream, struct uvc_buffer **video_buf, struct uvc_buffer **meta_buf) { … } static void uvc_video_decode_isoc(struct uvc_urb *uvc_urb, struct uvc_buffer *buf, struct uvc_buffer *meta_buf) { … } static void uvc_video_decode_bulk(struct uvc_urb *uvc_urb, struct uvc_buffer *buf, struct uvc_buffer *meta_buf) { … } static void uvc_video_encode_bulk(struct uvc_urb *uvc_urb, struct uvc_buffer *buf, struct uvc_buffer *meta_buf) { … } static void uvc_video_complete(struct urb *urb) { … } /* * Free transfer buffers. */ static void uvc_free_urb_buffers(struct uvc_streaming *stream) { … } static bool uvc_alloc_urb_buffer(struct uvc_streaming *stream, struct uvc_urb *uvc_urb, gfp_t gfp_flags) { … } /* * Allocate transfer buffers. This function can be called with buffers * already allocated when resuming from suspend, in which case it will * return without touching the buffers. * * Limit the buffer size to UVC_MAX_PACKETS bulk/isochronous packets. If the * system is too low on memory try successively smaller numbers of packets * until allocation succeeds. * * Return the number of allocated packets on success or 0 when out of memory. */ static int uvc_alloc_urb_buffers(struct uvc_streaming *stream, unsigned int size, unsigned int psize, gfp_t gfp_flags) { … } /* * Uninitialize isochronous/bulk URBs and free transfer buffers. */ static void uvc_video_stop_transfer(struct uvc_streaming *stream, int free_buffers) { … } /* * Compute the maximum number of bytes per interval for an endpoint. */ u16 uvc_endpoint_max_bpi(struct usb_device *dev, struct usb_host_endpoint *ep) { … } /* * Initialize isochronous URBs and allocate transfer buffers. The packet size * is given by the endpoint. */ static int uvc_init_video_isoc(struct uvc_streaming *stream, struct usb_host_endpoint *ep, gfp_t gfp_flags) { … } /* * Initialize bulk URBs and allocate transfer buffers. The packet size is * given by the endpoint. */ static int uvc_init_video_bulk(struct uvc_streaming *stream, struct usb_host_endpoint *ep, gfp_t gfp_flags) { … } /* * Initialize isochronous/bulk URBs and allocate transfer buffers. */ static int uvc_video_start_transfer(struct uvc_streaming *stream, gfp_t gfp_flags) { … } /* -------------------------------------------------------------------------- * Suspend/resume */ /* * Stop streaming without disabling the video queue. * * To let userspace applications resume without trouble, we must not touch the * video buffers in any way. We mark the device as frozen to make sure the URB * completion handler won't try to cancel the queue when we kill the URBs. */ int uvc_video_suspend(struct uvc_streaming *stream) { … } /* * Reconfigure the video interface and restart streaming if it was enabled * before suspend. * * If an error occurs, disable the video queue. This will wake all pending * buffers, making sure userspace applications are notified of the problem * instead of waiting forever. */ int uvc_video_resume(struct uvc_streaming *stream, int reset) { … } /* ------------------------------------------------------------------------ * Video device */ /* * Initialize the UVC video device by switching to alternate setting 0 and * retrieve the default format. * * Some cameras (namely the Fuji Finepix) set the format and frame * indexes to zero. The UVC standard doesn't clearly make this a spec * violation, so try to silently fix the values if possible. * * This function is called before registering the device with V4L. */ int uvc_video_init(struct uvc_streaming *stream) { … } int uvc_video_start_streaming(struct uvc_streaming *stream) { … } void uvc_video_stop_streaming(struct uvc_streaming *stream) { … }
Codebase Browser
linux