$Id: firmware.html 1153 2006-05-17 04:39:09Z 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 provides additional information related to manually extracting the firmware needed for the PVR USB2 hardware. (There is an easier way to do this; please try this procedure first before wading through this page.)
Contents
Overview
cx23416 & cx25840 firmware capture
FX2 firmware capture
Locating the Firmware
The PVR USB2 hardware has several parts within it that require firmware images to be loaded first 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 or from Hauppauge's web site). In addition, the exact firmware files you will need will depend on which model of the PVR USB2 device you have. Whether you are using the standalone pvrusb2 driver snapshot or the in-V4L version of the pvrusb2 driver, you will need to obtain and install the appropriate firmware images before your device will function correctly.
The easiest means for extracting the firmware is NOT described here. It is instead documented as part of the normal driver setup. You can find that information in the Firmware extraction and installation section within setup.html. Try there first, and if that failed to work, then read on.
There is the occasional situation where the easy method doesn't work. It is possible that fwextract.pl might not recognize your driver package no matter what you throw at it; you'll see messages of the form "failed to locate data for writing filename" (where filename is the firmware file it tried to generate). This can happen if Hauppauge releases new drivers and fwextract.pl hasn't been updated yet. If this is indeed the case, then things are somewhat more difficult - we need to manually identify the firmware data and teach the script where to find it when it encounters the new driver package.
Basically what has to be done if this happens is something like this:
The second step runs a process to scan the original Windows driver files and find where the firmware (previously fetched here in step 1) is hiding. Once found, fwextract.pl will write a Perl expression to the terminal which contains new table entry needed by the extractor for locating the firmware in the future. Send that snippet to me and I'll place it into the master copy of fwextract.pl so that other users can benefit from your hacking effort.
The first step here is obviously the big one. There are two approaches to it. One approach is that someone good at reverse-engineering starts hacking away with a hex editor to find the embedded data. Yuck. Another approach is to capture the firmware from the hardware itself - which we can do. There are at least two pieces of data to capture: the cx23416 (mpeg encoder) firmware and the FX2 (device microcontroller) firmware. If you have 24xxx hardware, then you need to capture the cx25840 (video & audio digitizer) firmware as well.
Important Note: Since the pvrusb2 driver needs the cx23416 firmware to be successfully loaded in order to function at all right now, you will need to first capture at least the cx23416 firmware (which doesn't involve the pvrusb2 driver) before you attempt to capture the FX2 firmware.
To manually capture the cx23416 and cx25840 firmware images, you need to use the USB sniffer to grab it "in flight" from within Windows and then use several tools included with the standalone driver snapshot to extract the firmware data from the stream.
The USB sniffer is a handy free utility that can be found at http://benoit.papillault.free.fr/usbsnoop/.
The additional tools you will need are included with the standalone driver snapshot. Specifically, you will need usbreplay.pl to distill the output of the USB sniffer down to a simpler form, and you will need the decompiler (decode_log with the "--firmware" option) to extract the firmware data from the stream. Note that the decompiler is C++; if you haven't yet compiled it then just run make in the utils directory to build it.
Additional information about all of this can be found in the Sniffing and decompiling USB traffic section of of the utils.html page.
The process is roughly the same regardless of the type of hardware you have - you'll get one file out of this if you are using 29xxx hardware and two files if you are using 24xxx hardware. Here's the exact procedure:
usbreplayprep.pl < logfile.txt | decode_log --firmware firmware_file > /dev/null
The result of that last step will be either 1 or 2 files. If you are using 29xxx hardware you should see one file named "firmware_file". If you are using 24xxx hardware you should see two files, named "firmware_file-1" and "firmware_file-2". You need to rename these files. For 29xxx hardware with a single file, just do this:
mv firmware_file v4l-cx2341x-enc.fw
For 24xxx hardware, you first need to figure out which file is which and then rename them accordingly. You must not get this backwards! One file will be exactly 256KB in size - that will be the cx23416 image and you should rename that to "v4l-cx2341x-enc.fw". The other file will be roughly 13KB in size (this might vary); rename that file to "v4l-cx25840.fw".
Important note: If you are using the in-V4L version of the pvrusb2 driver, be sure you have built it with the debug interface option (CONFIG_VIDEO_PVRUSB2_DEBUGIFC) enabled. Doing this enables a feature that you need in order to capture the FX2 firmware. For the standalone pvrusb2 driver, this is enabled by default.
Capturing of the FX2 firmware is entirely different. The USB sniffer doesn't see this traffic right now so we have to take a different strategy. I've added a feature to the pvrusb2 driver that makes possible the direct retrieval of the firmware data from the device. Here's the procedure:
echo "cpufw fetch" >/sys/class/pvrusb2/sn-XXXXXXX/debugcmd
cat /dev/video0 >/tmp/fx2.fw
echo "cpufw done" >/sys/class/pvrusb2/sn-XXXXXXX/debugcmd
It is imperative that you do not power cycle the device when switching from Windows to Linux. This allows the FX2 firmware to be retained in the device's memory, and will cause the pvrusb2 Linux driver to not attempt to reload the firmware. Thus when you run the command sequence to pull the firmware back, you'll get what had previously been loaded by Windows.
Your device will reset itself after the "cpufw done" debug command is sent to the driver. The file /tmp/v4l-pvrusb2-29xxx-01.fw for 29xxx hardware (or /tmp/v4l-pvrusb2-24xxx-01.fw for 24xxx hardware) is an image of the FX2's program memory. Note that this isn't the exact bit-for-bit copy of the firmware file you need; apparently the FX2 program modifies itself slightly. However it's close enough that the fwextract.pl program's --search feature can still locate the pristine firmware data using a fuzzy matching algorithm (which it will fall back to if an exact search doesn't find it).
After you've gotten the firmware images retrieved and named correctly, put copies of all the files in the current directory (if you haven't already done so). The exact set of files to have copied will depend on your hardware type; just to review, by this point you should have copied across the following names:
For 29xxx hardware:
v4l-cx2341x-enc.fw
v4l-pvrusb2-29xxx-01.fw
For 24xxx hardware:
v4l-cx2341x-enc.fw
v4l-pvrusb2-24xxx-01.fw
v4l-cx25840.fw
Now unpack the Hauppauage Windows driver package again into an empty "win_driver" subdirectory, then run fwextract.pl --search. (If you installed from a cdrom, you can alternatively mount the cdrom under Linux and use the --driverDir=<path> option to point at the mount point instead of the default win_driver subdirectory.) After a minute or so it will print the magic chunk of data that can then be put back inside fwextract.pl so it will now automatically understand how to extract this firmware data in the future. Send that magic chunk to me (along with a description of the driver package) and I'll ensure that the next release of fwextract.pl includes it.
You should in theory be able to just use the manually extracted firmware files. However the FX2 firmware image (either v4l-pvrusb2-29xxx-01.fw or v4l-pvrusb2-24xxx-01.fw) may not be exactly identical to what is really loaded, so you may really want to go back and get the real firmware out of the driver directory anyway. Do the following:
Don't forget to send me that magic chunk of data so that I can update the master copy of fwextract.pl. Please also include a 1 line description that indicates some kind of uniquely identifiable attribute of the driver package from where you extracted the firmware. You can find my e-mail address at the top of pvrusb2.html.