pvrusb2 driver usage information

$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

Driver logging / parameters

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:

ctlchg
(Think ConTroLCHanGe - yeah I stink at creating names.) This enables an optimization in the driver involving update when controls are changed. The default value of zero means that any control change are always propagated to all affected logic. If the value is set to one, then a given control change will only be propagated if the new value is actually different than the previously known value. Enabling this can speed up frequency changes (slightly) for applications that insist on dumping out piles of other redundant control changes at the same time.
debug
This controls logging verbosity. This is a bit mask, though unfortunately you get to specify it as a decimal number (get out your hex / decimal calculator). The bit definitions are in the header pvrusb2-debug.h, and a default value is set near the front of pvrusb2-main.c. You can change this mask at any time via sysfs (the directory just mentioned above); the effect will be immediate.
i2cscan
This parameter when set to non-zero enables a full scan of the internal I2C bus as part of the initialization of the device. The results of the scan will go to the kernel log; driver operation itself is unaffected.
init_pause_msec
This parameter defines a wait time to be used after forcing a reset of the device hardware. The units are milliseconds. The idea here is to allow the hardware some settling time after a reset, before we start poking at it again. The default is currently zero (because at the moment it appears that there is no wait time needed).
initusbreset
This parameter when set to non-zero enables the issuance of a USB-standard reset command to the PVR USB2 device when it is probed. It might help recover from a stuck device (which is why I implemented it) but I haven't actually seen it help when I've tried in the past. It is on by default since it shouldn't hurt.
procreload
This parameter when set to non-zero permits the driver to forcibly reload the microcontroller firmware as a recovery strategy from a failed device initialization. It is off by default because I haven't it found it to be too helpful.
tolerance
This parameter allows you to specify a tolerance level for dealing with USB streaming errors. This parameter takes a list of comma-separated values; each value is used for successive instances of the driver, providing you a way to raise the tolerance level for a specific device that you know might be connecting through flakey intervening hardware. The default is zero, which means no errors are tolerated at all and if one is encountered the stream will be terminated. Otherwise a non-zero tolerance value specifies how many consecutive errors will be ignored before the stream is errored-out. (If a URB succeeds after a failure, the running error count will be reset back to zero, thus what this option does is permit the driver to tolerate a certain level of spurious errors.) Note that errors ignored means that data will be lost and there will likely be a discontinuity in the stream data. You might realize that this parameter is "pasting over" what is probably a real problem in your USB controller, cabling, and/or core driver software. Don't use this lightly. I would suggest this as an act of last desparate resort if you can't otherwise solve your flakey hardware problem. Realize that even with a non-zero tolerance value, errors during control transfers are still not tolerated at all and will likely kill the stream - if you're lucky. It would be much better to just solve the underlying problem(s) in your system - but if you can't, then well I guess you can just tell the pvrusb2 here to try and tolerate some level of junk.
tuner
This parameter allows you to override the v4l tuner type associated with the device. Normally the correct value is detected through a scan of data from the device's internal eeprom. If however there is a problem with that (which has been known to happen in the past due to bugs, missing mappings, etc) and if you know what the correct actual type should be, then you can use this parameter to work around the problem. This parameter takes a list of comma-separated values; each value is used for successive instances of the driver (i.e. you can specify a tuner type per-instance).
video_nr
This parameter allows you to force the driver to use a specific v4l minor device number (assuming that the requested value isn't already allocated elsewhere). This parameter takes a list of comma-separated values; each value is used for successive instances of the driver (i.e. you can specify this per-instance). Some advice: If you find yourself having to play with this option, I suggest instead that maybe you should try setting up udev.
video_std
This parameter allows you to specify the initial video standard to use with the device. This is a per-instance driver option. The value is interpreted to be a bit mask as defined by the V4L v4l2_std_id type. Note that even if you use this option, an application can still change the video standard choice to something else. Also, if the choice falls outside the set of supported video standards as reported by the eeprom, then that set is expanded to include this value.

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


V4L apps

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

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.

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:

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

xine and vlc

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

Kaffeine

It is possible to get Kaffeine to work with this driver (streaming only?) using the following MRL:

fifo:/dev/video#demux:mpeg

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

If want to try MythTV, here are some tips:

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


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


IR handling

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.

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


Playing well with others

The following is a summary of issues / tips when using this driver alongside other software or in less-typical environments.

Playing well with ivtv

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.

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). Contact me for the patch.

Playing well in v4l

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.