UVC gadget test application Readme

Copyright (C) 2010 Ideas on board SPRL
Copyright (C) 2013 ST Microelectronics Ltd.

Contacts:
Laurent Pinchart <laurent.pinchart@xxxxxxxxxxxxxxxx>
Bhupesh Sharma <bhupesh.sharma@xxxxxx>

Introduction
============

This README file documents the UVC gadget test application available
here git://git.ideasonboard.org/uvc-gadget.git, which can be used to
test the UVC webcam gadget driver located under drivers/usb/gadget
directory.

Possible Use-Case scenarios
===========================

There can be a number of scenarios under which the UVC webcam gadget can
be used and each use-case can vary in the following ways:

- Video streaming endpoint choice:
  --------------------------------

  As per UVC specifications (Revision 1.1), either Bulk or Isochronous
  USB endpoints can be used are for implementing UVC Video streaming
  interface. Both have there unique challenges as:

	Isochronous video streaming interface will have two
	alt-settings:
		- Alt-setting 0 for zero-bandwidth mode, and
		- Alt-setting 1 for full-bandwidth mode.

	This requires us to ACK status stage of SET_ALT(alt-setting =
	1), only when we have video frames available which can be queued
	to UVC domain.

	Bulk video streaming interface, on the other hand will have only
	one alt-setting.

	This requires us to prepare UVC gadget for streaming when we
	receive a a UVC_VS_COMMIT_CONTROL command from USB host and
	actually start streaming as soon as we have video frames
	available which can be queued to UVC domain.

- Availability of a video capture device:
  ---------------------------------------

  To emulate a real UVC webcam gadget (capturing live video from a video
  capture source and sending it over USB bus), it is possible to
  integrate a V4L2 based video-capture device driver with the UVC gadget
  test application acting as an interface between the UVC based
  video-output device and V4L2 based video-capture device.
  
  Accordingly, there can be the following scenarios possible:

	- No video capture device available:

		In this case, there is no video capture device available
		and the UVC webcam gadget is working in an standalone
		environment.

		It is possible in this case to stream a dummy test
		pattern from the UVC webcam gadget and view the same on
		the Linux/Windows USB Host machine using standard video
		capture utilities like CHEESE.

	- VIVI (Virtual Video driver) acting as a video capture source:

		In case we don't have a real video capture hardware
		(e.g. sensor) available, it is still possible to
		exercise the complete path from the V4L2 based
		video-capture domain to UVC based video-output domain,
		using the Virtual Video driver (VIVI) available here:
		drivers/media/platform/vivi.c

		It is possible in this case to stream changing vertical
		color bar pattern pattern from the VIVI capture device
		and send it to UVC webcam gadget, which will eventually
		send these frames over USB bus.

		Similar to the case above, it is possible to view the
		frames on the Linux/Windows USB Host machine using
		standard video capture utilities like CHEESE.

	- Real video capture hardware and corresponding V4L2 driver
	  available:

		In this case, we have a real video capture hardware
		(e.g. CCD / CMOS sensor) available.

		Here, it is possible to exercise the complete path from
		the V4L2 based video-capture driver domain to UVC based
		video-output domain, using the UVC gadget test
		application.

		It is possible in this case to stream real video/still
		images from capture source and send it to UVC webcam
		gadget, which will eventually send these frames over USB
		bus.

- IO methods supported:
  --------------------

  V4L2 framework supports a number of IO methods and to achieve
  zero-memcpy of video frames as they pass from V4L2 video-capture
  domain to UVC video-output domain, it is important to select
  appropriate IO methods for working on videobuffers.

  Accordingly we can have the following scenarios possible:
  
	- UVC webcam standalone, supporting IO_METHOD_MMAP method:

		In this case, there is no video capture device available
		and the UVC webcam gadget is working in an standalone
		environment.

		It is supporting IO_MMAP method, which implies that the
		videobuffers are allocated by the UVC webcam gadget
		itself and they are filled with dummy test pattern by
		UVC gadget test application.

	- UVC webcam standalone, supporting IO_METHOD_USERPTR method:

		In this case, there is no video capture device available
		and the UVC webcam gadget is working in an standalone
		environment.

		It is supporting IO_METHOD_USERPTR method, which implies
		that the videobuffers are allocated and filled with
		dummy test pattern by the UVC gadget test application
		and UVC webcam gadget operates on a USERPTR of these
		videobuffers.

	- UVC webcam integrated with V4L2 video-capture driver, with
	  V4L2 video-capture driver supporting IO_METHOD_MMAP method and
	  UVC webcam supporting IO_METHOD_USERPTR:

		In this case, either VIVI or another V4L2 based driver
		(working on real HW) is available as a video capture
		device and is integrated with the UVC webcam gadget via
		UVC gadget test application, with V4L2 video-capture
		driver supporting IO_METHOD_MMAP method and UVC webcam
		supporting IO_METHOD_USERPTR.

		Here, the videobuffers are allocated in the V4L2
		video-capture domain and UVC gadget test application
		acts as a means to pass a USERPTR of these videobuffers
		to the UVC webcam gadget domain, without requiring any
		memcpy from the CPU.

	- UVC webcam integrated with V4L2 video-capture driver, with
	  V4L2 video-capture driver supporting IO_METHOD_USERPTR method
	  and UVC webcam supporting IO_METHOD_MMAP:

		In this case, either VIVI or another V4L2 based driver
		(working on real HW) is available as a video capture
		device and is integrated with the UVC webcam gadget via
		UVC gadget test application, with V4L2 video-capture
		driver supporting IO_METHOD_USERPTR method and UVC
		webcam supporting IO_METHOD_MMAP.

		Here, the videobuffers are allocated in the UVC webcam
		gadget domain and UVC gadget test application acts as a
		means to pass a USERPTR of these videobuffers to the
		V4L2 video-capture domain, without requiring any memcpy
		from the CPU.

Modifying UVC gadget test application
=====================================

The UVC webcam gadget kernel driver located under drivers/usb/gadget
directory and compilable as g_webcam.ko kernel module, supports 360p and
720p frame resolutions and YUV4:2:2 and MJPEG frame formats by default.

So, the video capture device must be aligned to support similar frame
format and resolutions.

In case the video capture device supports other resolutions and frame
formats, we need to replace the default values used in the UVC gadget
test application with the same and also update the UVC webcam gadget
kernel driver.

Keeping USBCV's UVC test-suite happy
====================================

The UVC webcam gadget kernel driver located under drivers/usb/gadget
directory and compilable as g_webcam.ko kernel module, supports changing
the Brightness attribute of the Processing Unit (PU) by default.

If the underlying video capture device supports changing the Brightness
attribute of the image being acquired (like the Virtual Video, VIVI
driver does), then we should route this UVC request to the respective
video capture device.

Incase, there is no actual video capture device associated with the UVC
gadget and we wish to use this application as the final destination of
the UVC specific requests then we should return pre-cooked (static)
responses to GET_CUR(BRIGHTNESS) and SET_CUR(BRIGHTNESS) commands to
keep command verifier test tools like UVC class specific test suite of
USBCV, happy.

Note that the values used in UVC gadget test application are in sync
with the VIVI driver and must be changed for your specific video capture
device. These values also work well in case there in no actual video
capture device.