README for PWCX 9.0 

This package contains code and patches to get PWCX running on
a variety of kernels and processors. Hopefully this will eliminate
a lot of the versioning problems. This is the official release, after
2 betas which have wrinkled out quite a lot of details.

This release contains patches for 2.4.25 and 2.6.4 (may work on other
kernels with a little tweaking). In addition, it contains the PWCX core
code for the  following CPUs:
- ARM (hard- & software floating point)
- MIPS (mips1 & mips4)
- PowerPC
- SH4
- x86
- ia64 (Itanium)

In addition a small test utility is provided to test some new features from
PWC 9 (more below).

The idea behind this PWCX is simple: provide a small library (libpwcx.a)
that gets linked against a small piece of 'glue' C code that is compiled in
the kernel and contains all the kernel specific module stuff. The added
bonus is that with a little support from the kernel driver it is possible to
do decompression outside of the kernel, in your application. This allows you
to stream the raw data from the camera over a limited bandwidth channel (old
10 MBit/s UTP, wireless LAN), and decompress at the remote end.

Note: PWC/PWCX 9 is incompatible with PWC/PWCX 8 (that's why I bumped the
major version number in the first place). I do not intend to try a similar
approach for PWC 8.

* Open issues

 - Currently the Bayer format does not work, while it did work okay in 
   beta-2. Not sure what the problem is, Ill look into it.

* Changes

** 9.0 Official

 - Removed PWC 9.0 from the package, only PWCX is left.

* Installation notes

Below generic installation instructions are provided for 2.4 and 2.6 kernels.
I assume you have at least some knowledge of kernel building; no real kernel
compile is required: just modules.

NB: the directorynames below may of course be different on your system; adjust
as necessary.

** Installation 2.4.25 (probably works on 2.4.26 as well)

 - Download the tarball, extract (you probably already did this). I assume
   it is extracted in your homedirectory.

 - Go to your kernel sources (usually located in /usr/src/linux)
   # cd /usr/src/linux

 - Apply the proper patch for your kernel; this will modify the USB build
   structure
   # patch -p1 -s < ~/pwcx-9.0/patch-2.4.25

 - Copy the proper libpwcx.a to the directory; see the various
   subdirectories for builds of the library. You may also have to rename 
   the library while copying, e.g.
   # cp ~/pwcx-9.0/mipsel/libpwcx-mips4.a drivers/usb/libpwcx.a

 - Copy the glue code to the directory
   # cp ~/pwcx-9.0/pwcx/*.[ch] drivers/usb

 - Start up your kernel configurator
   # make menuconfig
     or
   # make xconfig

 - Go the USB section; you will find a "PWCX decompressor entry"; 
   enable it as module

 - Build your modules:
   # make modules modules_install

 - If all went well, you now have a working PWCX on your system!

!! Do not execute a 'make dep' or 'make clean' in your kernel source tree! 
!! That will remove all .a files :-(
   
  

** Installation 2.6.4

 - Download the tarball, extract (you probably already did this). I assume
   it is extracted in your homedirectory.

 - Go to your kernel sources (usually located in /usr/src/linux)
   # cd /usr/src/linux

 - Apply the proper patch for your kernel; this will modify the USB build
   structure
   # patch -p1 -s < ~/pwcx-9.0/patch-2.6.4

 - Copy the proper libpwcx.a to the directory; see the various
   subdirectories for builds of the library. You may also have to rename 
   the library while copying, e.g.
   # cp ~/pwcx-9.0/mipsel/libpwcx-mips4.a drivers/usb/media/libpwcx.a

 - Copy the glue code to the directory
   # cp ~/pwcx-9.0/pwcx/*.[ch] drivers/usb/media

 - Start up your kernel configurator
   # make menuconfig
     or
   # make xconfig
 - Go the USB section; you will find a "PWCX decompressor entry"; enable it as module

 - Build your modules:
   # make modules modules_install

 - If all went well, you now have a working PWCX on your system!

!! Do not execute a 'make dep' or 'make clean' in your kernel source tree! 
!! That will remove all .a files :-(


** TestPWCX

I've also included a small test utility; it demonstrates two new features of
PWC 9: raw data streaming + external decompression and Bayer image data (the
latter will probably enlighten amateur astronomers (pun intentional :-))).

testpwcx is a small Qt application and it requires also the libpwcx.a
library, since it does decompression outside of the kernel.

 - Go to the testpwcx directory
   # cd ~/pwcx-9.0/testpwcx

 - Copy the proper pwcx.a to this directory (see kernel instructions above).
   # cp ../<CPU>/libpwcx.a .

 - Configure and build the application
   # qmake testpwcx.pro
   # make

If that goes well you end up with a 'testpwcx' executable. Its use is simple:

   # testpwcx [options] /dev/videoX

It will show the YUV data from the device (thus grayscale, not color).
The supported options are:

  -r    Use raw data from the device, perform decompression inside the program
  -B    Show Bayer data

For those interested: "Bayer data" refers to the layout on the CMOS/CCD
sensor of the light-sensitive pixels; usually 1 red, 2 green and 1 blue in a
2x2 grid. The advantage of this mode is that you get the real, _unprocessed_
data straight from the CCD/CMOS (well, okay, it is compressed, but only by a
factor of less than 2; I doubt you will ever notice that). I refrain from
calling it "raw data" to avoid any confusion with the uncompressed
datastream.

