$Id: usage.html 1258 2006-07-02 21:16:15Z isely $
Mike Isely <isely at pobox dot com>
You can find the main driver page on the web at http://www.isely.net/pvrusb2/pvrusb2.html.
This page describes how to use the driver, including module options, interface control, and information about driver-specific effects with certain apps.
Contents
Driver logging / parameters
Hotplug behavior / recovery
V4L apps
Sysfs Interface
DVB Interface
IR handling
Frequency Table
Playing well with others
The level of log verbosity within the pvrusb2 driver is controlled through a global bit mask variable whose name is debug. This mask is set initially at compile time; you might want to change it. Set / clear bits in this mask to enable / disable various forms of logging to the kernel. The default value of this bit mask is fairly noisy however it only enables types of output that won't stuff your log when streaming.
The debug bit mask definitions are all contained in the driver source inside pvrusb2-debug.h. The bits are generally organized in order of increasing noise level. There are three ways to adjust these bits:
There are a number of module parameters you may specify to the pvrusb2 module when it is loaded; none however are strictly needed. Note that these parameters are also all visible at run-time by examining the directory /sys/module/pvrusb2/parameters/. Most parameters there are read-only (because they only are looked at during initialization). However as pointed out above the debug parameter in particular can be changed at any time simply by echoing a new value into its file name within that directory.
Note that unless otherwise pointed out, these parameters are global to all instances of the driver (i.e. if you have two PVR USB2 devices plugged in the effect is the same on both corresponding driver instances). The following parameters exist:
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 driver (or just about any support module) 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 potential 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. (Update 4-Jan-2006: It has been a very long time since I've seen this problem repeat; it might have been something else long since fixed in the driver.)
This driver provides an implementation of the video4linux version 2 and version 1 driver APIs. 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...)
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.
Note that when you compile xawtv, make sure that you've configured it for mpeg2 video decoding and mp3 audio decoding. The app's configuration process tries to detect what libraries you have installed on your system, and if it doesn't find what it is looking for then it will silently disable parts of itself, i.e. no mpeg2 decoding. Inspect the configuration output and make sure it looks OK...
The xawtv application seems to have a number of rough edges. Best advice is to make sure you're running a recent snapshot. Some specific details:
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 does not work. The second method (pass the device name as a plain file argument) however works well. The reason why you just can't tell mplayer it is talking to a tv device is because once you do that then mplayer goes "dumb" and decides to only attempt streaming of uncompressed video (i.e. no mpeg2 streaming), which of course won't work since our hardware here produces mpeg2...
I've seen floating around the net a variant of mplayer which has been adjusted to work with the ivtv driver. I imagine that the adjustment is to cause mplayer to still attempt mpeg2 streaming when in tv mode. If that is the case, then that version should work here. However I have never gotten around to trying it.
Several people have encountered problems reading pvrusb2 output with mplayer if the the avisynth.dll codec is installed in mplayer. This can be found in /usr/lib/win32/avisynth.dll. I can't profess to know what that codec might provide (or even if it is a codec) since I don't use it. However for those who have encountered problems in mplayer with this driver, removing this codec solves the problem.
Similar to mplayer, xine and vlc are 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. I've been told that this these example invocations should work:
xine - < /dev/video vlc - < /dev/video
It is possible to get Kaffeine to work with this driver (streaming only?) using the following MRL:
fifo:/dev/video#demux:mpeg
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 success.
If want to try MythTV, here are some tips:
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.
There is an additional interface available with this driver. In parallel with the v4l interface, you can access all driver controls via sysfs. Once the device is plugged in and the driver is loaded, try this:
# cd /sys/class/pvrusb2/sn-XXXXXXX
where XXXXXXX is the serial number of your device (just let tab-completion do the hard work here or use "*" since unless you have multiple tuners there will only be one file there anyway). 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_resolution_ver ctl_audio_crc ctl_saturation ctl_audio_emphasis ctl_signal_present ctl_audio_layer ctl_srate ctl_audio_mode ctl_streaming_enabled ctl_balance ctl_treble ctl_bass ctl_usb_speed ctl_brightness ctl_vbr ctl_channel ctl_video_average_bitrate ctl_contrast ctl_video_peak_bitrate ctl_debug_subsys_mask ctl_video_standard ctl_debug_subsys_stream_mask ctl_video_standard_mask_active ctl_freq_table_channel ctl_video_standard_mask_available ctl_freq_table_value ctl_volume ctl_frequency debugcmd ctl_hue debuginfo ctl_input device ctl_interlace uevent ctl_mute unit_number ctl_resolution_hor v4l_minor_number londo:/sys/class/pvrusb2/sn-6829718#
(The device and driver links you see there by the way are standard things which point off to other parts of sysfs where the driver's and device's lower level control files can be found.)
Note: As said above, the "XXXXXXX" part of the path is the device's serial number. It is possible that the driver might not be able to retrieve a serial number from the device (if there were problems reading the device's PROM). In this situation, the sysfs implementation here will substitute the device's unit id using the form "unit-X" (instead of "sn-XXXXXXX") where "X" is the letter for the unit assigned to the device instance.
Each ctl_ directory has some subset of these files:
You can read any of these files just by cat'ing it out. All are read-only except for cur_val and custom_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 an integer within the legal range specified by min_val and max_val, a legal enumeration constant (for enumerated controls), a true / false or yes / no literal (for boolean controls), or a bit mask assignment (for bit mask controls) in order for the assignment to "take". Otherwise the program doing the write should get back an EINVAL or ERANGE error status.
Bit mask controls have a somewhat more complex expected format in order to support the setting and clearing of individual bits within the mask. The values you write in are expected to be a set of whitespace-seprated bit names. If just the names are used then the entire mask is set to just those bits. If however each bit name is prefixed with a "+" or a "-", then just those corresponding bits will be set or cleared (respectively) without affecting the other bits in the mask.
The contents of the custom_val file is determined entirely by the specific control itself; there is no defined format unlike with cur_val. This will only appear if the control has a way to format its own value. Currently it is only used to show video standard mask values, where this custom form adheres closer to normal conventions for expressing multiple standards. If the control in question is writable, then this may be writable as well (in which case the control will parse the symbolic value itself to determine the desired underlying internal value). If none of this makes sense to you, then you can just safely ignore the existence of the custom_val file.
I initially put together this interface to make it easier to debug the driver, independent of an application like xawtv. But the possibilities here are obvious. For example, it is possible open the /dev/ entry into mplayer and then completely control everything else with this sysfs interface while mplayer is running. (I routinely test the driver this way.) One could write a shell script control program 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. But as I said, I had initially 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 is what ivtv does).
In the driver source tree, there is a file doc/controls.txt which annotates each of the controls with information about what it is expected to do, what effects may or may not happen, and whether certain settings work or not. I put this together after experimentation with the device. Others may find it handy so I've made the results available.
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 architecture of the driver 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.
NOTE: IR reception currently only works with the model 29xxx series devices. With 24xxx devices, the IR situation is apparently different and so far not understood, unfortunately. So everything described below currently only applies to 29xxx devices.
The IR receiver within the model 29xxx series devices is an I2C part that is already 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.
Making IR reception work is mostly just a case of install lircd and go. It's the same thing you would do to get IR working in 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 appropriate for the PVR USB2's included remote is provided with the standalone pvrusb2 driver), it will "just work". The I2C driver will 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.
Note that if you are a Debian user, there is an lirc-modules-source package which you can in theory just install and build against your kernel tree. I and others have found that package to be broken. It won't compile cleanly. (See here for the current situation with this package.) You're probably better off just using the vanilla version from the lirc web site.
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. Thanks to Per Christian Henden, one example of such a script exists now in the utils subdirectory (see utils.html for more information about this).
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 flexibility 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...
The following is a summary of issues / tips when using this driver alongside other software or in less-typical environments.
Even though the PVR USB2 hardware 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 both happen to share the same chip-level drivers. This is in fact where the chip-level drivers in the ivtv subdirectory of the standalone driver snapshot came from. Even the same cx23416 mpeg2 encoder - which is the heart of ivtv - is also used in the PVR USB2 device. If you have / need to also use ivtv, it should be possible for this driver to coexist with it. Any ivtv-provided chip-level drivers should also work fine with the PVR USB2 driver, thus the two drivers should be able to coexist nicely on the same system.
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). Contact me for the patch.
The v4l system in Linux is undergoing rapid development. This can cause issues for an out-of-tree driver like the pvrusb2 driver. The standalone version of the pvrusb2 driver goes to some length to detect and interoperate correctly with whatever surrounding v4l environment it finds itself operating inside of, however it can be hard to keep up. The in-V4L version of the pvrusb2 driver is less complex in this area since it can always assume exactly what v4l environment in which it is running. If you find you are having problems with the pvrusb2 standalone driver and you suspect v4l incompatibilities as the cause, then contact me or check the mailing list for chatter about such a problem. And of course you can elect to simply update to the latest v4l repository snapshot, with its included in-V4L version of the pvrusb2 driver.