Subversion Repositories or1k

DC10/DC10plus/LML33/Buz  Driver for Linux

=========================================

by Rainer Johanni  (for Iomega Buz Driver)

Adapted for DC10/DC10plus by Wolfgang Scherr 

Further changes for DC10/DC10plus and LML33 cards by

Serguei Miridonov 

Current homepage: http://www.cicese.mx/~mirsev/Linux/DC10plus/

Current maintainer: Serguei Miridonov 

  This is a driver for DC10plus capture cards from Pinnacle Systems

  Inc., LML33 cards from Linux Media Labs and Buz from Iomega.

  It also works with many old Miro DC10 cards with SAA7110A TV decoder

  and ADV7176 TV encoder (please, make sure that your card has these

  chips, otherwise the driver will not work).

  The driver is Video4Linux compliant and contains extensions to

  provide hardware support for full motion MJPEG compression and

  decompression. Since this driver is a derivative from the driver for

  Buz Iomega cards written by Dr. Rainer Johanni,

  http://www.johanni.de/munich-vision/buz/ they both have compatible

  API. I hope that this API will become a part of V4L standard.

Copyright: This driver is free software; you can redistribute it and/or

modify it under the terms of the GNU General Public License. Please,

check http://www.gnu.org/ for details.

No warranty: This software is provided on AN "AS-IS" basis WITHOUT

WARRANTY OF ANY KIND. YOU USE IT AT YOUR OWN RISK.

CONTENTS

~~~~~~~~

Supported Formats

Hardware compression

Compiling and Loading the Driver

Driver Options

Tested applications

Programming interface

Features for testing

Mailing lists

Bug Reports

Supported Formats

=================

Card:              DC10/DC10plus             LML33/Buz

TV standard:       NTSC/PAL/SECAM(*)         NTSC/PAL

Format:            Square pixel              CCIR.601

                   640x480 NTSC              720x480 NTSC

                   768x576 PAL/SECAM(*)      720x576 PAL

Frame rates: 30 frames/60 fields per second NTSC

             25 frames/50 fields per second PAL/SECAM(*)

(*) - SECAM is supported for input only in DC10/DC10plus cards. The

output of the recorded SECAM video stream will be in PAL standard.

Also, please, note that monitoring of the SECAM input signal at the

DC10/DC10plus analog output may not be available. Please, use

appropriate application like XawTV to watch full color SECAM video at

the card input.

Hardware compression

====================

Since the card provides hardware compression, even low end machines can

be successfully used for movie capture and playback. I'm testing the

driver with with 2.2.16 kernel running on 233 MHz Pentium MMX with 64M

RAM on 430TX motherboard and with 10GB IDE drive from Western Digital

Corp.

On one test run with DC10plus card I've got 0 frames dropped during

about 20 minutes of full motion NTSC (I live in Mexico) video capture

with fully synchronized audio. The command was

  lavrec -fa -in -d1 -l -1 -q30 -w /dos/g/capture/Linux/test%03d.avi

for recording, and

  lavplay -n128 /dos/g/capture/Linux/test*.avi

for playback. (See lavtools distribution for more information).

Typical run of similar test can provide as few as 6-8 dropped frames per

half of an hour. You mileage may vary, though.

Compiling and Loading the Driver

================================

You should run a 2.2.x kernel in order to use this driver. The driver

was also tested with 2.4-test6 kernel, so hopefully it will work

with 2.4 kernels too.

I would recommend to use only official kernels from www.kernel.org and

its mirrors. Kernels supplied with some Linux distributions may be

patched in some way to meet specific needs of particular Linux

distributor and could be incompatible with this driver. As a driver

maintainer, I am not able to follow every unofficial kernel release,

and no unofficial kernels will be supported.

Besides the files in this directory, the driver needs the 'videodev'

and the 'i2c' module from the Linux kernel (i2c-old for 2.4 kernels).

In order to get these modules available, enable module support for

VIDEODEV and BTTV (which implies i2c) in your 2.2.x kernel

configuration. You will find these devices in the menu "Character

Devices" in your Kernel Configuration.

In newer kernels (2.4) instead of BTTV you should enable support for

Iomega Buz cards and for Zoran 36060/36067 chipset. This will include

i2c or i2c-old modules and Buz/LML33 driver. However, instead of

modules for Buz/LML33 driver from the kernel, use modules from _this_

driver.

To compile the driver, just type make.

Before you load the driver you must have a video device at major device

node 81. If you don't have it yet, do the following (as root!):

cd /dev

mknod video0 c 81 0

ln -s video0 video

If you have more than one card, add more nodes in /dev directory:

mknod video1 c 81 1

mknod video2 c 81 2

...

