How to use the UVC gadget driver in Linux

UVC Gadget

UVC or USB Video Class is a USB specification created by the USB Implementers Forum (USB-IF) and it is intended to standardize the video streaming functionality on the USB, that is, if you want to create a USB embedded device capable of sending video over the USB port and compatible with most operating systems and applications, then you need to implement the UVC specification.

Linux-based operating systems as well as other, have support for UVC based devices such as webcams, acting as a host for the device. In the case of the device side, also known as the gadget, the driver support is usually proprietary depending on the manufacturer. The Linux kernel has added an implementation of a UVC gadget driver to its mainline in order to help developers to create Linux based devices with UVC support. Beside those efforts, the current UVC driver does not implement all the UVC specification and it is quite hard to configure and use, depending heavily on a userspace application in order to complete the enumeration process and start the video streaming.

This wiki page shows you how to configure and use the linux UVC gadget driver. The user has 2 ways of configuring a UVC gadget: using the g_webcam kernel module and through configfs. Following you will find the the instructions for both methods.

Using kernel g_webcam module

The Webcam Gadget acts as a composite USB Audio and Video Class device. It provides a userspace API to process UVC control requests and stream video data to the host. In order to enable the module, make sure the CONFIG_USB_G_WEBCAM module is selected in kernel configuration:

Symbol: USB_G_WEBCAM [=m]
Type  : tristate
Prompt: USB Webcam Gadget
  Location:
    -> Device Drivers
      -> USB support (USB_SUPPORT [=y])
        -> USB Gadget Support (USB_GADGET [=m])
          -> USB Gadget precomposed configurations (<choice> [=m])
  Defined at drivers/usb/gadget/legacy/Kconfig:480
  Depends on: <choice> && VIDEO_DEV [=m]
  Selects: USB_LIBCOMPOSITE [=m] && VIDEOBUF2_VMALLOC [=n] && \
USB_F_UVC [=n]

After the module has been enabled and built, in order to use it you have to load it as follows:

modprobe g_webcam

After this, a new /dev/videoXdevice will be created that will be used by the user space application.

Using configfs

Configfs allows Userspace-driven kernel object configuration. Configfs is a ram-based filesystem that provides the converse of sysfs's functionality. Where sysfs is a filesystem-based view of kernel objects, configfs is a filesystem-based manager of kernel objects, or config_items.

A configfs config_item is created via an explicit userspace operation: mkdir. It is destroyed via rmdir. The attributes appear at mkdir time, and can be read or modified via read and write. Unlike sysfs, the lifetime of the representation is completely driven by userspace. The kernel modules backing the items must respond to this.

Enabling configfs

First you have to make sure that configfs is enabled:

Symbol: USB_CONFIGFS [=m]
Type  : tristate
Prompt: USB Gadget functions configurable through configfs
  Location:
    -> Device Drivers
      -> USB support (USB_SUPPORT [=y])
        -> USB Gadget Support (USB_GADGET [=m])
  Defined at drivers/usb/gadget/Kconfig:220
  Depends on: USB_SUPPORT [=y] && USB_GADGET [=m]
  Selects: USB_LIBCOMPOSITE [=m]

Then, make sure the UVC function is also selected:

Symbol: USB_CONFIGFS_F_UVC [=y]
Type  : boolean
Prompt: USB Webcam function
  Location:
    -> Device Drivers
      -> USB support (USB_SUPPORT [=y])
        -> USB Gadget Support (USB_GADGET [=m])
          -> USB Gadget functions configurable through configfs (USB_CONFIGFS [=m])
  Defined at drivers/usb/gadget/Kconfig:445
  Depends on: USB_SUPPORT [=y] && USB_GADGET [=m] && \
USB_CONFIGFS [=m] && VIDEO_V4L2 [=m] && VIDEO_DEV [=m]

You can take a look here for instructions on how to verify and mount configs.

Configuring UVC function

First, make sure the libcomposite module is loaded:

modprobe libcomposite