HDTV capture driver for cx2388x

[Jason Harmening]

Okay, looks like the mailserver scrubbed the attachments.  For anyone who's 
interested, both the source tarball and the iicbus patch are available at 
ftp://corona.homeunix.net.

On Sunday 30 September 2007, Jason Harmening wrote:
> Hi everyone,
>
> I've been working on a FreeBSD driver for cx2388x-based TV cards on and off
> for several months since I came
> into possession of an old pcHDTV HD-3000 in late 2006.  I only recently
> learned about jmg's work with cxd, but I'm making my driver available in
> case anyone is interested.  It works reliably with my HD-3000; I've managed
> to capture several hours of live TV.  I've only been able to test it on my
> own machine, which is 6-STABLE/amd64/SMP.  It'll need a little work
> (interrupt filters, at least) to be usable with 7-CURRENT.
>
> I've attached a tarball with full sources--I hope the mail server doesn't
> remove the attachments, but if it does and you're interested, let me know
> and I'll send you a copy.
>
> The driver is called "cx88"--one of the few
> things it has in common with the Linux driver.  Here's a not-so-brief
> overview of the contents in case you're interested:
>
> common/
>
>         Sources for cx88.ko, wich implements channel configuration, buffer
> configuration, and RISC program routines common to all functions.  Provides
> a "board data" facility to allow drivers for different functions on the
> same physical board to coordinate usage of shared resources (e.g. the
> SRAM). Dynamically sizes the SRAM allocation for each DMA channel based on
> the total number of DMA channels claimed by attached drivers (MPEG, analog
> video, audio, etc.).  Allows RISC programs to be placed in SRAM if there's
> enough space.  Allows for data buffers to either be allocated in the kernel
> and mmap'ed or allocated in user mode and vslock'ed.
>
> i2c/
>
>         Sources for cx88i2c.ko, which controls the onboard i2c bus.  Uses
> interrupt-driven, hardware I2C.  Directly implements the iicbus interface
> instead of going through iicbb, so on 6.x it requires the attached patch to
> get iicbus.ko to export its driver_t.  I don't think this is necessary on
> 7-CURRENT though.
>
> mpeg/
>
>         Driver for mpeg transport stream (cx88mpeg.ko).  Depends on both
> cx88.ko and cx88i2c.ko.
>
> video/
>
>         Skeleton analog video driver.  Doesn't really do anything right
> now.
>
> iicdev/
>
>         Sources for iicdev.ko--generic kernel mode driver for i2c device
> control from user mode.  Mostly I implemented this because I don't really
> care for iic's use of Giant or its ioctl interface.  iicdev
> isdevice-centric, so an iicdev character device is created for each i2c
> device.
>
> libtuner/
>
>         (libtuner.so) User-mode drivers for tuners, demodulators, and
> anything else
> that constitutes the "frontend".  This idea, along with support for
> user-mode buffers, I got from jmg's bktrau driver.  Implemented in C++.
> Currently only contains drivers for the Thomson DTT7612 tuner and Oren
> 51132 demod on the HD-3000.  Configurable via text file.  This is library
> is designed to be easily extensible to support additional tuners/demods and
> to possibly work with other drivers besides cx88.
>
> cx88_client.cpp, cx88_user_client.cpp
>
>         Really lame capture apps I kludged up to test cx88mpeg.
> cx88_client.cpp uses conventional (kernel-allocated) buffers, while
> cx88_user_client.cpp uses user-allocated buffers.  Mostly I included these
> just to demonstrate how to use the cx88mpeg ioctl() interface.
>
> client/
>
> 	Not-so-lame multi-threaded capture app.  Allows simultaneous streaming
> over UDP and capture to file.  Also allows for channel to be changed and
> signal status to be queried on-the-fly.  Uses XML configuration file for
> channel maps--requires textproc/ezxml.
>
> or51132_*.fw
>
>         8VSB and QAM firmware files for the OR51132 demodulator.
> Automatically loaded as necessary by the libtuner or51132 driver.
>
>
> Whew!  Anyway, here are my short-term goals for the driver:
>
> 0) Keep testing and fix any bugs I find.
> 1) Add decent comments and documentation--this is mostly done for the
> kernel-mode pieces, but libtuner and the client application need
> documentation.
> 3) Get my hands on a pcHDTV HD-5500.  If I've done things right, I'll only
> need to add drivers for the LG tuner and demod to libtuner, and add a
> pchdtv_hd5500 class to the capture application.
> 4) Work on analog video driver and maybe, once I get the 5500, audio as
> well. 5) When I'm ready to upgrade to FreeBSD 7.0 (probably during the beta
> phase), add interrupt filters, ditch the iicbus patch, and do whatever else
> is necessary to get this puppy working under 7.0.
>
> Here are some quick instructions on how to use the driver:
>
> 1.  Extract the source tarball.
>
> 2.  To patch the iicbus driver:
> 	cd /usr/src/sys/dev/iicbus
> 	patch < patch_iicbus
> 	Reload iicbus.ko or recompile kernel
>
> 3.  Install textproc/ezxml.  The capture app uses this to parse its XML
> channel map configuration file.
>
> 4.  From cx88_20070930 directory extracted from source tarball, type
> 'make', or, if you want your system log full of status messages from the
> driver, type 'make -D DIAGNOSTIC'.  This will compile all kernel-mode
> drivers, libtuner.so, and the capture app (called 'cx88'--creative, I
> know).
>
> 5.  From the same directory,
> 	kldload iicdev/iicdev.ko
> 	kldload common/cx88.ko
> 	kldload i2c/cx88i2c.ko
> 	kldload mpeg/cx88mpeg.ko
>
> To use the client application:
>
> The capture app (cx88) depends on libtuner, so make sure the libtuner/
> directory (or wherever you're keeping libtuner.so) is in your library path.
> Libtuner uses a simple text-based configuration file to allow for flexible
> configuration of tuner drivers that may need it--an example can be found in
> client/.tuner_config, which specifies the paths to the OR51132 firmware
> files.  The cx88 executable uses an XML configuration file to load its
> channel maps--an example can be found in client/cx88.xml.  At some point
> I'll document the syntax for this file, but cx88.xml should be adequate for
> receiving OTA HDTV broadcasts.
>
> Here's a list of the command-line options for the cx88 executable:
>
> -d <path>: [Required] Specify device from which to capture
>
> -c <channel | profile:channel>: [Required] Specify initial channel, e.g.
> '7' or 'ATSC:7'
>
> -u <host-ip | host-ip:port>: [Optional] Send capture over UDP to provided
> host
>
> -f <filename>: [Optional] Send capture to specified file
>
> -x <filename>: [Optional] Specify XML configuration file; default is
> ~/.cx88.xml
>
> -t <filename>: [Optional] Specify libtuner configuration file; default is
> ~/.tuner_config
>
> -n <value>: [Optional] Specify non-interactive capture for provided number
> of minutes
>
> -? : Display this list of options.
>
> If you omit the -n option, cx88 will run in interactive mode, in which case
> you can enter the following commands to control the application on-the-fly:
>
> 'c':
> 	Changes channel on-the-fly.
> 	After entering the 'c' character, you'll be prompted to enter a channel
> number, optionally prefixed with a channel profile name from the XML
> configuration file.  For example:
> 	...
> 	c
> 	Enter channel:
> 	ATSC:56
> 	...
>
> 'i':
> 	Display channel/signal stats:
> 	...
> 	i
> 	Tuned to 725000000HZ
> 	        Signal strength: 80.8992%
>         	Signal-to-noise ratio: 28.3147
> 	        Bit-error rate: 0
>         	Uncorrected blocks: 0
> 	...
>
> 'q':  Quit the application.
>
> Examples:
>
> 	To launch cx88 in interactive mode, using device /dev/cx88mpeg0 for
> capture, initially tuned to channel 33 in the 'ATSC' profile, streaming
> data over UDP to host 127.0.0.1, port 8802, and also storing the same data
> to a file named 'abc.ts':
>
> 	./cx88 -t ./.tuner_config -x ./cx88.xml -u 127.0.0.1:8802 -f abc.ts -c
> ATSC:33 -d /dev/cx88mpeg0
>
> 	To launch cx88 in non-interactive mode, capturing channel 33 in the 'ATSC'
> profile to a file named abc.ts for 7.5 minutes:
>
> 	./cx88 -t ./.tuner_config -x ./cx88.xml -f abc.ts -c
> ATSC:33 -d /dev/cx88mpeg0 -n 7.5
>
> For playing the transport stream, either from a file or live via UDP, the
> best player I've found so far is multimedia/vlc.  However, I haven't yet
> found a player that allows you to select from multiple program streams
> broadcast on the same channel.
>
> Anyway, I hope there are people out there interested enough to wade through
> this long e-mail and maybe give the driver a try and let me know how it
> works!
>
> Thanks,
> Jason Harmening