USB Video Class (UVC) Host Driver
Overview
The UVC host driver (drivers/usbhost/usbhost_uvc.c) enumerates USB
Video Class 1.1/1.5 cameras attached to an isochronous capable host
controller and exposes each camera through the NuttX camera upper half as
/dev/videoN. A camera can then be used with any application that
speaks the V4L2 capture API, apps/examples/camera for instance.
The driver parses the VideoControl and VideoStreaming descriptor sets of the camera, answers the class-specific control requests (including PROBE/COMMIT negotiation) and streams frames from the isochronous IN endpoint that the negotiated alternate setting provides.
Features
UVC 1.1/1.5 cameras, both composite (IAD) and single function devices
MJPEG and frame-based (H.264/HEVC) payloads
Uncompressed payloads: YUYV, UYVY, NV12, YVU420, YUV420, M420, GREY, RGB565 and BGR24, matched by the format GUID
Format, frame size and frame interval enumeration
Alternate setting selection driven by the bandwidth the frame size needs
A pipeline of isochronous transfers, sized in packets, so a frame may span several transfers without losing microframe data
Stream restart on transport errors and safe teardown while transfers are still pending
Configuration
The driver is enabled through the following Kconfig options:
CONFIG_VIDEO_STREAM=y # Required: camera upper half
CONFIG_USBHOST_HAVE_ASYNCH=y # Required: provided by the host controller
CONFIG_SCHED_HPWORK=y # Required: disconnect handling
CONFIG_USBHOST_COMPOSITE=y # Recommended: UVC cameras are usually composite
CONFIG_USBHOST_UVC=y # Enable the driver
CONFIG_USBHOST_UVC_ISO_PIPELINE_DEPTH=2
CONFIG_USBHOST_UVC_PACKETS_PER_SLOT=32
CONFIG_USBHOST_UVC_THREAD_PRIORITY=100
CONFIG_USBHOST_UVC_THREAD_STACKSIZE=4096
CONFIG_USBHOST_UVC_ISO_PIPELINE_DEPTH is the number of isochronous
transfers kept in flight; CONFIG_USBHOST_UVC_PACKETS_PER_SLOT is how
many packets each of them carries. A slot is not a frame: frame
boundaries come from the UVC payload header, so a large frame spans as
many slots as it needs. Each slot costs
PACKETS_PER_SLOT * wMaxPacketSize (per slot, from the controller)
ISO_PIPELINE_DEPTH * the above (total)
Every slot holds exactly PACKETS_PER_SLOT packets, which is the number
of packet lengths the host controller reports when the transfer completes.
A controller that delivers fewer packets simply leaves the tail of the
array at zero, and a zero length carries no data.
The driver submits each slot with DRVR_ISOCASYNCH(), which reports the
length of every isochronous packet instead of a single byte count: the
packet boundaries are what delimits the frames, since a packet may be short
or empty and each one begins with its own payload header. Only host
controllers that implement that method can carry this class, which is why
CONFIG_USBHOST_UVC currently depends on SIM_USB_HOST.
Device Nodes
Every enumerated camera registers itself as /dev/video0,
/dev/video1 and so on, up to UVC_MAX_DEVICES cameras. The node
implements the V4L2 capture ioctls through the camera upper half:
VIDIOC_QUERYCAP,VIDIOC_ENUM_FMT,VIDIOC_S_FMT/G_FMTVIDIOC_ENUM_FRAMESIZES,VIDIOC_ENUM_FRAMEINTERVALSVIDIOC_REQBUFS,VIDIOC_QBUF,VIDIOC_DQBUF,VIDIOC_STREAMON/VIDIOC_STREAMOFFVIDIOC_QUERYCTRL,VIDIOC_G_CTRL,VIDIOC_S_CTRL
Streaming Model
For a given frame size the driver picks the alternate setting whose
wMaxPacketSize covers the bandwidth the format needs, or falls back
to the largest one available. It then programs the camera through
VS_PROBE_CONTROL / VS_COMMIT_CONTROL and starts the isochronous
pipeline.
Payload headers are parsed as the transfers complete: the frame
identifier tells the driver when a new frame starts, and the end of
frame bit terminates it. Completed frames are handed to the upper half
through the imgdata capture callback, which copies them into the
buffer the application queued.
Testing on the Simulator
The driver can be exercised on the simulator with a real camera passed through to the host by libusb:
CONFIG_SIM_USB_HOST=y
CONFIG_SIM_LIBUSB=y
CONFIG_SIM_USB_VID=0xXXXX # Camera vendor ID
CONFIG_SIM_USB_PID=0xXXXX # Camera product ID
CONFIG_VIDEO_STREAM=y
CONFIG_USBHOST_UVC=y
Enable the camera example in apps, boot the simulator and capture:
nsh> camera
The host must allow the simulator process to claim the camera interface,
which usually means the process runs as root or a udev rule grants
access to the device.
Limitations
One streaming interface per camera; a camera that exposes several video streaming interfaces registers only the first one.
Isochronous transfers only. Cameras that use bulk endpoints for video data are not supported.
High bandwidth alternate settings (multiple transactions per microframe) depend on the host controller programming
Max Burst Sizecorrectly; a controller that hard codes a burst size of zero will run the camera at a fraction of the negotiated bandwidth.Uncompressed payloads are passed through as-is; no colour space conversion is performed by the driver.