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

In the root directory of this project, there is a tool called 'recode-fw.scm'.
This is a Guile script that takes a Windows driver file and attempts to extract
the camera microcode from it.

You might also want to look at docs/disasemble_ucode.txt for information on how
to compile the fw-extract tool, as well.

Arguments & running
===================

There are several options you need to change in the scheme file. Generally, 
the Windows driver files are name "R5U870FLx86.sys". If this is not the case, 
update this on line 16 of the file. 

You'll also need to update the destination filename (line 18).

Now, open up your .sys file in a text editor, and look for the line ".pdb". It
should be around offset 0xAE96 or so (which is probably about the middle of
the file). Find the location of 0x40 0x00 (or 0x08) 0x80 as decimal, and put
that in as the 'start' parameter (line 20).

Once you've done that, give it an initial run (you'll need Guile installed):
 $ ./recode-fw.scm

Checking output
===============

The tool should do a good job cleaning up any crap data at the end of the
firmware file. You may need to increase the length, however. If you get an
error about Wrong type argument, try decreasing/increasing the "length"
argument in the script.

Hopefully also when you ran the script that you got a few 0 -> 0; lines. If
not, increase the "length" argument as well.

It's also preferable that you check that your decoded firmware file starts with
the correct data. Generally, the first triplet should look like:
 0x40 0x00 0x80 or
 0x40 0x08 0x80

There may be exceptions - this isn't a hard and fast guide.

Testing
=======

To test your decoded firmware file, you can run it through the loader tool in
'pretend' mode. In this mode, the loader will go through all the motions of
trying to upload firmware to the camera, but without actually sending any data.
It will verify that your firmware file will upload OK.

You'll need to add your camera to loader.h's device table. Open it up, and add
an entry near the bottom, before the final { } entry. It takes the format:
  { VID, PID, Microcode version },

Once you've added it (you can add a temporary microcode version for now if you
don't know it), compile and run the following:

 $ ./loader --pretend

and check the output for any errors. The tool should also give you the correct
microcode version to plug into the device table if there were no other errors.

More testing
============

Now comes the real test - actually uploading the data to your camera:
 $ ./loader --force-clear

and try to stream some video data!

If your camera refuses to accept any new microcode data, you may need to
completely shutdown and cold-boot (or, rip open your laptop and replug in
the camera ;).

Sharing
=======

Now that you've got your camera working, hg add the firmware and send off a
patch to alex@alexhixon.com (or ask me to pull in your changes).
