r5u870v2/readme/README

Ricoh R5U870 Linux Driver
Version 2, 2021/05/02

Requirements
============

To build/install this driver, you must have a set of configuration and
interface headers, or the complete build directory, for your running kernel,
or the target kernel for which the driver is to be built.  This should
include most files in the include/linux directory, and specifically
include/linux/autoconf.h and include/linux/version.h.

The required interface headers are usually located at or symlinked from:
/lib/modules/<version>/build

Your kernel must be 4.9 or newer.


Supported Hardware
==================

This driver supports the following OEM webcams:

05ca:1810 HP Pavilion Webcam - UVC
05ca:1812 HP Pavilion Webcam (UVC - NO FW)
05ca:1830 Sony Visual Communication Camera VGP-VCC2 (for VAIO SZ)
05ca:1832 Sony Visual Communication Camera VGP-VCC3 (for VAIO UX)
05ca:1833 Sony Visual Communication Camera VGP-VCC2 (for VAIO AR1)
05ca:1834 Sony Visual Communication Camera VGP-VCC2 (for VAIO AR2)
05ca:1835 Sony Visual Communication Camera VGP-VCC5 (for VAIO SZ)
05ca:1836 Sony Visual Communication Camera VGP-VCC4 (for VAIO FE)
05ca:1837 Sony Visual Communication Camera VGP-VCC4 (for VAIO FZ)
05ca:1839 Sony Visual Communication Camera VGP-VCC6 (for VAIO CR)
05ca:183a Sony Visual Communication Camera VGP-VCC7 (for VAIO SZ)
05ca:183b Sony Visual Communication Camera VGP-VCC8 (for VAIO FZ)
05ca:183e Sony VGP-VCC9
05ca:1841 Fujitsu F01
05ca:1870 HP Pavilion Webcam / HP Webcam 1000


Installation Process
====================

To attempt to build against the running kernel:

make

To build against a specific kernel:

make KDIR=/path/to/kernel

To install the modules to the appropriate location:

make install

-or-

make install KDIR=/path/to/kernel

Please note that these commands do not install firmware. You can manually
copy the desired .fw file to /lib/firmware/ or run:

make firmware_install

to install all firmware files. Installed modules will be automatically 
probed for supported devices by the udev coldplug component at boot, 
and the driver should be automatically loaded on subsequent reboots.

NOTE: Previous releases of this driver have produced modules named
ry5u870.ko and r5u870.ko.  With the current release, the module name was 
changed to r5u870v2.ko.  Ensure that any old versions are deleted after
installing a new version.


Loading the Driver
==================

If you installed the driver, you can just run:

modprobe r5u870v2

You must also copy the microcode files (r5u870_*.fw) to /lib/firmware.


Driver Options
==============

Below is a list of module parameters that may be used with the r5u870 module:

dv1000 -- HP Webcam handling mode
	HP has done it again and used ID 05ca:1870 for two distinct pieces
	of hardware: the HP Webcam 1000, found in HP Pavilion dv1000 series
	machines, and the HP Pavilion Webcam, found in other HP Pavilion
	machines that don't have Microdia cameras, and don't have the 
	05ca:1810 Ricoh UVC camera -- which is not actually any different 
	from the 05ca:1870 HP Pavilion webcam.  These two devices have
	different image sensors and require different microcode.
	0: Assume HP Pavilion Webcam
	1: Assume HP Webcam 1000
	2: Check DMI product name field (DEFAULT)


Changes from r5u870
======================================

 * Total driver rework and update for work with modern kernels 4.9+
 * Two modules [usbcam] and [r5u870] have been combined into one [r5u870v2]
 * videobuf has been replaced with videobuf2
 * cam controls have been reworked and get more integration with v4l2
 * custom workqueue has been replaced with kernel implementation
 * urbstream get rework
 * some callbacks has been replaced with default helpers
 * many variables got friendly names

Bugs
====

Remember to submit in your bug report:
  * Kernel version (uname -a)
  * Distribution name & version
  * lsusb output
  * lsmod output
  * dmesg output after loading r5u870v2
  * if you're getting distorted images, a sample of the camera output

Also remember to check if your bug has already been fixed!

Copyright and License
=====================

r5u870
	Copyright (c) 2007-2008 Sam Revitch <samr7@cs.washington.edu>,
	Alexander Hixon <hixon.alexander@mediati.org>

r5u870v2
	64coreCPU 2021 <r5u870v2@gmail.com>

This driver is licensed to you under the terms of the GNU GPL v2.  See
the included file 'COPYING'.

The Makefile and Kbuild components are derived from the ivtv project.

The files:
	r5u870_1810.fw
	r5u870_1812.fw
	r5u870_1830.fw
	r5u870_1832.fw
	r5u870_1833.fw
	r5u870_1834.fw
	r5u870_1835.fw
	r5u870_1836.fw
	r5u870_1839.fw
	r5u870_183a.fw
	r5u870_183b.fw
	r5u870_1841.fw
	r5u870_1870.fw
	r5u870_1870_1.fw

were derived from usbsnoop/sniffusb tracing of various Windows drivers, 
including some named Mvc25u870.sys, 5U870CAP.sys, and R5U870FLx86.sys.


Acknowledgements (r5u870)
================++++++++++

Huge kudos to Sam Revitch for writing the driver. Cheers, mate. I owe you a
beer (or two). :)

Thanks to Albert Vilella for establishing an interest group for this type of
webcam, for early VAIO SZ testing, and generally collecting a good set of
resources for Linux on VAIO SZ laptops.

Thanks to Geert Willems for extensive testing of HP Webcam support, general
driver compatibility testing, and putting up with endless crazy requests for
more debug information. :-)

Thanks to Mattia Dongili for taking usbsnoop traces of the VAIO UX50 webcam
driver on Windows, and testing initial support in the Linux driver.

Thanks to Beno�t Canet for updating this driver to work with the Sony VAIO AR
webcam (05ca:1834).

Thanks to Utz-Uwe Haus for getting the Sony VGP-VCC7 firmware extracted, and
providing a patch against the original r5u870 driver, and providing the
recode-fw.scm script.

Some friendly folk on the Ubuntu Forums for providing extracted version of
firmwares and their associated version numbers.

Thanks to Francesco Palmisano for providing an updated version of 183b and Sony VGP-VCC8 driver, and testing.

Thanks to Gonzalo Alvarez for testing the 1812 driver and providing usbsnoop
traces of the device.