pvrusb2 driver information
$Id: pvrusb2.html 596 2005-09-11 23:19:49Z isely $
Mike Isely <isely at pobox dot com>
The home location for this page is here.
If you have any suggestions for improving either this web page or
the driver itself, please drop me a message.
Contents
Contacting People / Discussion List
Background
Download
Setup
Usage
Interactions with other drivers
FAQ
Utilities
Bugs
Change History
If you wish to contact me, my e-mail address is spelled out at the
top of this page.
There is also a pvrusb2 e-mail discussion list, hosted here at this
site. This is a mailman-operated list, so you can subscribe,
unsubscribe, access your subscription, scan archives, etc via the web.
(You can also initiate a subscription by sending a message to
<pvrusb2-subscribe at isely dot net>.) Any pvrusb2 relevant
topic there is fair game. Posting to the pvrusb2 list is limited to
just subscribers, but I encourage you to subscribe to the list.
The main web page for the discussion list can be found here.
This driver is intended for the Hauppauge WinTV
PVR USB 2.0, which is a USB 2.0 hosted TV Tuner. Examples
for sale can be found at pricegrabber.
This driver is very much a work in progress. Its history started
with the reverse-engineering effort by Björn Danielsson whose web
page can be found here. From
there Aurelien Alleaume began an effort to create a video4linux
compatible driver. His web page about this driver can be found here.
Unfortunately it seems that Aurelien has stopped working on this
driver. Repeated attempts to contact him over several months have not
been successful. Thus I have for now taken Aurelien's latest snapshot
and begun making changes. This page describes those efforts.
If you have trouble getting the driver to work, please read through
this page again - there are a lot of details here and it's easy to
miss something. Also, I've written a short FAQ covering common situations that people
have found themselves in. If none of that helps, send me a message -
it's entirely possible that you might have encountered something new
and thus I want to hear about it so I can address the problem for
everyone...
Note that the links below only work when viewing this web page at
its home location.
Latest driver snapshot:
pvrusb2-mci-20050911.tar.bz2
Older snapshots (version format is yyyymmdd):
pvrusb2-mci-20050828.tar.bz2
pvrusb2-mci-20050824.tar.bz2
pvrusb2-mci-20050804.tar.bz2
pvrusb2-mci-20050722.tar.bz2
pvrusb2-mci-20050717.tar.bz2
pvrusb2-mci-20050716.tar.bz2
pvrusb2-mci-20050626.tar.bz2
pvrusb2-mci-20050620.tar.bz2
pvrusb2-mci-20050619.tar.bz2
pvrusb2-mci-20050605.tar.bz2
pvrusb2-mci-20050527.tar.bz2
pvrusb2-mci-20050520.tar.bz2
pvrusb2-mci-20050516.tar.bz2
pvrusb2-mci-20050515.tar.bz2
pvrusb2-mci-20050505.tar.bz2
pvrusb2-mci-20050430.tar.bz2
pvrusb2-mci-20050427.tar.bz2
pvrusb2-mci-20050423.tar.bz2
pvrusb2-mci-20050421.tar.bz2
pvrusb2-mci-20050313.tar.bz2
pvrusb2-mci-20050227.tar.bz2
Drop me a message (address at top of page) and I'll add you to a
notification list for driver updates.
Prerequisites
This driver only works under Linux 2.6.x. I have not made any
attempt to even try it in 2.4.x and I know there are environmental
differences which likely prevent it from running or even loading.
The WinTV-PVR-USB-2.0 tuner is a device containing an
8051 microcontroller and another programmable part (either the FPGA or
the cx23416 mpeg2 encoder, not exactly sure), both of which must be
loaded with vendor firmware before the driver will run. That firmware
is not included here; you must extract it from the Windows
driver package that came with your device and then place that firmware
in a location where the hotplug system can find it. See the next
section about firmware extraction for more information.
The main driver module (pvrusb2.ko) specifically depends
on several other kernel modules in order to function correctly. These
are tveeprom.ko, tuner.ko, msp3400.ko, and
saa7115.ko. All except saa7115.ko can be built as
part of the core v4l kernel implementation, or they can all be found
as part of the ivtv driver.
A snapshot from ivtv of these modules is included in this snapshot and
is built alongside everything else here. However you may elect to use
later (and perhaps improved) versions from elsewhere. More details on
this can be found further down. Regardless of the ultimate source for
these drivers, they must be loaded into the kernel in order for the
pvrusb2 driver to function correctly. If tveeprom.ko is not
present, then pvrusb2.ko will fail to load (and probably complain
about a symbol tveeprom_hauppauge_analog being undefined).
But the other modules are all bound late into the driver via the I2C
abstraction layer so their absence will be harder to figure out.
This driver has been tested against 2.6.10-ac12 and 2.6.11.7 with
the "-3" v4l release applied against it. It has also been
successfully tested against stock 2.6.11.10, 2.6.12.3, and 2.6.13-rc6
(using the kernel v4l-provided chip drivers or pvrusb2-supplied chip
drivers). Probably you will need something at least this recent.
(Note: The driver didn't start working in 2.6.13-rcX until the
20050824 snapshot.)
Note: If your driver build fails with a complaint about
being unable to find media/tveeprom.h, then your
kernel sources are probably too old.
Firmware extraction
There are a couple programs in the util subdirectory of
this distribution that can perform the correct extraction of needed
firmware data. Full information on firmware extraction can be found
on the separate utilities page, but
here's a really quick recipe:
- Run the contributed script fwfind.sh.
If the above doesn't work, here a "less" quick recipe to
follow:
- chdir util (Change directory to the util
subdirectory.)
- mkdir win_driver
- chdir win_driver
- unzip driver_package.EXE
- chdir ..
- ./fwextract.pl
Substitute the name of the driver package you got from Hauppauge
for "driver_package.EXE" which is just a
placeholder above. If you're starting from a CDROM copy of the
drivers, then just copy the driver subdirectory contents into
"win_driver" instead of doing the unzip step above.
You now should see two files in the current directory:
File | Size | Description |
pvrusb2.f1 | 8192 bytes | 8051 program image |
pvrusb2.f2 | 262144 bytes | mpeg2 encoder image |
If that didn't work, then possibly you're dealing with a later
driver version that fwextract.pl doesn't know how to handle yet.
Solving this requires a more complex manual extraction. See here for more info.
Failing all of the above, you can still try to extract the firmware
using previous methods. Information on that can be found on
Björn's web page, mentioned
previously. Note that you may need to rename the firmware file names
in that case (see table above for clues on the correct names).
Installation
The driver sources and build files can be found in the
driver subdirectory of the distribution.
Compile this driver more or less in the usual way one does to build
2.6.x kernel modules outside of the kernel source tree. Said another
way, you need a kernel source tree somewhere nearby, and you need to
run make here with KDIR or KREL variables
set to help make find where you put that source tree. For example:
export KREL=`uname -r`
export KDIR=/lib/modules/$KREL/source
make
If you set neither KDIR nor KREL, then
KREL is assumed to be the output of uname -r and
KDIR is assumed to be /lib/modules/$(KREL)/source
(same as the example above). Since nothing else except the default
KDIR value needs KREL, then you can skip setting
KREL if you set KDIR. This is all explained in the
comments that you can find within the Makefile itself.
Before going on, you did extract and install the 2
required vendor firmware files, right? If not, go back and read the
second paragraph of the Prerequisites section above before continuing
any further.
Once you have the driver compiled, you must copy the the binary
modules into your kernel's module area. The target directory is
typically under /lib/modules/$(KREL). I usually use
/lib/modules/$(KREL)/pvrusb2/ as the destination. Note that
there are multiple modules (*.ko) to copy. The actual driver
is pvrusb2.ko and you must copy that. The other modules as
mentioned earlier function in a support role; copy them as well if you
want to use them. Otherwise, ensure that equivalents are available
through some other means. After everything is copied, run depmod
-a so that the module loader will recognize any needed
dependencies.
NOTE: Some people have instead just run "make
install" to let the build system copy the modules for you. This
worked - up until the 20050527 snapshot. Before that point there was
an explicit rule in the driver's local Makefile that did this.
However I removed this rule in the (perhaps misguided) goal of
simplification and outsourcing of everything to Kbuild. Now if you
type "make install" you'll be running the kernel build
system's "install" target - which will try to install a
kernel not the modules! That of course (hopefully) fails. This
problem has been fixed in the 20050605 snapshot.
A few important notes need to be said here about those
"support" modules before we continue (this comes from
feedback from various people trying out the driver):
- If you are replacing an existing module with one from this driver
snapshot, you need to disable the old version by removing it or
renaming it. For example, if you want to use the tuner.ko
supplied by this driver, check for tuner.ko in
/lib/modules/$(KREL)/kernel/drivers/media/video/ and if it is
there, remove or rename it. Do this check for all the modules. Don't
know where it might be hiding? Then try something similar to this:
find /lib/modules/$(KREL)/ -name tuner.ko -print
If you miss this detail, you may end up loading the wrong module. Do
this before you execute the depmod -a step.
- If you are replacing any modules (updating pvrusb2 or changing one
of the "support" modules as mentioned above) then make sure
you've unloaded the old versions from the kernel before you test. In
other words, do a modprobe -r pvrusb2 (repeat as needed for
the specific support modules being replaced). This is easy to forget
about - hotplug may automatically load things for you but it won't
automatically unload them! If you miss this detail, things may still
work - but you won't be running what you think you're running. I've
gotten several problem reports whose cause was ultimately traced to
this error.
- IMPORTANT: If your pvrusb2 device has a Hauppauge
type 58 tuner in it, you may have to use tveeprom.ko from
this snapshot. If you see something like this in your system log:
tveeprom: tuner = Philips FM1236 MK3 (idx = 58, type = 4)
Then you are using a type 58 tuner. This is a problem for the version
of tveeprom.ko included with the Linux kernel - it doesn't
correctly map that type to a v4l tuner definition. Thus you won't be
able to tune anything and you'll get static. The solution in this
case is to use the tveeprom.ko included in this snapshot (or
tveeprom.ko included in ivtv; they're the same).
You can next execute modprobe pvrusb2 to load the driver.
After this point, lsmod should show pvrusb2, tveeprom,
tuner, msp3400, and saa7115 all present. With hotplug running, this
step is not strictly needed, as hotplug will do the needed module
loading when the device appears in the system.
Plug in your WinTV-PVR-USB-2.0 device and after a few seconds the
driver should be ready to go. Progress can be noticed by watching the
kernel log.
Note that the level of log verbosity is controlled through a global
bit mask variable whose name is debug. This mask is set
initially at compile time from within pvrusb2-main.c, using
defined values found in pvrusb2-debug.h. This variable is
also a module parameter and may be assigned at loading time. Also,
like all other module parameters, the debug mask can be adjusted at
any time via sysfs. Read the file
/sys/module/pvrusb2/parameters/debug to find the current
mask, and echo a new value into that file to adjust the mask.
If the driver isn't loaded when you plug in the device, that's OK
because if you're running hotplug, then the driver should be
automatically found and loaded for you.
Hotplug behavior / recovery
The pvrusb2 driver should be robust enough now that it can survive
about any hardware abuse you can throw at it. There are no known
situations where it should ever generate a kernel oops. You
should be able to plug / unplug the hardware or insert / remove the
device to your devious heart's content and the Linux kernel should
just keep merrily going on its way. (Obviously if you find out
otherwise, please let me know.)
There is one issue however with the device itself. From
experiments I have done, it seems that if the device is in the middle
of transaction with the driver, that unplugging the device at that
instant can leave it in a useless (maybe crashed?) state. The only
recovery is to power cycle the device. I have tried numerous
approaches to implementing automatic recovery in the driver, but there
doesn't seem to be any strategy possible that guarantees recovery.
However I did the next best thing: If the driver detects that the
device might be jammed, it will log a message suggesting that the
device be power cycled. The driver should come through all this just
fine of course.
V4L interface
This driver provides an implementation of the video4linux driver
API. Any v4l application which can handle an mpeg2 stream should in
theory be able to use this driver. (Unfortunately there seem to be
very few v4l apps which can...)
xawtv
One application you can try is xawtv 4.x. Note that
anything before version 4 will definitely not work with this since
earlier versions did not support mpeg2 decoding. Obviously, make sure
you've built xawtv with mpeg2 video and mp3 audio support configured
into it.
The xawtv application seems to have a number of rough edges. I've
been testing with a snapshot from February which has worked well
enough for me, but there are issues. More recent snapshots - as
recent as 20050518-16206 have a bug which completely breaks the
ability to stream mpeg2 video. The maintainer has been contacted and
he's committed a fix to his CVS repository. So hopefully anything
after that point should work a lot better. Here is a list of known
issues to watch out for when trying xawtv:
- Snapshots of xawtv from roughly 20050518 to likely back at least
a month (I've gotten failure reports going back that far) have a fatal
bug that totally prevents mpeg2 streaming from working properly. Use
a later (or far earlier) xawtv snapshot.
- You might have to run xawtv once before scantv (part of xawtv)
will find anything. This might have been a driver bug or an
xawtv bug; I'm not sure. However 20050516 driver snapshot with a
correspondingly recent xawtv snapshot (after patching for the fatal
bug) appears not to have this problem.
- There appears to be another long-standing problem in xawtv where
it will every once in a while issue a read of zero bytes. This seems
to happen within a second of first starting a streaming operation.
When it happens, the driver responds with zero (e.g. "ask for zero
bytes, get zero bytes"), but then xawtv treats the zero response as an
EOF and closes the stream. The outward symptom will be just that it
quits displaying video.
- If you attempt to tune a very weak (almost not there) station, the
pvrusb2 hardware may be unable to render a continuous stream of
frames. This causes the video stream to pause, and if the pause is
long enough, xawtv will give up with a "select timeout". When this
happens, consider trying to tune a stronger station.
mplayer
Another application that works is mplayer. There are two ways to
use mplayer: You can tell mplayer it's dealing with a tv device, or
just pass it /dev/video0 (or whatever the right name is on
your system) as the "file" to play. The first method has
not been well tested, and is suspected to have problems. The second
method however works well. More debugging is needed here with the
first method...
xine
Similar to mplayer, xine is reported to work provided you treat the
device file as just a normal file with mpeg contents. There is a v4l
mode apparently for xine (I haven't tried it), but I've heard that it
is very immature and definitely does not work with this driver when
run in that manner.
MythTV
The MythTV application of
course is the holy grail for this driver. I got sucked into this
whole effort because of this desire. Several people have since tested
this driver against MythTV and are reporting some success.
If want to try MythTV, here are some tips:
- Configure MythTV to treat the pvrusb2 driver as an ivtv type of
device (e.g. PVR-250).
- Disable the use of VBI - that definitely does not work in the
driver, and while missing this detail seems to be non-fatal (just
extra noise in the system log about missing ioctl()
functions), it is probably a good idea to just leave VBI off.
Other V4L info
Please contact me if you find other apps which work, and I'll list
them here.
This v4l implementation should allow for multiple opens. Said
another way, if you have one application reading video from
/dev/video0, it should be possible to have another
application still open /dev/video0 and successfully
manipulate driver controls. Of course, only one application at a time
can stream video. A second attempt at streaming will be greeted with
an I/O error.
Sysfs Interface
There is an additional interface available with this driver. In
parallel with the v4l interface, you can now access all driver
controls via sysfs. Once the device is plugged in and the driver is
loaded, try this:
# cd /sys/class/pvrusb2/sn-XXXX
where XXXX is the serial number of your device (just let
tab-completion do the hard work here since unless you have multiple
tuners there will only be one file there). Now use "ls" and
you'll see a whole bunch of directories all starting with
"ctl_". Here is what my system looks like:
londo:~# cd /sys/class/pvrusb2/sn-6829718/
londo:/sys/class/pvrusb2/sn-6829718# ls
ctl_audio_bitrate ctl_freq_table_value ctl_streaming_enabled
ctl_audio_crc ctl_frequency ctl_streaming_force_suspend
ctl_audio_emphasis ctl_hue ctl_treble
ctl_audio_layer ctl_input ctl_vbr
ctl_audio_mode ctl_interlace ctl_video_average_bitrate
ctl_balance ctl_mute ctl_video_peak_bitrate
ctl_bass ctl_resolution_hor ctl_video_standard
ctl_brightness ctl_resolution_ver ctl_volume
ctl_channel ctl_saturation device
ctl_contrast ctl_signal_present driver
ctl_freq_table_channel ctl_srate
londo:/sys/class/pvrusb2/sn-6829718#
(The device and driver links you see there by the way point off to
other parts of sysfs where the driver's and device's lower level
control files can be found.)
Each ctl_ directory has some subset of these files:
- cur_val - This will contain the current value of the
control. It will be either an enumeration constant or an integer
- enum_val - This will contain the full set of legal
enumeration constants available for this control. It will only be
present if the control is an enumerated type.
- max_val - This will contain the maximum legal value for
this control. It will only be present if the control is an integer
type.
- min_val - This will contain the minimum legal value for
this control. It will only be present if the control is an integer
type.
- name - This will contain the descriptive name of the
control.
You can read any of these files just by cat'ing it out. All are
read-only except for cur_val, most of which can be set by
just writing the new value into it (a few of those controls are
actually completely read-only). The incoming value must be either a
legal enumeration constant (for enumerated controls) or an integer
within the legal range specified by min_val and
max_val in order for the assignment to
"take". Otherwise the program doing the write should get
back an EINVAL error status.
I put together this interface to make it easier to debug the
driver, independent of an application like xawtv. The possibilities
here are obvious. For example, it should be possible open the /dev/
entry into mplayer and then completely control everything else with
this sysfs interface while mplayer is running. One could write a
control program in Perl with this interface...
Please be aware that with this interface one has complete run of
all the driver's controls. There are certainly combinations of
settings which, uh, won't work very well. For example, changing the
capture resolution is not a pathway very well trodden yet. But as I
said, I put this here to make it easier to debug the driver. It was
either this or invent a pile of new ioctl()'s and write a test program
to operate those settings (the ioctl() approach I believe is what ivtv
does).
DVB Interface
I have several interesting thoughts towards also making a DVB
interface concurrently available. This device after all deals in
mpeg2 streams not video frames, so from a purist standpoint it's
probably closer to DVB in behavior than v4l. The internal structure
of the driver now should make this sort of stunt possible, but I need
to do more research before I can determine if it is truly feasible.
In the mean time, there's no DVB interface.
The IR receiver within the device is an I2C part that is understood
by the lircd
software package (0.7 or later). Previously Aurelien's driver
hardcoded something here which made the IR receiver into another
source for /dev/input, but I had stability problems with this
and just decided to rip it out in favor of letting more stable
external software handle this function.
You should do here precisely the same solution as that needed for
ivtv. In other words, grab lircd 0.7 or later, build it, modprobe the
I2C driver into the kernel and when configured with the appropriate
lircd.conf (one is included with the pvrusb2 driver), it should
"just work". The I2C driver should discover the internal
I2C bus made available by the pvrusb2 driver, probe that bus, and
attach itself when it finds the IR receiver chip it will be looking
for.
I have received one report that this in fact does work (I
haven't tested it myself yet).
Frequency Table
There is a frequency table implemented inside this driver. It is
not available for v4l, but it can be used with the sysfs control
interface. You must program it first before using it, but once
programmed it becomes possible to change the channel just by, well,
writing the new channel number to the driver. The table size is
currently limited to channel numbers 1 through 500 (far in excess of
anything anyone should need), and the channel ids must be integers not
something cute like station call letters.
Note: You do not need to program this frequency
table or otherwise even touch it when using this driver with any v4l
application. This table is not even visible in the v4l API; it is
only present here to make it easier to debug the driver using
sysfs.
The frequency table must be programmed a slot at a time. You do
this by first selecting the slot's id (a.k.a. the channel number) into
the freq_table_channel variable through sysfs. Once
selected, you can read / write the frequency (in Hz) for that slot
using the freq_table_value variable through sysfs. Repeat
this process for all channels to be programmed. Yes, this is just
begging for a shell script to do the dirty work. Anyone care
to write one?
Once you've programmed the desired slots in the table, just
"change the channel" by writing the desired channel number
to the channel variable through sysfs. That's it.
The frequency can still be set as before by writing the actual
frequency to the frequency variable. If that is done, then
the channel will be implicitly set to zero, which means
"none". Thus the channel and frequency variables at all
times stay consistent with each other and there's no loss of flexible
or any implied confusion.
The frequency variable can of course be read back at any time to
see what the actual frequency is, regardless of whether it was set
directly or implied by a channel setting. And of course the channel
variable can be read back at any time to find out what the current
channel is or if it is not being used due to the frequency being
directly set (in which case the value read back will be zero).
Why do this? Well it was dirt-cheap easy to implement, and it does
help with debugging, though in a minor way. Besides it's cool to do.
OK, OK. Enough playing and back to the real rework...
Aurelien's version of this driver implemented all chip-level
functionality directly inside the pvrusb2 source code. All of these
chips are accessed via an internal I2C bus, and it so happens that the
Linux kernel has a fairly decent I2C abstraction layer in it. In
addition, there already exist more complete and better-tested chip
level drivers out there that use this I2C abstraction layer. So the
first thing I did was to implement a proper I2C adapter driver within
pvrusb2, and then (similar to the IR remote description earlier) I
proceeded to rip out the redundant code in favor of using the better
external implementations. The external chip-level drivers currently
being used are:
- tuner.ko - This is a generic tuner driver; it knows how
to handle many different tuner variations. It can be found in v4l
within the kernel sources and within the ivtv driver
package. (Problems with new tuner types in various devices and the
desire not to clone more code is what started me down this
path...)
- tveeprom.ko - This is a module which knows how to
interpret the contents of a Hauppauge EEPROM. We use it to discover
the installed tuner type, the supported video standard(s), and the
serial number of the device. This module can also be found both within
v4l and the ivtv driver package (however the v4l implementation
doesn't correctly map type 58 tuners, which can be found in some
pvrusb2 devices).
- msp3400.ko - This is a driver for the msp34xx series of
audio processors. The PVR USB2 tuner I've been playing
with has an msp4418G inside it (which is apparently backwards
compatible with the msp34xx series). This module can be found both in
v4l and ivtv.
- saa7115.ko - This is a driver for the saa7115 video
processor chip. Unfortunately this driver does not seem (yet) to exist
in v4l, but it does exist in ivtv.
This driver snapshot includes copies of all of the above listed
chip-level drivers, however they are just exact copies from version
0.3.7i of the ivtv driver.
They are merely included here for convenience. It is my intention to
leave the corresponding source files unchanged, in order to better
track the upstream source.
All of the above chip-level driver except
saa7115.ko are also available as part of the core v4l
distribution. They are known to work, but the v4l implementation of
tveeprom.ko does not handle type 58 tuners (look back to the
Installation section of these notes for more information on this).
Playing well with ivtv
Even though the PVR USB2 is a USB device while
everything else driven by ivtv is a PCI device, there really is more
than a passing resemblance among them. As such it's no coincidence
that all the listed chip-level drivers above also happen to come from
ivtv. (In fact, the same NDA-protected, no-datasheet-available cx23416
mpeg2 encoder - which is the heart of ivtv - is also used in this
device.) If you have / need to also use ivtv, it should be possible
for this driver to coexist with it. You can discard all the chip-level
drivers list earlier from this package in favor of the versions from
ivtv (which likely will have additional fixes).
Playing well with xbox
The X-box has an internal I2C bus, and the code that was hacked
together for it makes the assumption that it is the only I2C bus that
can possibly exist on an xbox. That assumption becomes false when a
PVR USB2 device is introduced, unfortunately. The problem here is that
the I2C driver code for the xbox tries to attach to the PVR USB2's I2C
bus, causing dangling pointers in the xbox driver code and chaos
ensues. If you have an xbox, I have a patch for the xbox I2C driver
code that makes it play nicer (it's still a horrible hack though). I
will try to get that code submitted back to the xbox author(s). In the
mean time, contact me for the patch.
Playing well in v4l
The v4l implementation is still undergoing development - and
recently there has been some maintainership turmoil. There's a risk
that a later snapshot may cause this driver to break. Indeed, it is
already known that you need at least 2.6.10-3 of the v4l kernel patch
for the driver to even work. There isn't anything really that can be
done here yet about this problem, except to warn the reader to watch
out for trouble.
I've written up a short list of common mis-steps and solutions
encountered by people trying the driver. If you have any suggestions
for things to add here, please let me know. Hopefully you can find
your situation described here: pvrusb2-faq.html
The driver package now includes a few utilities related to
operation of this device - including a new means for extracting driver
firmware. There is a separate page describing all of this: pvrusb2-utils.html
This is a fairly immature driver. There are a number of important
issues. However since they change with each driver snapshot,
please see the driver/README file included in the snapshot
sources for a list issues known when the release was made.
Here is a list of issues discovered since the last release:
- Audio input for composite-in and svideo-in appears not to be
working. Very likely that the driver is operating the wrong control
for volume in the msp3400.ko module. I just need to chase this
down.
pvrusb2-mci-20050911
- Fixed kernel oops when cable was yanked while video was streaming.
The driver internally doesn't tear everything down inside the USB
core's disconnect hook due to the need to wait for other references
(e.g. open file handles) to go away first. When it finally does tear
things down, it was also disconnecting at that time its
association(s) with the USB core. But that's too late, and doing that
can result in dangling pointers being dereferenced from within the
core. This is not a USB problem; the root cause is that the driver
must remove itself from the USB core before the disconnect hook
returns. Now the driver disassociates from USB immediately on device
disconnect, while still delaying its own internal tear-down until
other references go away, as usual.
- Fixed memory leak in pvrusb2-io.c - buffer control structures were
never being freed (happens only when streaming is stopped). Also
cleaned up a potential dangling pointer (which actually should never
have been touched anyway, but I'm paranoid).
- Updated misc/lircd.conf to match the "Hauppauge grey"
remote more typically included with the PVR USB2 hardware. (Some
corresponding tweaks to misc/lircrc.) This is a conf file I've been
using with a PVR-250 (it's the same remote).
- Added sanity / debug code to buffer management, in an attempt to
trap any possibly corrupted buffer control structures. This is turned
off by default right now. To enable, turn on the SANITY_CHECK_BUFFERS
symbol pvrusb2-io.c. When on, there will be some additional noise
during stream start / stop but otherwise no additional log messages
will appear unless a bad buffer has been spotted.
pvrusb2-mci-20050828
- Got rid of dead pvrusb2-data.h. Cleaned up pvrusb2.h (removed
remaining old junk which had long since stopped being used).
- Implemented unit number concept which is used to uniquely name
driver / device instances. Other parts of the driver will use the
unit number to select per-unit module options (like tuner override,
minor device number, etc).
- Implemented tuner=x module option to allow overriding of tuner
type. This is an array, so the tuner type can be individually
overridden for each pvrusb2 unit you might have (yeah, as if
that will ever actually be tested...
- Changed video_nr module option from a scalar to an array. Similar
to the tuner option, this can be specified on a per-instance
basis.
- The v4l minor device number is published now in sysfs as
v4l_minor_number.
- The unit number is published now in sysfs as unit_number.
pvrusb2-mci-20050824
- Updated ivtv-sourced modules to those from ivtv 0.3.7i.
- Fixed pvrusb2-tuner.c so that driver works under 2.6.13 (verified
with 2.6.13-rc6).
pvrusb2-mci-20050804
- Fixed longstanding and nasty bug which prevented tuning any
frequency below 76.00MHz (roughly below US broadcast channel 5). It's
amazing that something like this went undetected for so long. Cause:
brain-fart while reading the FM1236 datasheet back in February (read
off the floor frequency for FM instead of VHF). Thanks go to a
pvrusb2 user for tracking this one down.
- Minor clarifications / updates to web page info based on feedback
from many others.
pvrusb2-mci-20050722
- New firmware signature added to fwextract.pl (corresponding to
driver 2.5.22329 found on a CDROM distribution).
- Modified fwextract.pl to exit with a non-zero status if extraction
is not completely successful.
- Contributed script fwfind.sh added to utilities and described.
Firmware extraction procedure reworked to include fwfind.sh, and extra
information added about where to place firmware files after
extraction.
- Adjusted log messages slightly which are related to firmware
upload. We don't want to mislead the user if the upload had not
succeeded.
pvrusb2-mci-20050717
- Various tweaks / improvements to firmware extraction script.
- Teach extraction script how to pull firmware from 3 additional
Hauppauge driver releases.
pvrusb2-mci-20050716
- New firmware extraction procedure, along with new tools and a
driver feature to support it.
- Moved all files into Subversion. Rearranged distribution layout;
there are now separate util, doc, and driver subdirectories.
Utilities now included as part of driver snapshot.
- Added pvrusb2-utils.html web page, which describes detailed
firmware extraction info, along with how to use the decompiler.
pvrusb2-mci-20050626
- Detect when encoder stops responding to commands and return an
error code to higher level code in the driver. We don't know why this
can happen, but at least now we can detect when it happens...
- Rewrote low level request / response logic
(pvr2_send_request()). New version can issue simultaneous
write / read pairs, and eliminates some of the hacks that previously
existed (and from what I can tell over 5 months of working on this
driver that these hacks were completely unneeded).
- Defined encoder firmware reloading as a callable configuration
step.
- Reworked device configuration function
(pvr2_hdw_subsys_bit_chg_no_lock()) to react to failures and
retry appropriate pieces as needed. Specifically, we can recover from
a hung encoder now by causing an encoder firmware reload (and
reconfiguration of all affected pieces).
- Reworked all code involved in encoder register read/write to use
little-endian ordering instead of big-endian. (This wasn't a bug, but
now we match what ivtv is doing which makes it easier to analyze other
issues.)
- Fixed error in pvrusb2-encoder.c which caused too many words to be
read back from encoder (was 32, should have been 16).
- Always send 16 words to the encoder for every request instead of 4
plus the number of arguments.
- Fixed bug in pvrusb2-encoder.c which caused it to misbehave if more
than 8 words were being sent to the encoder.
- Implemented "reset firmware" command in debug interface,
which can be used to force an encoder firmware reload.
- Added lots of new stuff to protocol-info.txt, all
regarding operation of the encoder chip. (See a running theme here
yet for this snapshot?...)
- Implemented functions in pvrusb2-hdw-low.c for direct manipulation
of GPIO signals.
- Discovered that bit position d7 of the GPIO direction(?) register
appears to control the LED. Confirmed that flipping this bit does not
seem to impact video streaming, so now we ensure that the LED is on
when the encoder is running and off when not the encoder is stopped.
(We really need to understand these GPIO bits a lot better.)
pvrusb2-mci-20050620
- After auditing the encoder configuration command sequence against
the same sequence snooped from the Windows driver, one unexplained
difference was found. Changing this driver to match the Windows
driver seems to have cleared up video corruption problems. Because of
this, streaming control now toggles the USB link again and also now
reconfigures the encoder when the encoder is started / stopped.
- Additional debug abilities added to help debug driver lockups.
pvrusb2-mci-20050619
- Updated ivtv-sourced modules to those from ivtv 0.3.6n.
- All pointers are formatted with %p now instead of my usual pattern
of hacking, I mean uh casting the value into an unsigned int and
printing with %x. Using %p is more portable across machine
architectures, and the previous method caused a flood of warnings when
compiled on AMD64. A few related AMD64 compilation warning were also
fixed.
- Internal state handling code has been reworked so that we can
track when we need to configure various parts ("subsystems") of the
device and know what parts of the stream pipeline are running. This
is all in an effort to better implement stream start / stop, which so
far has been very unstable. It's now possible to easily configure
what gets manipulated when streaming is started and stopped.
- A new command parsing debug interface has been implemented,
currently accessible through the sysfs interface under the name
debugifc. cat'ing out this file will dump a human-readable
report of the driver's internal state (which subsystems are running or
configured, whether streaming is in progress, speed of USB link).
Commands can be echoed into it to adjust driver operation and / or
(attempt to) recover from strange errors. This is not meant for
routine access; it is purely a debugging aid.
- Identified the true purpose of a number of previously mysterious
commands sent over USB and abstracted them to separate functions.
Numerous ways to reset internal device state have been uncovered, and
a means for querying the device's view of the link speed is available
now (see ctl_usb_speed in the sysfs interface). The speed
query function is also a useful way to ping the device - it's a single
command & response requiring virtually nothing else in order to work.
So if you can read the USB speed value, then you can be assured that
communication is working between the device and the driver.
- Reverse-engineered the actual underlying encoder communication
protocol and reworked pvrusb2-encoder.c to expose and exploit that.
This makes our operation of the encoder somewhat more honest than
before (unfortunately this work didn't actually fix any known
problems). Interestingly enough, our communication with the encoder
bears a spooky resemblence to the mailbox communication used within
the ivtv driver. Coincidence? I think not...
- Adjusted driver's streaming start / stop function to no longer
shut down the USB link portion of the video streaming pipeline when
streaming is stopped. Numerous experiments seem to show that leaving
the USB link running at all times seems to avoid the rampant
accumulating video corruption problems that I and many others have
observed (at least in the tests I've done with mplayer).
- Added a text file to the driver sources protocol-info.txt
which documents the control protocol that the device expects. This is
of course far from complete, but I have spent far too long trying to
fill in this picture already and it doesn't do any good if the
knowledge is kept only in my head.
pvrusb2-mci-20050605
- Ensured that "make install" does the right thing (this bug had
been introduced in the 20050527 snapshot).
- Fixed a severe bug in the frequency table handling that essentially
made the frequency table useless. This problem had been introduced a
few snapshots back.
- Combed through pvrusb2-encoder.c and symbolically name all of the
commands being sent to the encoder chip. The information source for
this was the ivtv driver; this is a minor steps towards trying to
understand how the encoder works. No functional change here, not yet
at least.
- Cleaned up and regularized copyright attributions and CVS Id
keywords everywhere.
- Tweaked sysfs implementation a bit - if a control file is written
with multiple value now, each value will be set in rapid sequence.
This is a mostly useless feature, but it is good for debugging
scenarios where one wants to rapidly toggle something on / off (like
chasing the streaming startup problem).
pvrusb2-mci-20050527
- Eliminated race condition that was possible during a disconnect or
permanent failure where somebody might be attempting a control
transaction at the same time. The logic which does the disconnect or
marks the permanent failure now takes the same semaphore as the logic
which performs transactions. This is needed because I2C chip drivers
might try to operate autonomously with respect to this driver.
- Cleaned up build process; we no longer have to specify KREL.
Kbuild-specific stuff is now moved to its own file. The resulting
Makefile is significantly shorter. Added lots of comments.
pvrusb2-mci-20050520
- Turned on a debug log message ("ZERO Request? Returning
zero.") that will report when somebody attempts a read of length
zero. The driver responds to such a read by returning zero, but
unfortunately xawtv then treats that as an EOF and closes the channel.
This is an xawtv problem; the log statement is there so it's possible
to detect when it happens.
- Fixed a bunch of brain-damage involving the file permissions mask
for all the module parameters. Now all the permissions are
reasonable.
- Seriously improved error handling in the streaming logic. If the
cable is yanked while streaming video, the device will now cause the
stream to fail gracefully. This should cause the app to close the
channel, after which point the driver should deactivate itself.
- Found and fixed a nasty race condition that can happen if the
cable is yanked while it is being initialized.
- Implemented a set of informational summary log messages that print
at the end of device initialization which explain what state the
device is probably in. If it detects that the device is jammed, a
message will print suggesting that the device be power-cycled. It
will also print a message if it is allowed to reload the firmware and
decide to do so. If initialization is successful, a message to that
affect will also be printed. If initialization is incomplete due to a
firmware reload, an advisory message will print that a reconnect is to
be expected.
- Implemented experimental code to force a new firmware download if
the device fails to initialize properly. Unfortunately this doesn't
seem to help. This is controlled by the "procreload" module
parameter. For now I've left it off by default.
- Perform a device reset during set up (after primary firmware
download). Doing this allows recovery from some inconsistent
device states. This step is controlled by the
"initusbreset" module parameter. It is on by default.
- Fix call to I2C adapter tear-down function so that it is called
every time, not just when the device has been successfully
initialized. Why? Because we might have initialized the adapter
anyway; the overall initialization could have failed after adapter
initialization, thus without this fix we could leave the kernel's I2C
core with dangling pointers - which would eventually end badly with a
kernel oops.
pvrusb2-mci-20050516
- Fix the driver version info to match the snapshot. D'oh!!
pvrusb2-mci-20050515
- The old streaming logic has been completely ripped out and
replaced. This is by far the biggest change for this snapshot.
Previously logic was in pvrusb2-buffer.c and
pvrusb2-stream.c. New logic is pvrusb2-io.[ch] and
pvrusb2-ioread.[ch]. The new logic currently only implements
the "read" method, however even though the old logic did all
three v4l methods, it appears that the other two methods were broken
there anyway. The new streaming logic has two well-defined internal
shearing layers. The lowest level handles all USB buffering, and the
middle level translates that into stream data for the read()
system call. Other middle levels can later be implemented alongside
for other forms of I/O as appropriate.
- The entire v4l API implementation has now been isolated and
stuffed into a single place, pvrusb2-v4l2.c. The old
streaming logic had been entangled with v4l, so this step could not
happen until that the new streaming logic had been implemented
first.
- Debug logging has been further cleaned up. High-bandwidth log
messages are isolated behind specific debug mask bits and their
formatting has been regularized so that a post-processing script may
scrape useful data out of the kernel log. There's enough information
available now to theoretically reconstruct blow-by-blow events in the
streaming path. (Obviously that level of logging should normally
remain off.)
- Pulled in the following modules from ivtv: tuner.ko,
msp3400.ko, and tveeprom.ko. Requiring people to
hunt these down from other sources seemed to be too much trouble. The
final straw was the type 58 tuner problem in v4l. However that
doesn't mean I've forked the code. It should still be possible to
continue using other versions. The copies in this driver snapshot are
exact copies from ivtv and I intend to keep it that way. I
hope.
- Isolated usage struct tveeprom; this is an internal
structure from tveeprom.ko which may be subject to thrashing
and changes. It is now only visible inside of
pvrusb2-eeprom.c.
- Defined more controls that can be accessed through sysfs. Signal
presence (ctl_signal_present) can be queried (but obviously
not set), the streaming state (ctl_streaming_enabled) can be
queried (but not set), and there's a control present
(ctl_streaming_force_suspend) that can be used to explicitly,
temporarily suspend streaming (for debugging).
- We now tell tuner.ko about which video standard we are
using. Most of the time this probably isn't going to matter much
since it seems that the tuner type also implies the standard. But the
module has the ability to be told and there probably are some cases
where it matters, so we're telling it now.
- Do a better job of logging which video standards have been
detected from the eeprom. This should make things easier to
understand for multi-standard tuners where we happen to
"pick" the wrong choice. (Picking the wrong standard is no
big deal since it is easily corrected through sysfs and a v4l app
should probably be setting the choice of standard anyway.)
pvrusb2-mci-20050505
- The video standard is now initialized to a value that is
determined by what has been read from the Hauppauge eeprom.
Previously it had been default-initialized to NTSC.
- A frequency table has been implemented in the driver and made
available through sysfs.
pvrusb2-mci-20050430
- Fixed bug in video standard enumeration. This problem was
introduced in the previous snapshot due to the v4l driver abstraction
layer cleanup.
- New sysfs control interface. This is the big change here for this
snapshot. It's possible now to operate all driver controls just by
examining / changing files under /sys/class/pvrusb2/sn-XXXX (XXXX is
the device's serial number).
- More junk gutted out of pvrusb2-main.c.
pvrusb2-mci-20050427
- New driver abstraction layer implemented, the definition for which
can be found in pvrusb2-base.h. This is an attempt to isolate code
which manages the driver as a whole, and also provides a shearing
layer where we can plug in additional control interfaces. The
existing v4l code is hacked up to work through this abstraction layer
as just "another interface". The previously-mentioned
"shell" remnant struct in pvrusb2.h (see further back in the
history) is now completely removed, in favor of this new layer.
- First attempt made at trying to understand what is going on in
pvrusb2-encoder.c (the part which handles the mpeg2 encoder hardware).
As part of this, a large amount of debug code is added. Bugs fixed
here; these problems were collateral damage from all the other
rework.
- Implemented a kernel thread for the driver. Each driver instance
gets a kernel thread now, to handle whatever background tasks are
needed which otherwise would block the caller.
- All major device initialization moved to the kernel thread. All
firmware loading happens here now instead of being inline with the USB
probe function. This seems to have noticably sped up driver
initialization. And hotplug auto-loading of the driver works now.
Yay!
pvrusb2-mci-20050423
- Fixed problem with video standard handling and audio processing.
We need to tell msp3400.ko what video standard is in use, because that
driver uses it in determining how to configure the audio processor.
Previously this was working "by accident", but a recent
change to msp3400.ko exposed this bug in the pvrusb2 driver
- Brought in new saa7115.c from ivtv. The only real change is a
largely cosmetic fix required due to a change in the kernel's I2C
subsystem. Unfortunately lots of lines changed anyway because it
appears that the ivtv driver author decided to fix all the tabbing /
spacing in the driver at this time.
pvrusb2-mci-20050421
- Driver author info updated.
- Most of the debug code has been scrubbed and cleaned up. It's now
possible to selectively enable different kinds of debugging printk()'s
via the debug module parameter which is now a bit mask. Possible bit
mask choices are defined in pvrusb2-debug.h
- The first really big change: New hardware abstraction
layer implemented, core interface is defined pvrusb2-hdw.h.
Implementation is spread across other new modules:
pvrusb2-hdw-internal.h, pvrusb2-hdw.c, pvrusb2-hdw-low.c. All other
modules which touch the hardware except the streaming code are
restructured to now hide behind this interface. All driver controls
are abstracted as part of this, with a unified interface laid out in
pvrusb2-hdw.h. The driver's ioctl() (where much of the v4l part of
this puzzle exists) is reworked to operate through this interface.
The master control structure in pvrusb2.h is gutted down to a shell,
and fitted with an instance of the new layer. The driver's global
state variable is history now, no longer needed.
- Moved all code which handles firmware loading into its own module:
pvrusb2-firmware.c.
- New streaming code written, which can be found in pvrusb2-io.c,
pvrusb2-ioread.c, and pvrusb2-iommap.c. All of it compiles, but none
of it is being put to use it. This big shakeup must wait until
later...
- Beginnings of a new driver abstraction layer put together but not
put in use yet.
pvrusb2-mci-20050313
- Removed all code for handling the video capture chip, and replaced
it with far simpler code that merely calls out to saa7115.ko, a module
available from the ivtv driver (not currently in v4l).
- Imported CVS snapshots of ivtv driver, and copied saa7115.c from
there into this driver. What is in this driver is an exact
copy of what came from ivtv - no local changes. I intend to keep it
exact. Several header files were also brought over and one was hacked
up in order to make it possible for saa7115.c to compile cleanly
outside of ivtv.
- More I2C low level fixes.
- Minor cleanup in driver's ioctl() function.
pvrusb2-mci-20050311
- Additional eeprom handling cleanup.
- More I2C adapter driver cleanup / fixes.
- Removed all code for handling audio, and replaced it with far
simpler code that merely calls out to msp3400.ko which is already in
v4l.
- Reworked existing pvrusb2-saa7115.c code (video digitizer) to use
new I2C adapter driver
- Additional tuner handling cleanup.
- Control handling cleanup in the driver's ioctl() implementation.
- Added code to module initialization such that other needed I2C
based modules (e.g. tuner.ko) are explicitly loaded at the same time,
if not already present.
pvrusb2-mci-20050227
- New module: pvrusb2-i2c.c, containing low level logic for
appropriate interfacing with kernel's I2C layer.
- Removed IR handling logic, killing an instability problem when the
driver is removed.
- Removed all code for handling the Hauppauge eeprom, and replaced it
with far simpler code that merely calls out to tveeprom.ko which is
already in v4l.
- Removed all tuner handling code (scattered around in various
places), and replaced it with far simpler code that merely passes off
the actual work to tuner.ko which is already in v4l.
pvrusb2-mci-20050217
- Fixed USB run-time warning: changed call to usb_unlink_urb() to
usb_kill_urb().
- Defined two new tuner types.
- Minor tuner handling tweak.
- Renamed video standard string names and video input string names
to better match expectations of xawtv.
(Aurelien's 07112004 snapshot starting point)
Feel free to e-mail me (address at the top of this page) if you
have any questions or just want to say hello...
Mike Isely