$Id: setup.html 2424 2009-11-14 16:50:56Z isely $
Mike Isely <isely at pobox dot com>
You can find the main driver page on the web at http://www.isely.net/pvrusb2/pvrusb2.html.
This page describes the various prerequisites to using the pvrusb2 Linux driver and what steps you need to take in order to get your PVR USB2 hardware working.
To use the pvrusb2 driver in your Linux system, you must (1) satisfy the prerequisites, (2) compile the driver, and (3) obtain and install appropriate firmware images. You might also (4) have to deal with various support modules (chip-level drivers) if you are using an old kernel. This page is divided into sections corresponding to those steps.
Contents
Prerequisites / Compatibility
Driver compilation and installation
Firmware retrieval and installation
Support Modules
This driver only works under Linux 2.6.x. I have not made any attempt to even try it in 2.4.x and I know there are environmental differences which likely prevent it from running or even loading.
Note: If you are using kernel version 2.6.18 or later and wish to use the in-kernel version of the driver, then you can ignore everything below about kernel versions. If you are using any kernel older than 2.6.18, then keep reading.
Note: Newer hardware support in this driver generally means correspondingly newer kernel versions are required. In particular you'll need 2.6.26 or later to handle the digital side of hybrid devices.
Note: Gotview an OnAir support are newer than 24xxx or 29xxx, and definitely not in any kernel version prior to 2.6.25. If you are using a kernel older than that with a Gotview device, then you must use either the in-V4L or standalone pvrusb2 drivers.
HVR-1950 devices use a very new type of tuner; you will likely need 2.6.26 or later to run such a device.
Within the 2.6.x kernel series and if you are using the standalone driver (as opposed to the in-V4L or in-kernel variations), then there are additional limits, due mainly to the state of V4L in a given kernel. You really want to use a recent version of kernel; generally the later the kernel version probably the easier the time you will have. Going backwards in time:
Note that only the 2.6.18 kernel (and later) have the pvrusb2 driver in-kernel. Everything below this point requires you to use the standalone driver or the in-V4L driver version.
If the kernel version you are using is listed as one which may require replacement of chip-level drivers, read the modules section below and then see chipdrivers.html for more details.
The above constraints only apply for the standalone variant of the pvrusb2 driver. The in-V4L variant of the driver is separately constrained by the V4L environment there itself - but it also means that it should work anywhere that the V4L repository can be made to work (as of 14-Mar-2009: only for kernels 2.6.19 or later, and probably soon that floor will rise to 2.6.22). Basically, if the current Mercurial snapshot of V4L is known to work well in kernel 2.6.X, then the in-V4L pvrusb2 driver will probably work there as well. This is because most of the constraints that limit the standalone driver have to do with whatever V4L modules were included in that kernel. When you build the in-V4L variant of the driver you are also building all of the V4L modules as well and therefore you will be using the latest versions regardless of whatever the kernel might have included. I said in the background section that if you use the driver in-V4L that you would also have to install the other 50+ modules that come with it. Well, for older kernels that might actually be considered to be an advantage.
Unfortunately at this writing the V4L repository only actually is known to work with kernels back to 2.6.19. This is due to some API-breaking changes in the Linux kernel tree that the V4L repository is unable to cope with in a backwards compatible fashion. So if you go the in-V4L route, you are unfortunately effectively limited to kernel versions 2.6.19 or later.
None of the above applies for the in-kernel variant of the driver. As one might expect all support needs for the in-kernel pvrusb2 driver are already in-kernel as well.
I routinely build and test this driver using a Debian based system, and I run only vanilla Kernel trees here from kernel.org. I do not run any distro-specific kernels, thus I cannot guarantee or otherwise support this driver in any distro-specific kernel. You are of course welcome to try, but you may have problems if the vendor is in the habit of back-porting newer-kernel changes into older kernels. The reason why is this: There are various APIs that have been getting thrashed / changed etc in each version of the kernel. Some changes have been in V4L while others have been in the kernel itself. An out-of-tree driver like the standalone pvrusb2 driver has only a single defense against this - by implementing conditionally compiled code that conditions itself on the kernel version against which the driver is being compiled. That works well for vanilla kernels. However when a distribution vendor back-ports changes between different versions of the kernel then you can get problems where an unexpected API change shows up in a different version of the kernel and then compilation breaks.
I can't get into the business of identifying distro-specific versions and modifying the driver to adapt to stuff like that. I'm not a Fedora user so there's no way I can test this sort of thing. Also if I were to try to support Fedora in this way, then where does it stop? The burden of having to test compile against each possible kernel variant can be overwhelming. I have a hard enough time just test compiling against 4-6 kernel versions for each snapshot - and if you look at the change history you'll see I've even failed in that regard multiple times...
If you find yourself in this situation, all is not lost. Seriously consider moving to a vanilla kernel anyway. Or hunt around your distro for a later kernel that doesn't choke the driver build. You could also just try to edit the driver sources and if you want to send me a patch I'll look at it - but I can't promise I'll include it if it might be hazardous to the vanilla kernels. Also of course even if I apply such a patch I can't support it or guarantee that it will continue to build correctly in the future.
I'm not trying to be a pain; it's just that there's a limit to how many kernel variants I can juggle here and still have time left to actually improve the driver.
This driver uses a standard kernel facility for loading firmware images from the file system, and that facility requires a userspace utility to be present. Currently that utility is udev. For older Linux distributions, the hotplug utility filled this role. Either way, you need one or the other or firmware loading will not work correctly. You must have udev or its equivalent installed in order for this driver to work.
There are a number of things you must have configured into your kernel in order for the standalone driver to work. (For the in-kernel driver, the appropriate dependencies should be set automatically when you select the driver.) You have to enable firmware loading, you have to enable V4L, and you have to enable various options so that required support modules, a.k.a. "chip-level drivers" are built for your kernel. Note that if you are using a pre-built vendor kernel then you may want to at least ensure that these options have been set (and if not, go build a vanilla kernel):
A subset (depending on kernel version and hardware type) of the remaining options must be configured for the standalone driver. None of these should be required for the in-V4L version of the driver, since in that case the surrounding V4L source tree should provide everything needed:
There might yet still be other configuration options that must be turned on - the above are only what I've identified so far. In my test builds, I basically build everything anyway as modules so I tend not to notice if something might be missing...
If you are compiling against a kernel older than 2.6.15, then things get a little trickier, because it wasn't until 2.6.15 when all the chip-level drivers actually made it into the kernel tree. See the Support Modules section below for more information about this. Best advice: stick to kernel versions 2.6.15 or (preferably) later.
If you see messages in the log of the form "WARNING: No decoder present", that is an indication that saa7115 or (if you have 24xxx or Gotview hardware) cx25840 was not configured into your kernel. It's always a good idea to check that you have the appropriate options set, as defined above.
The following subsections describe the various different build scenarios possible. Pick the appropriate heading and read on...
Compiling and installing the standalone driver itself it actually the easiest part of this process; the driver is just a collection of sources which you must compile together to produce the pvrusb2.ko module, which is then inserted into your running kernel to implement control of your device.
The standalone pvrusb2 driver sources and build files can be found in the driver subdirectory of the driver snapshot; follow the rest of this section to build it.
Compile this driver more or less in the usual way one does to build 2.6.x kernel modules outside of the kernel source tree. Said another way, you need a kernel source tree somewhere nearby, and you need to run make in the driver directory with KDIR or KREL variables set to help make find where you put that source tree. For example (starting from the root of the driver snapshot tree):
export KREL=`uname -r`
export KDIR=/lib/modules/$KREL/source
make --directory driver
If you set neither KDIR nor KREL, then KREL is assumed to be the output of uname -r and KDIR is assumed to be /lib/modules/$(KREL)/source (same as the example above). Since nothing else except the default KDIR value needs KREL, then you can skip setting KREL if you set KDIR. This is all explained in the comments that you can find within the Makefile itself (both in the driver and ivtv subdirectories).
Once you have the driver compiled, you must copy the the pvrusb2.ko module into your kernel's module area. The target directory is typically under /lib/modules/$(KREL). I usually use /lib/modules/$(KREL)/pvrusb2/ as the destination but the choice is up to you. After pvrusb2.ko is copied, run depmod -a so that the module loader will recognize any needed dependencies.
You should be able to also just run make install and the driver should be copied into the appropriate place.
You can next execute modprobe pvrusb2 to load the driver. After this point, lsmod should show pvrusb2 present. This step is not strictly needed however, as hotplug (which you likely have set up anyway due to firmware loading requirements) will do the needed module loading when the device hardware appears in the system.
If you are using the in-V4L version of this driver, then you must build and install V4L itself - there's nothing special here related to the pvrusb2 driver. Go instead to linuxtv.org and read their documentation for how to check out, build, and install the full V4L subsystem from their repository.
There's no special knowledge needed to build the in-kernel driver, since obviously the kernel build process takes care of that. Just select it as a configuration option when you configure the kernel. So, nothing to see here, move along...
This is an uncommon scenario, but it can prove useful in the following situation:
In this case apparently you still want to use the standalone pvrusb2 driver at the same time you are using a V4L repo. Typically I'd just say use the in-V4L version of the pvrusb2 driver, but perhaps there's some reason you don't want to. (Maybe you just want to make more work for yourself...) In order for this scenario to build correctly, then you need to compile the standalone pvrusb2 driver against both the kernel and your V4L repository snapshot. This is important because the pvrusb2 driver depends on headers from V4L and they tend to change when you replace V4L. For standalone driver snapshots from 20060625 onward, there is a way to do this.
To compile the standalone pvrusb2 driver against V4L and the kernel, follow the normal standalone build procedure above, but you must also pass another environment variable that tells the pvrusb2 build about the V4L repository. That variable is V4LDIR, and is expected to be set to the path where the top of your V4L tree is residing. For example (and assuming that the pvrusb2 driver is in your CWD), if your V4L tree is in /usr/src/v4l-dvb, then do this:
export KREL=`uname -r`
export KDIR=/lib/modules/$KREL/source
export V4LDIR=/usr/src/v4l-dvb
make --directory driver
This build process may produce some warnings. You might see messages like this:
*** Warning: "cx2341x_fill_defaults" [/home/isely/pvrusb2/driver/pvrusb2.ko] undefined! *** Warning: "cx2341x_log_status" [/home/isely/pvrusb2/driver/pvrusb2.ko] undefined! *** Warning: "cx2341x_ctrl_get_menu" [/home/isely/pvrusb2/driver/pvrusb2.ko] undefined! *** Warning: "cx2341x_update" [/home/isely/pvrusb2/driver/pvrusb2.ko] undefined! *** Warning: "cx2341x_ctrl_query" [/home/isely/pvrusb2/driver/pvrusb2.ko] undefined! *** Warning: "cx2341x_ext_ctrls" [/home/isely/pvrusb2/driver/pvrusb2.ko] undefined!
The warnings might vary, depending on the kernel you are using. These can be safely ignored. What is happening here is that the kernel build system is finding references which are actually resolved by modules in the V4L repository but happen to not be in the kernel tree. This is OK. Provided you have the V4L repository compiled and installed as well, then everything should be fine.
NOTE: Even if you intend to use the in-V4L or in-kernel versions of the driver, you must still either obtain the firmware from somewhere or extract the firmware from your driver CD using the instructions here.
Hardware driven by the pvrusb2 driver has several parts within it that require firmware in order to operate correctly. That firmware is not a part of this driver; you must obtain it from elsewhere (e.g. your Windows driver CD, the device maker's web site, or perhaps a 3rd party). In addition, the exact firmware files you will need will depend on which type device you have.
IMPORTANT: If you are using an HVR-1950, the vendor FX2 firmware for that device has recently increased in size from 8KB to 16KB. This causes an issue because all in-kernel pvrusb2 driver versions up through kernel 2.6.32 enforce this size to be strictly 8KB - anything else will cause the driver to reject the firmware image. This has been fixed in the standalone driver (anything 31-Oct-2009 or later) and should propagate to the in-kernel and in-V4L drivers shortly. But this strictly requires that if your kernel is 2.6.32 or older and your FX2 firmware size is 16384 then you absolutely must use the standalone pvrusb2 driver or the in-V4L pvrusb2 driver.
In order to obtain the firmware, there are multiple posssible strategies available, depending on the vendor:
The central piece of the firmware extraction puzzle is just a Perl script, called fwextract.pl. It is included in the utils subdirectory of the standalone driver snapshot. If you are using the in-V4L driver driver version however you won't want to deal with grabbing that whole snapshot - in that case you can download a reasonably recent version of the script from here:
http://www.isely.net/downloads/fwextract.pl
This extraction program is fairly smart; you need only point it at a directory where the actual Windows driver files have been placed and it will automatically hunt down and extract appropriate firmware images. This script uses MD5 sums to identify its target(s) and so it normally works across all currently known driver versions and hardware variants. It also verifies the extracted results with additional MD5 sums, so if it writes a firmware image file at all, you can have high confidence that it is indeed correct.
Note about compressed driver packages in general and OnAir drivers in particular: The fwextract.pl program knows how to scan files, but it cannot decompress them. This means that if you download a driver from the vendor's site as, say, a zip file, then you must unzip it first and then point fwextract.pl at the results. Otherwise fwextract.pl won't find anything to extract. This has an undesirable effect: If the vendor compressed the driver package in a way that can't be uncompressed with any Linux tool, then you may be out of luck. This can happen if the driver package is a self-extracting EXE and something other than a zip variant was used to compress it. And unfortunately this is in fact the case for OnAir supplied Windows drivers. This is why you can't easily use fwextract.pl for OnAir (unless you first go find a Windows system to uncompress the package first). This is also why OnAir has made their firmware directly available (see earlier section above).
Note: The fwextract.pl program will scan any nested subdirectories it might find. This means two things: First, if the driver package you are trying to extract from has nested subdirectories (it usually will), then you can avoid trying to guess the exact directory to scan. Second, if you were to accidentally specify, oh, say "/" as the "driver directory" then fwextract.pl will likely take a very long time to find the firmware. (It will however probably still find it if you wait long enough and have enough virtual memory available...)
The general process of firmware extraction is this:
Note that when the term "Windows driver files" is used above, it is refering to a directory tree full of files that contains the drivers from Hauppauge (or Gotview). That unfortunately is easier defined than found because Hauppauge in particular seems to like packaging these drivers in different ways. If you're working from a CDROM distribution, then we're refering to the root directory of the CDROM - for 29xxx hardware but the DriverD2 subdirectory of the CDROM for 24xxx hardware(!). If you are working from a download package, there might be several such packages but only one has the files you want. For example, the packages pvrusb2_23_31351.exe and pvrusb2_27_23178.zip each contain a driver set, but pvrusb2_26_23055.exe does not - instead in that case the actual drivers are in pvrusb2_inf.zip. Why did they do this? I have no idea; it just confuses. Best advice here is make a guess and if fwextract.pl doesn't spot anything then try a related package.
Stated more literally, here is an example of the set of steps you can do:
Substitute the name of the driver package you got from the vendor for "driver_package.EXE" which is just a placeholder above. If you're starting from a CDROM copy of the drivers, then just copy the driver subdirectory contents into "win_driver" or just list the directory name as a command argument to fwextract instead of doing the unzip step above. For $UTIL_DIR, substitute the path where you have located the fwextract script.
If you extracted from a driver package for 29xxx hardware, you should then see the following two firmware files:
File Size Description v4l-pvrusb2-29xxx-01.fw 8KB FX2 program for 29xxx device v4l-cx2341x-enc.fw 256KB (approx) cx23416 encoder firmware
Note: The above two files used to be known as pvrusb2.f1 and pvrusb2.f2, respectively. Starting with the 20060318 snapshot they have been renamed (but the snapshot should also locate and use the old files if they are present).
If you extracted from a driver package for 24xxx hardware, you should then see the following three firmware files:
File Size Description v4l-pvrusb2-24xxx-01.fw 8KB FX2 program for 24xxx device v4l-cx2341x-enc.fw 256KB (approx) cx23416 encoder firmware v4l-cx25840.fw 13KB (approx) cx25840 audio/video decoder firmware
With more recent Hauppauge driver packages both sets of firmware will be in the same package, in which case fwextract.pl will locate and extract everything:
File Size Description v4l-pvrusb2-29xxx-01.fw 8KB FX2 program for 29xxx device v4l-pvrusb2-24xxx-01.fw 8KB FX2 program for 24xxx device v4l-cx2341x-enc.fw 256KB (approx) cx23416 encoder firmware v4l-cx25840.fw 13KB (approx) cx25840 audio/video decoder firmware
If you extracted from a driver package for Gotview hardware, you should then see the following two firmware files:
File Size Description v4l-cx2341x-enc.fw 256KB (approx) cx23416 encoder firmware v4l-cx25840.fw 13KB (approx) cx25840 audio/video decoder firmware
If you extracted from a driver package for OnAir hardware (but probably not since OnAir driver packages can't be uncompressed in Linux), you should then see just the following firmware file:
File Size Description v4l-cx2341x-enc.fw 256KB (approx) cx23416 encoder firmware
If you extracted from a driver package for HVR-1950 hardware, you should then see the following three firmware files:
File Size Description v4l-pvrusb2-73xxx-01.fw 8KB or 16KB FX2 program for HVR-1950 device v4l-cx2341x-enc.fw 256KB (approx) cx23416 encoder firmware v4l-cx25840.fw 13KB (approx) cx25840 audio/video decoder firmware
Note: The HVR-1950's FX2 firmware can be either 8KB or 16KB. More recent versions are 16KB. If you have a 16KB (16384 bytes) sized FX2 image, you may need a more recent pvrusb2 driver. Definitely any in-kernel pvrusb2 driver in kernels 2.6.32 or older will not successfully load a 16KB FX2 image. Any standalone driver dated 31-Oct-2009 or later should handle it fine. See the warning at the top of this page (here) for more detail.
If the extraction didn't work, then possibly you are dealing with a later driver version that fwextract.pl doesn't know how to handle yet. Solving this requires a more complex manual extraction. See firmware.html for more info. Note that fwextract.pl can find some firmware files in newer drivers now even without additional specific knowledge about the driver package. So, if it found some but not all of the firmware files listed above for your device, then it probably didn't work.
What this all really boils down to is just a matter of expanding all the Windows driver files into a single place and then letting fwextract.pl chew on it for a while to locate the firmware. The extract script doesn't care about file names or history; it works purely by recognizing file MD5 sums and acting on what it finds.
Assuming that fwextract.pl recognizes the driver files, it will automatically locate and extract the firmware. No firmware file guesswork, ever.
Failing all of the above, you can still try to extract the firmware using an older method (before I started working on this) - but such a method does not verify the image, is specific to a single version of the Hauppauge driver package and is of no use to anyone with other than 29xxx hardware. Information on this can be found on Björn's web page. Note that you may need to rename the firmware file names in that case (see table above for clues on the correct names). If you find you must use this (frankly obsolete) method of extraction, please contact me so we can figure out why fwextract.pl apparently did not work for you.
The pvrusb2 standalone driver also includes a wrapper script in the utils subdirectory that will attempt to further simplify the process, for 29xxx devices. This is a contributed script, called fwfind.sh. What this does is attempt the surrounding steps: It will locate or download the Windows drivers for you and then it will run fwextract.pl to perform the actual extraction. Thus to extract using this method involves just one step: run fwfind.sh. If it works for you, great. If not, then just use fwextract.pl directly, as described above. As of this writing, fwfind.sh will only work for 29xxx hardware, i.e. it only downloads and extracts using a Hauppauge driver package for 29xxx hardware - so if you're using 24xxx hardware then this is not an option for you.
The result of the extraction process will be some number of firmware files that have to be put somewhere. During its initialization the pvrusb2 driver (and possibly also the cx25840.ko chip-level driver) will expect to find these files, load them into memory and then upload their contents to the pvrusb2 device. For this to work, you have to be using udev (or something that supports the kernel firmware request facility), and you have to place these files in a spot where they can be found. The exact location may be distribution and utility dependant. On my Debian system, viable locations include:
/lib/firmware
/usr/local/lib/firmware
/usr/lib/hotplug/firmware
However, your distribution may have things configured differently. For example, perhaps your system is configured to look in /lib/hotplug/firmware instead. When hotplug is in use, the firmware.agent script is programmed with these locations. Try this command to find out your list of candidate firmware directories:
grep FIRMWARE_DIRS
/etc/hotplug/firmware.agentCopy the firmware images to the appopriate location. Once there, then the pvrusb2 driver will be able to retrieve what it needs and upload appropriate data to the device hardware.
The following information is rather old and only really applies if you are running a really old kernel. It will be a rare circumstance indeed if you have to deal with what is described in this section; I only still include it because the current pvrusb2 driver should in theory still work with kernels this old (though honestly I haven't tested anything this old in quite a long time).
The architecture of the pvrusb2 driver (and for that matter all V4L drivers) is that "the" driver doesn't actually do all of the work. Most chip-level operations are instead handled by an ensemble of common chip-level drivers - the exact modules needed will depend on which chips are in your device. The pvrusb2 driver performs in the role of the "conductor" within that ensemble, sending commands to those attached chip-level drivers as needed to accomplish whatever overall task is being executed at a given moment. (And the chip-level drivers in turn work back through the pvrusb2 driver to communicate with the controlled hardware in the device.) This scheme works because many different TV tuner / capture devices happen to use a lot of common chips. All that the "conductor" driver has to do is ensure that the various chip-level drivers work in concert correctly to operate the device.
Unfortunately, working with common modules like that means that it's another boundary where compatibility / breakage can occur. In an ideal world, all the chip-level drivers you will ever need will already be present and perfect. But in the V4L world, things constantly change, and that may require you to update / replace a few of those modules before your hardware is going to work...
If you are using the standalone driver in kernel version 2.6.15 or later, then you should be able to safely ignore everything about dealing with chip-level drivers. This is because in those cases all the drivers you need will already be present and are usually mature enough not to be a problem. (Note: For Gotview hardware, 2.6.15 is probably not good enough by itself due to the cx25840 module being too different with its method for handling video/audio routing.)
On the other hand if you are compiling against a kernel older than 2.6.15, then things get a little trickier, because it wasn't until 2.6.15 when all the chip-level drivers actually made it into the kernel tree. Worse still, some of those drivers that do exist in the older kernels can be broken in various subtle ways. Basically in those cases you are faced with having to use replacement chip-level drivers. There are three ways to meet this requirement:
No kernel older than 2.6.15 includes the saa7115.ko or cx25840.ko chip-level drivers so you unavoidably need to deal with that if you want to run an old kernel. Other than that, kernels at least back to 2.6.11 include the other chip-level drivers, though sometimes in an incomplete or less than functional form.
For a complete discussion of all these chip-level driver requirements and what to do in various scenarios, see here. A better and far less painful choice however is to just run kernel 2.6.15 or later - then you won't have to worry about any of this.