The driver should operate properly with several cards. It was tested

with one DC10plus and one LML33 cards installed together and the driver

correctly identifies both cards and works with both of them.

Currently the driver does not support LML33 and Buz cards installed

together in the same system. This will be fixed in future versions.

Edit the 'update' script if you want to give the driver special options

(see below for options descriptions) and then type (as root)

./update 

to insert all necessary modules into the kernel.  is a list of

cards installed in your system separated by white space. Supported cards

are dc10, dc10plus, lml33, and buz. For example, if you have both dc10plus

and lml33 cards, please type

./update dc10 lml33

If you want to make full use of the Video for Linux _uncompressed_

grabbing facilities, you must either

- obtain and install the "big_physarea patch" for your kernel and

  set aside the necessary memory during boot time. There seem to be

  several versions of this patch against various kernel versions

  floating around in the net, you may obtain one e.g. from:

  http://www.polyware.nl/~middelin/hob-v4l.html#bigphysarea

  You also have to compile your driver AFTER installing that patch in

  order to get it working

  or

- start your kernel with the mem=xxx option, where xxx is your

  real memory minus the memory needed for the buffers.

  For doing this add an entry in lilo.conf (if you use lilo):

    append "mem=xxxM"

  or add a line in your linux.par file (if you use loadlin):

    mem=xxxM

The second method is by far easier, however it is dangerous if more

than one driver at a time has the idea to use the memory leftover by

setting the mem=xxx parameter below the actual memory size.

Read also below how to use this memory!

  If you use only MJPEG compressed capture provided by the driver, you

  should not need large memory areas for DMA. In this case, you will be

  able to capture and playback movies with lavtools, however you will

  not be able to use capture features of XawTV and other similar

  programs (you can still watch video on the screen).

Driver Options

==============

You are able to customize the behavior of the driver by giving

it some options at start time.

default_input, default_norm

---------------------------

As soon as the driver is loaded, the Buz samples video signals

from one of its input ports and displays it on its output.

The driver uses the Composite Input and the video norm PAL for this.

If you want to change this default behavior, set default_input=1

(for S-VHS input) or default_norm=1 for NTSC or default_norm=2

for SECAM (DC10/DC10plus only).

lock_norm

---------

This option was introduced to disable norm (TV standard) change by some

not well behaving programs. For example, if you have some application

which was written by somebody who lives in a country with PAL standard,

this program may not have NTSC option and may always try to set the

driver to PAL. In this case, you may load the driver with

default_norm=1 and lock_norm=1 and the card will be forced to work in

NTSC standard only.

  Options:

  lock_norm=0   default, TV standard change is enabled;

  lock_norm=1   TV standard change is disabled but the driver

                will not notify the application about any error;

  lock_norm=2   TV standard change is disabled and the driver

                will notify the program that TV standards other

                than set by default_norm=X option are not

                supported.

pass_through

------------

When the driver is not in use (device is not opened by any program) and

pass_through=0 (default) the driver will set the TV encoder to produce

color bar signal at the output. If the driver was loaded with

pass_through=1, the color bar will be disabled and input signal will be

sent to the output even if the driver not in use. If you have LML33 card

and wish the color bar signal at the output, you will also need to set

lml33dpath=1 (please, see next section).

lml33dpath

----------

LML33 card normally (lml33dpath=0) connects its output to the input

using analog switch. Additionally, it also allows real-time monitoring

of digitized video using TV monitor connected to the output. This

"digital path" option can be enabled setting lml33dpath=1. In this

mode, the input is connected only to the TV decoder, digital video data

is sent via internal video bus to the TV encoder and resulting analog

signal is sent to the output. This mode could be very useful for testing and

picture adjustment while watching video at the TV monitor connected to

the output. However, because of lack of 75 ohm terminating resistors at

TV decoder input, the signal will suffer serious distortions.

# These distortions could be eliminated by soldering two 75 ohm resistors

# in LML33 card: in parallel to capacitors C73 and C82 (see schematics of

# H33 board available at www.linuxmedialabs.com and www.zoran.com). Be

# aware, however, that doing so will void card warranty and the card,

# after this change, must always be used with loading option lml33dpath=1.

#

# WARNING: I DID NOT TRY THIS CARD CHANGE YET, THIS IS JUST AN ASSUMPTION

# AND I WILL NOT BE RESPONSIBLE FOR ANY DAMAGE ASSOCIATED WITH THIS

# CHANGE. IF YOU WISH TO TRY IT, DO IT AT YOUR OWN RISK.

Please, note that DC10/DC10plus cards always use "digital path" for

signal monitoring. Its input and output are both properly terminated

and the digitized signal quality does not depend on the connection of

