1 DC10/DC10plus/LML33/Buz Driver for Linux
2 =========================================
4 by Rainer Johanni <Rainer@Johanni.de> (for Iomega Buz Driver)
6 Adapted for DC10/DC10plus by Wolfgang Scherr <scherr@net4you.net>
8 Further changes for DC10/DC10plus and LML33 cards by
9 Serguei Miridonov <mirsev@cicese.mx>
11 Current homepage: http://www.cicese.mx/~mirsev/Linux/DC10plus/
12 Current maintainer: Serguei Miridonov <mirsev@cicese.mx>
14 This is a driver for DC10plus capture cards from Pinnacle Systems
15 Inc., LML33 cards from Linux Media Labs and Buz from Iomega.
16 It also works with many old Miro DC10 cards with SAA7110A TV decoder
17 and ADV7176 TV encoder (please, make sure that your card has these
18 chips, otherwise the driver will not work).
20 The driver is Video4Linux compliant and contains extensions to
21 provide hardware support for full motion MJPEG compression and
22 decompression. Since this driver is a derivative from the driver for
23 Buz Iomega cards written by Dr. Rainer Johanni,
24 http://www.johanni.de/munich-vision/buz/ they both have compatible
25 API. I hope that this API will become a part of V4L standard.
27 Copyright: This driver is free software; you can redistribute it and/or
28 modify it under the terms of the GNU General Public License. Please,
29 check http://www.gnu.org/ for details.
31 No warranty: This software is provided on AN "AS-IS" basis WITHOUT
32 WARRANTY OF ANY KIND. YOU USE IT AT YOUR OWN RISK.
41 Compiling and Loading the Driver
53 Card: DC10/DC10plus LML33/Buz
55 TV standard: NTSC/PAL/SECAM(*) NTSC/PAL
57 Format: Square pixel CCIR.601
58 640x480 NTSC 720x480 NTSC
59 768x576 PAL/SECAM(*) 720x576 PAL
61 Frame rates: 30 frames/60 fields per second NTSC
62 25 frames/50 fields per second PAL/SECAM(*)
64 (*) - SECAM is supported for input only in DC10/DC10plus cards. The
65 output of the recorded SECAM video stream will be in PAL standard.
66 Also, please, note that monitoring of the SECAM input signal at the
67 DC10/DC10plus analog output may not be available. Please, use
68 appropriate application like XawTV to watch full color SECAM video at
74 Since the card provides hardware compression, even low end machines can
75 be successfully used for movie capture and playback. I'm testing the
76 driver with with 2.2.16 kernel running on 233 MHz Pentium MMX with 64M
77 RAM on 430TX motherboard and with 10GB IDE drive from Western Digital
80 On one test run with DC10plus card I've got 0 frames dropped during
81 about 20 minutes of full motion NTSC (I live in Mexico) video capture
82 with fully synchronized audio. The command was
84 lavrec -fa -in -d1 -l -1 -q30 -w /dos/g/capture/Linux/test%03d.avi
88 lavplay -n128 /dos/g/capture/Linux/test*.avi
90 for playback. (See lavtools distribution for more information).
92 Typical run of similar test can provide as few as 6-8 dropped frames per
93 half of an hour. You mileage may vary, though.
95 Compiling and Loading the Driver
96 ================================
98 You should run a 2.2.x kernel in order to use this driver. The driver
99 was also tested with 2.4-test6 kernel, so hopefully it will work
100 with 2.4 kernels too.
102 I would recommend to use only official kernels from www.kernel.org and
103 its mirrors. Kernels supplied with some Linux distributions may be
104 patched in some way to meet specific needs of particular Linux
105 distributor and could be incompatible with this driver. As a driver
106 maintainer, I am not able to follow every unofficial kernel release,
107 and no unofficial kernels will be supported.
109 Besides the files in this directory, the driver needs the 'videodev'
110 and the 'i2c' module from the Linux kernel (i2c-old for 2.4 kernels).
111 In order to get these modules available, enable module support for
112 VIDEODEV and BTTV (which implies i2c) in your 2.2.x kernel
113 configuration. You will find these devices in the menu "Character
114 Devices" in your Kernel Configuration.
116 In newer kernels (2.4) instead of BTTV you should enable support for
117 Iomega Buz cards and for Zoran 36060/36067 chipset. This will include
118 i2c or i2c-old modules and Buz/LML33 driver. However, instead of
119 modules for Buz/LML33 driver from the kernel, use modules from _this_
122 To compile the driver, just type make.
124 Before you load the driver you must have a video device at major device
125 node 81. If you don't have it yet, do the following (as root!):
131 If you have more than one card, add more nodes in /dev directory:
137 The driver should operate properly with several cards. It was tested
138 with one DC10plus and one LML33 cards installed together and the driver
139 correctly identifies both cards and works with both of them.
141 Currently the driver does not support LML33 and Buz cards installed
142 together in the same system. This will be fixed in future versions.
144 Edit the 'update' script if you want to give the driver special options
145 (see below for options descriptions) and then type (as root)
149 to insert all necessary modules into the kernel. <card_list> is a list of
150 cards installed in your system separated by white space. Supported cards
151 are dc10, dc10plus, lml33, and buz. For example, if you have both dc10plus
152 and lml33 cards, please type
156 If you want to make full use of the Video for Linux _uncompressed_
157 grabbing facilities, you must either
159 - obtain and install the "big_physarea patch" for your kernel and
160 set aside the necessary memory during boot time. There seem to be
161 several versions of this patch against various kernel versions
162 floating around in the net, you may obtain one e.g. from:
163 http://www.polyware.nl/~middelin/hob-v4l.html#bigphysarea
164 You also have to compile your driver AFTER installing that patch in
165 order to get it working
169 - start your kernel with the mem=xxx option, where xxx is your
170 real memory minus the memory needed for the buffers.
171 For doing this add an entry in lilo.conf (if you use lilo):
173 or add a line in your linux.par file (if you use loadlin):
176 The second method is by far easier, however it is dangerous if more
177 than one driver at a time has the idea to use the memory leftover by
178 setting the mem=xxx parameter below the actual memory size.
180 Read also below how to use this memory!
183 If you use only MJPEG compressed capture provided by the driver, you
184 should not need large memory areas for DMA. In this case, you will be
185 able to capture and playback movies with lavtools, however you will
186 not be able to use capture features of XawTV and other similar
187 programs (you can still watch video on the screen).
194 You are able to customize the behavior of the driver by giving
195 it some options at start time.
197 default_input, default_norm
198 ---------------------------
200 As soon as the driver is loaded, the Buz samples video signals
201 from one of its input ports and displays it on its output.
202 The driver uses the Composite Input and the video norm PAL for this.
203 If you want to change this default behavior, set default_input=1
204 (for S-VHS input) or default_norm=1 for NTSC or default_norm=2
205 for SECAM (DC10/DC10plus only).
210 This option was introduced to disable norm (TV standard) change by some
211 not well behaving programs. For example, if you have some application
212 which was written by somebody who lives in a country with PAL standard,
213 this program may not have NTSC option and may always try to set the
214 driver to PAL. In this case, you may load the driver with
215 default_norm=1 and lock_norm=1 and the card will be forced to work in
220 lock_norm=0 default, TV standard change is enabled;
221 lock_norm=1 TV standard change is disabled but the driver
222 will not notify the application about any error;
223 lock_norm=2 TV standard change is disabled and the driver
224 will notify the program that TV standards other
225 than set by default_norm=X option are not
231 When the driver is not in use (device is not opened by any program) and
232 pass_through=0 (default) the driver will set the TV encoder to produce
233 color bar signal at the output. If the driver was loaded with
234 pass_through=1, the color bar will be disabled and input signal will be
235 sent to the output even if the driver not in use. If you have LML33 card
236 and wish the color bar signal at the output, you will also need to set
237 lml33dpath=1 (please, see next section).
242 LML33 card normally (lml33dpath=0) connects its output to the input
243 using analog switch. Additionally, it also allows real-time monitoring
244 of digitized video using TV monitor connected to the output. This
245 "digital path" option can be enabled setting lml33dpath=1. In this
246 mode, the input is connected only to the TV decoder, digital video data
247 is sent via internal video bus to the TV encoder and resulting analog
248 signal is sent to the output. This mode could be very useful for testing and
249 picture adjustment while watching video at the TV monitor connected to
250 the output. However, because of lack of 75 ohm terminating resistors at
251 TV decoder input, the signal will suffer serious distortions.
253 # These distortions could be eliminated by soldering two 75 ohm resistors
254 # in LML33 card: in parallel to capacitors C73 and C82 (see schematics of
255 # H33 board available at www.linuxmedialabs.com and www.zoran.com). Be
256 # aware, however, that doing so will void card warranty and the card,
257 # after this change, must always be used with loading option lml33dpath=1.
259 # WARNING: I DID NOT TRY THIS CARD CHANGE YET, THIS IS JUST AN ASSUMPTION
260 # AND I WILL NOT BE RESPONSIBLE FOR ANY DAMAGE ASSOCIATED WITH THIS
261 # CHANGE. IF YOU WISH TO TRY IT, DO IT AT YOUR OWN RISK.
263 Please, note that DC10/DC10plus cards always use "digital path" for
264 signal monitoring. Its input and output are both properly terminated
265 and the digitized signal quality does not depend on the connection of
269 v4l_nbufs, v4l_bufsize
270 ----------------------
272 In order to make to make full use of the Video for Linux uncompressed
273 picture grabbing facilities of the driver (which are needed by many
274 Video for Linux applications), the driver needs a set of physically
275 contiguous buffers for grabbing. These parameters determine how many
276 buffers of which size the driver will allocate at open (the open will
277 fail if it is unable to do so!).
279 These values do not affect the MJPEG grabbing facilities of the driver,
280 they are needed for uncompressed image grabbing only!!!
282 v4l_nbufs is the number of buffers to allocate, a value of 2 (the default)
283 should be sufficient in almost all cases. Only special applications
284 (streaming captures) will need more buffers and then mostly the
285 MJPEG capturing features of the Buz will be more appropriate.
286 So leave this parameter at it's default unless you know what you do.
288 The things for v4l_bufsize are more complicated: v4l_bufsize is set by
289 default to 128 [KB] which is the maximum amount of physically
290 contiguous memory Linux is able to allocate without kernel changes.
291 This is sufficient for grabbing 24 bit color images up to sizes of
292 approx. 240x180 pixels (240*180*3 = 129600, 128 KB = 131072).
294 In order to be able to capture bigger images you have either to
295 - obtain and install the "big_physarea patch" and set aside
296 the necessary memory during boot time or
297 - start your kernel with the mem=xxx option, where xxx is your
298 real memory minus the memory needed for the buffers.
299 In that case, useful settings for v4l_bufsize are
300 - 1296 [Kb] for grabbing 24 bit images of max size 768*576
301 - 1728 [Kb] for 32bit images of same size (4*768*576 = 1728 Kb!)
302 You may reduce these numbers accordingly if you know you are only
303 grabbing 720 pixels wide images or NTSC images (max height 480).
305 In some cases it may happen that Linux isn't even able to obtain
306 the default 128 KB buffers. If you don't need uncompressed image
307 grabbing at all, set v4l_bufsize to an arbitrary small value (e.g. 4)
308 in order to be able to open the video device.
313 The driver tries to detect if you have a triton or natoma chipset
314 in order to take special measures for these chipsets.
315 If this detection fails but you are sure you have such a chipset,
316 set the corresponding variable to 1.
317 This is a very special option and may go away in the future.
323 XawTV to watch video on your computer monitor.
325 kwintv the same (you might need to use option lock_norm=1).
327 lavtools To record and playback AVI or Quicktime files. Note: you
328 will need patched version, lavtools-1.2p2 to support new
329 features of this driver. Please visit driver homepage for
332 Broadcast2000 reportedly (I didn't try that) can accept movies recorded
333 by lavrec in Quicktime format for editing and then edited
334 movie can be played back by lavplay program.
336 MainActor 3.5x also can accept movies recorded by lavrec for editing.
339 The driver can to be used by two programs at the same time
340 (please, see warning note below regarding this feature). Using XawTV
341 you can watch what you are recording or playing back with lavtools.
342 I've tested the following sequence and it worked for me:
344 * start xawtv and switch inputs, TV standards, and adjust video
345 (contrast, saturation, etc.). You may also run your favorite
346 audio mixer application to adjust audio inputs.
348 * run lavrec with options:
350 -i<set your input and norm here> (to choose proper input
353 -l -1 (to use audio mixer settings)
355 Other lavrec option can be added at your choice.
357 * watch the movie in xawtv window while recording it as AVI or
360 * when recording is finished, run lavplay or xlav and watch your
361 clip in xawtv window.
363 * Note: you should not quit xawtv during recording or playing back.
364 If you quit xawtv during recording or playback, another lavtools
365 program will stop and may even crash.
367 I'm not sure that the same will work for you. You can try but,
370 WARNING! This is an experimental feature and I'm not sure if it will be
371 supported in the future. The original driver was not designed to be
372 used like this and it has no protection against any interference
373 between two running programs. THEREFORE, IT IS POTENTIALLY DANGEROUS
374 AND SINCE THE DRIVER OPERATES IN KERNEL SPACE, USING THIS FEATURE MAY
375 CRASH YOUR ENTIRE SYSTEM.
378 Programming interface
379 =====================
381 This driver should be fully compliant to Video for Linux, so all
382 tools working with Video for Linux should work with (hopefully)
385 A description of the Video for Linux programming interface can be found at:
386 http://roadrunner.swansea.linux.org.uk/v4lapi.shtml
388 Besides the Video for Linux interface, the driver has a "proprietary"
389 interface for accessing the Buz's MJPEG capture and playback facilities.
391 For a full description of all members and ioctls see "zoran.h" (used to
392 be buz.h or dc10.h in previous versions, so, please, update your
393 programs accordingly).
395 The ioctls for that interface are as follows:
400 Get and set the parameters of the buz. The user should always do a
401 BUZIOC_G_PARAMS (with a struct buz_params) to obtain the default
402 settings, change what he likes and then make a BUZIOC_S_PARAMS call.
406 Before being able to capture/playback, the user has to request
407 the buffers he is wanting to use. Fill the structure
408 zoran_requestbuffers with the size (recommended: 256*1024) and
409 the number (recommended 32 up to 256). There are no such restrictions
410 as for the Video for Linux buffers, you should LEAVE SUFFICIENT
411 MEMORY for your system however, else strange things will happen ....
412 On return, the zoran_requestbuffers structure contains number and
413 size of the actually allocated buffers.
414 You should use these numbers for doing a mmap of the buffers
416 The BUZIOC_REQBUFS ioctl also makes it happen, that the next mmap
417 maps the MJPEG buffer instead of the V4L buffers.
422 Queue a buffer for capture or playback. The first call also starts
423 streaming capture. When streaming capture is going on, you may
424 only queue further buffers or issue syncs until streaming
425 capture is switched off again with a argument of -1 to
426 a BUZIOC_QBUF_CAPT/BUZIOC_QBUF_PLAY ioctl.
430 Issue this ioctl when all buffers are queued. This ioctl will
431 block until the first buffer becomes free for saving its
432 data to disk (after BUZIOC_QBUF_CAPT) or for reuse (after BUZIOC_QBUF_PLAY).
436 Get the status of the input lines (video source connected/norm).
437 This ioctl may be subject to change.
439 For programming example, please, look at lavrec.c and lavplay.c code in
440 lavtools-1.2p2 package (URL: http://www.cicese.mx/~mirsev/DC10plus/)
441 and the 'examples' directory in the original Buz driver distribution.
443 Additional notes for software developers:
445 The driver returns maxwidth and maxheight parameters according to
446 the current TV standard (norm). Therefore, the software which
447 communicates with the driver and "asks" for these parameters should
448 first set the correct norm. Well, it seems logically correct: TV
449 standard is "more constant" for current country than geometry
450 settings of a variety of TV capture cards which may work in ITU or
451 square pixel format. Remember that users now can lock the norm to
457 When loaded, the driver creates a /proc/zoranX entry for each card:
458 using 'cat /proc/zoran0' for your first card you can see the contents
459 of ZR36057/67 chip registers. It is also possible to modify the
460 contents of some registers directly. WARNING: modified contents is not
461 stored in the driver memory, if you restart any program which uses this
462 driver or even change position or cause redraw of a window of xawtv or
463 other program, the original registers contents will be restored by the
464 driver. However, it can be used to change ZR36067 registers on the fly
465 for fine tuning and then to include these changes into driver code.
466 This feature is very limited and still requires some documentation.
467 However, if you are impatient, look at zoran_procfs.c code and
468 (IMPORTANT!) read ZR36057/67 manual. To set TopField bit, for example,
469 you need to type as root:
471 echo TopField=1 > /proc/zoranX # change X to 0 for your first card,
472 # 1 for second and so on...
474 If you use this feature and have found some interesting result, please, let
480 There are two mailing lists available to discuss application issues and
481 suggest driver improvements:
483 1. A mailing list buz-linux was set up to discuss Iomega Buz driver.
484 Since this driver is derivative of that driver, you can also post your
485 questions and suggestions there. Subscribe with a message (with
486 "subscribe" in the subject) to buz-linux-subscribe@webmages.com.
487 Unsubscribe with a message (with "unsubscribe" in the subject) to
488 buz-linux-unsubscribe@webmages.com. The mailing list archive can be
489 found at http://buz.webmages.com/list/.
491 2. Video4Linux mailing list is set for more general discussions related
492 to uncompressed video capture, V4L and V4L2 API, many Video4Linux
493 applications, etc. to subscribe to this mailing list, please, visit
494 https://listman.redhat.com/mailman/listinfo/video4linux-list
499 If you have found a bug, please, do the following:
501 1. Edit first line of zoran.c file and set DEBUGLEVEL to 3;
502 2. Recompile the driver and install it running update script
503 in the driver directory;
504 3. Run the application(s) which you used when you had found a
506 4. When application stops, look at you /var/log/messages file
507 (or whatever file you use to log kernel messages) and copy
508 all lines related to the driver activity to a separate file
509 in the same order of their appearence in your log file.
510 5. Mail a message to <mirsev@cicese.mx> with a subject
511 "Linux DC10(plus)/LML33/Buz driver bug report" with a detailed
512 description of your problem, kernel version, application name and
513 attach that file with kernel messages as plain text (please, don't
514 attach it using base64, uuencode, or any other encoding).
516 If you have a Buz card, please, also mail the same message to
517 Wolfgang Scherr <scherr@net4you.net>