README file for Winnov Videum Linux Driver 1999 September 21 * Note: Starting August 4, 1999 I have split the Winnov video capture driver into two modules: wnv.o and wnvvid.o If you have an older driver already on your system, you will need to edit your linux/drivers/char/Makefile and /etc/conf.modules files. See below. * Note2: Starting August 27, 1999 there is an audio driver for some Winnov cards, primarily the Videum PCI AV cards. The audio driver depends on the video driver, so install the video driver first according to the instructions here, then see wnvaudreadme.txt. The rest of this file discusses only the video capture driver. 1. About the driver: The driver was developed for kernel version 2.2. It won't compile on 2.0. (It will work on most recent 2.1 kernels.) I have written this driver myself as a volunteer effort and a fun project. Winnov is aware that the driver exists, but besides that they don't know anything about it. The driver is released under the terms of the GNU General Public License. There are many variations of Videum cards, and the driver doesn't work with them all. It should work with: * Any PCI Videum VO or AV card * Any ISA Videum VO or AV card that uses the Philips SAA7110, Philips SAA7111A, or ITT VPX video decoder, or any Philips EasyVideo card, except for some very early Videum AV cards It definately does not work with: * Videum Traveler digital cameras But there is a PCMCIA Traveler driver, see the link on the Winnov Linux web site http://www.thedirks.org/winnov/ 2. Video for Linux Two This driver uses the Video for Linux Two API. To run this driver you will need to get the V4L2 files, videodev.c and videodev.h and install them in place of the original videodev files. Videodev.c goes in /usr/src/linux/drivers/char, and videodev.h goes in /usr/src/linux/include/linux. You can get the V4L2 files from http://www.thedirks.org/v4l2/ There is a readme file included with the videodev.* files that explains how to install V4L2. Download videodev????????.tgz (whatever is latest) and unpack: # cd /usr/src/linux # tar zxvf videodev????????.tgz You may need to modify your kernel configuration. See the readme file. 3. Source files for the Winnov driver: wnv.c wnvvid.c wnv.h wnvhuff.h Put in /usr/src/linux/drivers/char. The typical commands would be: # cd /usr/src/linux/drivers/char # tar zxvf wnv19990731.tgz Compiling the driver: The driver uses the new V4L2 API and the V4L2 replacements for videodev.h and videodev.c should be installed first. See the documentation that comes with the V4L2 source. These files are available on the web at http://www.thedirks.org/v4l2/ The driver consists of two modules. The module wnv is the core module that interfaces to your Videum cards over the ISA or PCI bus. The module wnvvid is a V4L2 video capture driver and uses wnv to access the Videum cards. Add the new driver to the Makefile so it compiles just like your existing kernel modules. Edit /usr/src/linux/drivers/char/Makefile. Add "wnv.o" and "wnvvid.o" to the "M_OBJS :=" line near the top of the file like this: M_OBJS := wnv.o wnvvid.o Now compile modules, and do a depmod: # cd /usr/src/linux # make dep # make modules; make modules_install # depmod -a The driver will end up in /lib/modules/2.2.10/misc/. There should be no errors or warnings when compiling wnv.c or wnvvid.c. 4. Manually Loading the Driver: Note: Normally you would set up the configuration so the kernel will load the driver automatically. See "Automatically Loading the Driver" below. This discussion is only for testing. The driver depends on the videodev module. If that is not loaded, then load it with # modprobe videodev Now you can load the Winnov driver. Like all V4L2 drivers, you need to give each device a minor device number on the module load command line. The parameter is 'unit_video'. The driver can support up to four devices, but assuming you just have one, and you want it to be device 0 then: # modprobe wnvvid unit_video=0 It is probably a good idea to make sure that worked. The driver prints messages to /proc/kmsg, or your kernel log file, /var/log/messages. Take a look and see if it looks like the driver found your Videum. 5. Making a Device Node: Before the Videum can be used, you have to add a device node for it. Applications access Videum by opening the device node as a file. # mknod /dev/video0 c 81 0 The last parameter is the device minor number. This needs to match the unit_video= parameter of the module. Some applications may use /dev/video, in which case just make a symbolic link: # ln -s /dev/video0 /dev/video For example, the xawtv program requires this link. 6. Automatically Loading the Driver: If your kernel has the Kernel Module Loader option enabled you can make the driver load automatically. Edit /etc/conf.modules and add the lines alias char-major-81 videodev options wnvvid unit_video=0 alias char-major-81-0 wnvvid The unit_video= parameter must match the second number in the "alias char-major-81-* wnv" line. Also you must use the same number to make the device node. The driver will then load automatically when any application attempts to access the Videum. 7. Possible problems loading the driver: If the driver says it can't find the Videum you may have an IO conflict. ISA cards: If you have an non-Plug-and-Play ISA card, you can override the automatic IO port setting on the module load command line. For a non-PnP card the parameter is isa0_iobase, and the possible values are 0x160,0x150,0x140, 0x8160,0x8150,0x8140. For example # modprobe wnv isa0_iobase=0x150 If you can't find an IO port that works and you have a soldering iron, you can solder a jumper on W1. In which case the parameter is isa1_iobase, and the possible ports are 0x120,0x110,0x100,0x8120,0x8110, 0x8100. (The W1 jumper pins were not installed because the board had to be "jumperless" for marketing reasons. I'm not making this up.) Note that the board may still function correctly even if the driver reports a conflict because not all the addresses are used by the driver, so just try it to find out for sure. (Incidentally, it's possible to have two non-PnP ISA cards in one system if one has W1 open and the other has W1 closed.) If you have a PnP ISA card the parameter is pnp0_iobase, and the value can be any multiple of 0x80 greater than 0x400. For example # modprobe wnv.o pnp0_iobase=0x580 It is not possible to have two PnP ISA Videum cards in the same system because all PnP Videums unfortunately have the same PnP device ID code. I have occasionally gotten a "PnP checksum error" when installing the driver on PnP ISA cards. I don't know what this is yet. For me it goes away if I unload the driver and load it again. PCI cards: There are no command line overrides for the PCI cards. The IRQ and IO ports used by the PCI card are determined by the BIOS. 8. Testing with the xcaptest and vidpanel programs: The Videum driver supports all the capture features of the xcaptest and vidpanel programs available on the V4L2 website. Run xcaptest and give the device node name on the command line: # ./xcaptest /dev/video0& If your X Windows screen is 32 bits per pixel, you will probably need the -b option to get it work. # ./xcaptest -b /dev/video0 & In the xcaptest window, select the Standard as NTSC or PAL as appropriate. With xcaptest running, also run vidpanel, also with the device node name on the command line: # ./vidpanel /dev/video0 & In vidpanel select the video input. You should now see the video image on the screen! If you have more than one Videum, you can run more instances of xcaptest and vidpanel. 9. Using the driver in your own program: Look at xcaptest.c for the include files you need. The capture parameters are set up through ioctl() calls. Capturing is done through the read() function. Each call to read() gets a new frame. The buffer must be big enough to hold the entire frame or else read() will fail. See the Video for Linux Two draft video capture specification for more details: http://www.thedirks.org/v4l2/v4l2cap.htm The driver supports all the video related ioctls, excluding frame buffer capture and TV tuning. Both blocking and non-blocking reads are supported, as are the select() call, and streaming capture through memory-mapped driver buffers. The driver only supports capturing one field, so images sizes are limited to 240 pixel vertically for NTSC, or 288 pixels for PAL. The driver supports the following pixel formats: V4L2_PIX_FMT_YUYV V4L2_PIX_FMT_GREY V4L2_PIX_FMT_YUV420 V4L2_PIX_FMT_RGB555 V4L2_PIX_FMT_RGB565 V4L2_PIX_FMT_BGR24 V4L2_PIX_FMT_BGR32 10. More notes: The driver will autodetect an ISA Videum and select an IO port based on the ioport table of Linux. For a PCI Videum, the driver will always use the pre-assigned IO port and IRQ. There is currently no way to override automatic settings from the command line for PCI devices. The driver supports multiple Videums in a sytem. You can use multiple PCI cards, and/or a single PnP ISA card and/or a non-PnP ISA with jumper W1 open, and/or a non-PnP ISA card with jumper W1 closed. To use multiple Videums in a system, you just have to do a mknod for each one. You may want to subscribe to the video4linux mailing list. Go to https://listman.redhat.com/mailman/listinfo/video4linux-list Have fun with your Videum on Linux! Bill.