the output load.

v4l_nbufs, v4l_bufsize

----------------------

In order to make to make full use of the Video for Linux uncompressed

picture grabbing facilities of the driver (which are needed by many

Video for Linux applications), the driver needs a set of physically

contiguous buffers for grabbing. These parameters determine how many

buffers of which size the driver will allocate at open (the open will

fail if it is unable to do so!).

These values do not affect the MJPEG grabbing facilities of the driver,

they are needed for uncompressed image grabbing only!!!

v4l_nbufs is the number of buffers to allocate, a value of 2 (the default)

should be sufficient in almost all cases. Only special applications

(streaming captures) will need more buffers and then mostly the

MJPEG capturing features of the Buz will be more appropriate.

So leave this parameter at it's default unless you know what you do.

The things for v4l_bufsize are more complicated: v4l_bufsize is set by

default to 128 [KB] which is the maximum amount of physically

contiguous memory Linux is able to allocate without kernel changes.

This is sufficient for grabbing 24 bit color images up to sizes of

approx. 240x180 pixels (240*180*3 = 129600, 128 KB = 131072).

In order to be able to capture bigger images you have either to

- obtain and install the "big_physarea patch" and set aside

  the necessary memory during boot time or

- start your kernel with the mem=xxx option, where xxx is your

  real memory minus the memory needed for the buffers.

In that case, useful settings for v4l_bufsize are

- 1296 [Kb] for grabbing 24 bit images of max size 768*576

- 1728 [Kb] for 32bit images of same size (4*768*576 = 1728 Kb!)

You may reduce these numbers accordingly if you know you are only

grabbing 720 pixels wide images or NTSC images (max height 480).

In some cases it may happen that Linux isn't even able to obtain

the default 128 KB buffers. If you don't need uncompressed image

grabbing at all, set v4l_bufsize to an arbitrary small value (e.g. 4)

in order to be able to open the video device.

triton, natoma

--------------

The driver tries to detect if you have a triton or natoma chipset

in order to take special measures for these chipsets.

If this detection fails but you are sure you have such a chipset,

set the corresponding variable to 1.

This is a very special option and may go away in the future.

Tested applications

