HDTV capture driver for cx2388x

Jason Harmening jason.harmening at gmail.com
Sun Sep 30 13:17:06 PDT 2007

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:

        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. 


        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.


        Driver for mpeg transport stream (cx88mpeg.ko).  Depends on both 
cx88.ko and cx88i2c.ko.


        Skeleton analog video driver.  Doesn't really do anything right now.


        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.so) User-mode drivers for tuners, demodulators, and anything 
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.


	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.


        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 
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 

-t <filename>: [Optional] Specify libtuner configuration file; default is 

-n <value>: [Optional] Specify non-interactive capture for provided number of 

-? : 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:

	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:
	Enter channel:

	Display channel/signal stats:
	Tuned to 725000000HZ
	        Signal strength: 80.8992%
        	Signal-to-noise ratio: 28.3147
	        Bit-error rate: 0
        	Uncorrected blocks: 0

'q':  Quit the application.


	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, port 8802, and also storing the same data to a file 
named 'abc.ts':

	./cx88 -t ./.tuner_config -x ./cx88.xml -u -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 

Jason Harmening

-------------- next part --------------
A non-text attachment was scrubbed...
Name: patch_iicbus
Type: text/x-diff
Size: 754 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/freebsd-multimedia/attachments/20070930/e666edf6/patch_iicbus.bin

More information about the freebsd-multimedia mailing list