===================

  XawTV         to watch video on your computer monitor.

  kwintv        the same (you might need to use option lock_norm=1).

  lavtools      To record and playback AVI or Quicktime files. Note: you

                will need patched version, lavtools-1.2p2 to support new

                features of this driver. Please visit driver homepage for

                more info.

  Broadcast2000 reportedly (I didn't try that) can accept movies recorded

                by lavrec in Quicktime format for editing and then edited

                movie can be played back by lavplay program.

  MainActor 3.5x also can accept movies recorded by lavrec for editing.

The driver can to be used by two programs at the same time

(please, see warning note below regarding this feature). Using XawTV

you can watch what you are recording or playing back with lavtools.

I've tested the following sequence and it worked for me:

* start xawtv and switch inputs, TV standards, and adjust video

  (contrast, saturation, etc.). You may also run your favorite

  audio mixer application to adjust audio inputs.

* run lavrec with options:

    -i (to choose proper input

                                      and TV standard)

    -l -1  (to use audio mixer settings)

    Other lavrec option can be added at your choice.

* watch the movie in xawtv window while recording it as AVI or

  Quicktime file.

* when recording is finished, run lavplay or xlav and watch your

  clip in xawtv window.

* Note: you should not quit xawtv during recording or playing back.

  If you quit xawtv during recording or playback, another lavtools

  program will stop and may even crash.

I'm not sure that the same will work for you. You can try but,

please, be careful.

WARNING! This is an experimental feature and I'm not sure if it will be

supported in the future. The original driver was not designed to be

used like this and it has no protection against any interference

between two running programs. THEREFORE, IT IS POTENTIALLY DANGEROUS

AND SINCE THE DRIVER OPERATES IN KERNEL SPACE, USING THIS FEATURE MAY

CRASH YOUR ENTIRE SYSTEM.

Programming interface

=====================

This driver should be fully compliant to Video for Linux, so all

tools working with Video for Linux should work with (hopefully)

no problems.

A description of the Video for Linux programming interface can be found at:

http://roadrunner.swansea.linux.org.uk/v4lapi.shtml

Besides the Video for Linux interface, the driver has a "proprietary"

interface for accessing the Buz's MJPEG capture and playback facilities.

For a full description of all members and ioctls see "zoran.h" (used to

be buz.h or dc10.h in previous versions, so, please, update your

programs accordingly).

The ioctls for that interface are as follows:

BUZIOC_G_PARAMS

BUZIOC_S_PARAMS

Get and set the parameters of the buz. The user should always do a

BUZIOC_G_PARAMS (with a struct buz_params) to obtain the default

settings, change what he likes and then make a BUZIOC_S_PARAMS call.

BUZIOC_REQBUFS

Before being able to capture/playback, the user has to request

the buffers he is wanting to use. Fill the structure

zoran_requestbuffers with the size (recommended: 256*1024) and

the number (recommended 32 up to 256). There are no such restrictions

as for the Video for Linux buffers, you should LEAVE SUFFICIENT

MEMORY for your system however, else strange things will happen ....

On return, the zoran_requestbuffers structure contains number and

size of the actually allocated buffers.

You should use these numbers for doing a mmap of the buffers

into the user space.

The BUZIOC_REQBUFS ioctl also makes it happen, that the next mmap

maps the MJPEG buffer instead of the V4L buffers.

BUZIOC_QBUF_CAPT

BUZIOC_QBUF_PLAY

Queue a buffer for capture or playback. The first call also starts

streaming capture. When streaming capture is going on, you may

only queue further buffers or issue syncs until streaming

capture is switched off again with a argument of -1 to

a BUZIOC_QBUF_CAPT/BUZIOC_QBUF_PLAY ioctl.

BUZIOC_SYNC

Issue this ioctl when all buffers are queued. This ioctl will

block until the first buffer becomes free for saving its

data to disk (after BUZIOC_QBUF_CAPT) or for reuse (after BUZIOC_QBUF_PLAY).

BUZIOC_G_STATUS

Get the status of the input lines (video source connected/norm).

This ioctl may be subject to change.

For programming example, please, look at lavrec.c and lavplay.c code in

lavtools-1.2p2 package (URL: http://www.cicese.mx/~mirsev/DC10plus/)

and the 'examples' directory in the original Buz driver distribution.

Additional notes for software developers:

   The driver returns maxwidth and maxheight parameters according to

   the current TV standard (norm). Therefore, the software which

   communicates with the driver and "asks" for these parameters should

   first set the correct norm. Well, it seems logically correct: TV

   standard is "more constant" for current country than geometry

   settings of a variety of TV capture cards which may work in ITU or

   square pixel format. Remember that users now can lock the norm to

   avoid any ambiguity.

Features for testing

====================

When loaded, the driver creates a /proc/zoranX entry for each card:

using 'cat /proc/zoran0' for your first card you can see the contents

of ZR36057/67 chip registers. It is also possible to modify the

contents of some registers directly. WARNING: modified contents is not

stored in the driver memory, if you restart any program which uses this

driver or even change position or cause redraw of a window of xawtv or

other program, the original registers contents will be restored by the

driver. However, it can be used to change ZR36067 registers on the fly

for fine tuning and then to include these changes into driver code.

This feature is very limited and still requires some documentation.

However, if you are impatient, look at zoran_procfs.c code and

(IMPORTANT!) read ZR36057/67 manual. To set TopField bit, for example,

you need to type as root:

echo TopField=1 > /proc/zoranX # change X to 0 for your first card,

                               # 1 for second and so on...

If you use this feature and have found some interesting result, please, let

me know.

Mailing lists

=============

There are two mailing lists available to discuss application issues and

suggest driver improvements:

1. A mailing list buz-linux was set up to discuss Iomega Buz driver.

Since this driver is derivative of that driver, you can also post your

questions and suggestions there. Subscribe with a message (with

"subscribe" in the subject) to  buz-linux-subscribe@webmages.com.

Unsubscribe with a message (with "unsubscribe" in the subject) to

buz-linux-unsubscribe@webmages.com. The mailing list archive can be

found at http://buz.webmages.com/list/.

2. Video4Linux mailing list is set for more general discussions related

to uncompressed video capture, V4L and V4L2 API, many Video4Linux

applications, etc. to subscribe to this mailing list, please, visit

https://listman.redhat.com/mailman/listinfo/video4linux-list

Bug Reports

===========

If you have found a bug, please, do the following:

1. Edit first line of zoran.c file and set DEBUGLEVEL to 3;

2. Recompile the driver and install it running update script

   in the driver directory;

3. Run the application(s) which you used when you had found a

   suspisious behavior;

4. When application stops, look at you /var/log/messages file

   (or whatever file you use to log kernel messages) and copy

   all lines related to the driver activity to a separate file

   in the same order of their appearence in your log file.

5. Mail a message to  with a subject

   "Linux DC10(plus)/LML33/Buz driver bug report" with a detailed

   description of your problem, kernel version, application name and

   attach that file with kernel messages as plain text (please, don't

   attach it using base64, uuencode, or any other encoding).

   If you have a Buz card, please, also mail the same message to

   Wolfgang Scherr