blob: 01425c21986ba7ee03408f74537a36d2be7b2912 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001Frequently Asked Questions:
2===========================
3subject: unified zoran driver (zr360x7, zoran, buz, dc10(+), dc30(+), lml33)
4website: http://mjpeg.sourceforge.net/driver-zoran/
5
61. What cards are supported
71.1 What the TV decoder can do an what not
81.2 What the TV encoder can do an what not
92. How do I get this damn thing to work
103. What mainboard should I use (or why doesn't my card work)
114. Programming interface
125. Applications
136. Concerning buffer sizes, quality, output size etc.
147. It hangs/crashes/fails/whatevers! Help!
158. Maintainers/Contacting
169. License
17
18===========================
19
201. What cards are supported
21
22Iomega Buz, Linux Media Labs LML33/LML33R10, Pinnacle/Miro
23DC10/DC10+/DC30/DC30+ and related boards (available under various names).
24
25Iomega Buz:
26* Zoran zr36067 PCI controller
27* Zoran zr36060 MJPEG codec
28* Philips saa7111 TV decoder
29* Philips saa7185 TV encoder
30Drivers to use: videodev, i2c-core, i2c-algo-bit,
31 videocodec, saa7111, saa7185, zr36060, zr36067
32Inputs/outputs: Composite and S-video
33Norms: PAL, SECAM (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps)
34Card number: 7
35
36Linux Media Labs LML33:
37* Zoran zr36067 PCI controller
38* Zoran zr36060 MJPEG codec
39* Brooktree bt819 TV decoder
40* Brooktree bt856 TV encoder
41Drivers to use: videodev, i2c-core, i2c-algo-bit,
42 videocodec, bt819, bt856, zr36060, zr36067
43Inputs/outputs: Composite and S-video
44Norms: PAL (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps)
45Card number: 5
46
47Linux Media Labs LML33R10:
48* Zoran zr36067 PCI controller
49* Zoran zr36060 MJPEG codec
50* Philips saa7114 TV decoder
51* Analog Devices adv7170 TV encoder
52Drivers to use: videodev, i2c-core, i2c-algo-bit,
53 videocodec, saa7114, adv7170, zr36060, zr36067
54Inputs/outputs: Composite and S-video
55Norms: PAL (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps)
56Card number: 6
57
58Pinnacle/Miro DC10(new):
59* Zoran zr36057 PCI controller
60* Zoran zr36060 MJPEG codec
61* Philips saa7110a TV decoder
62* Analog Devices adv7176 TV encoder
63Drivers to use: videodev, i2c-core, i2c-algo-bit,
64 videocodec, saa7110, adv7175, zr36060, zr36067
65Inputs/outputs: Composite, S-video and Internal
66Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps)
67Card number: 1
68
69Pinnacle/Miro DC10+:
70* Zoran zr36067 PCI controller
71* Zoran zr36060 MJPEG codec
72* Philips saa7110a TV decoder
73* Analog Devices adv7176 TV encoder
74Drivers to use: videodev, i2c-core, i2c-algo-bit,
75 videocodec, sa7110, adv7175, zr36060, zr36067
76Inputs/outputs: Composite, S-video and Internal
77Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps)
78Card number: 2
79
80Pinnacle/Miro DC10(old): *
81* Zoran zr36057 PCI controller
82* Zoran zr36050 MJPEG codec
83* Zoran zr36016 Video Front End or Fuji md0211 Video Front End (clone?)
84* Micronas vpx3220a TV decoder
85* mse3000 TV encoder or Analog Devices adv7176 TV encoder *
86Drivers to use: videodev, i2c-core, i2c-algo-bit,
87 videocodec, vpx3220, mse3000/adv7175, zr36050, zr36016, zr36067
88Inputs/outputs: Composite, S-video and Internal
89Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps)
90Card number: 0
91
92Pinnacle/Miro DC30: *
93* Zoran zr36057 PCI controller
94* Zoran zr36050 MJPEG codec
95* Zoran zr36016 Video Front End
96* Micronas vpx3225d/vpx3220a/vpx3216b TV decoder
97* Analog Devices adv7176 TV encoder
98Drivers to use: videodev, i2c-core, i2c-algo-bit,
99 videocodec, vpx3220/vpx3224, adv7175, zr36050, zr36016, zr36067
100Inputs/outputs: Composite, S-video and Internal
101Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps)
102Card number: 3
103
104Pinnacle/Miro DC30+: *
105* Zoran zr36067 PCI controller
106* Zoran zr36050 MJPEG codec
107* Zoran zr36016 Video Front End
108* Micronas vpx3225d/vpx3220a/vpx3216b TV decoder
109* Analog Devices adv7176 TV encoder
110Drivers to use: videodev, i2c-core, i2c-algo-bit,
111 videocodec, vpx3220/vpx3224, adv7175, zr36050, zr36015, zr36067
112Inputs/outputs: Composite, S-video and Internal
113Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps)
114Card number: 4
115
116Note: No module for the mse3000 is available yet
117Note: No module for the vpx3224 is available yet
118Note: use encoder=X or decoder=X for non-default i2c chips (see i2c-id.h)
119
120===========================
121
1221.1 What the TV decoder can do an what not
123
124The best know TV standards are NTSC/PAL/SECAM. but for decoding a frame that
125information is not enough. There are several formats of the TV standards.
126And not every TV decoder is able to handle every format. Also the every
127combination is supported by the driver. There are currently 11 different
128tv broadcast formats all aver the world.
129
130The CCIR defines parameters needed for broadcasting the signal.
131The CCIR has defined different standards: A,B,D,E,F,G,D,H,I,K,K1,L,M,N,...
132The CCIR says not much about about the colorsystem used !!!
133And talking about a colorsystem says not to much about how it is broadcast.
134
135The CCIR standards A,E,F are not used any more.
136
137When you speak about NTSC, you usually mean the standard: CCIR - M using
138the NTSC colorsystem which is used in the USA, Japan, Mexico, Canada
139and a few others.
140
141When you talk about PAL, you usually mean: CCIR - B/G using the PAL
142colorsystem which is used in many Countries.
143
144When you talk about SECAM, you mean: CCIR - L using the SECAM Colorsystem
145which is used in France, and a few others.
146
147There the other version of SECAM, CCIR - D/K is used in Bulgaria, China,
148Slovakai, Hungary, Korea (Rep.), Poland, Rumania and a others.
149
150The CCIR - H uses the PAL colorsystem (sometimes SECAM) and is used in
151Egypt, Libya, Sri Lanka, Syrain Arab. Rep.
152
153The CCIR - I uses the PAL colorsystem, and is used in Great Britain, Hong Kong,
154Ireland, Nigeria, South Africa.
155
156The CCIR - N uses the PAL colorsystem and PAL frame size but the NTSC framerate,
157and is used in Argentinia, Uruguay, an a few others
158
159We do not talk about how the audio is broadcast !
160
161A rather good sites about the TV standards are:
162http://www.sony.jp/ServiceArea/Voltage_map/
163http://info.electronicwerkstatt.de/bereiche/fernsehtechnik/frequenzen_und_normen/Fernsehnormen/
164and http://www.cabl.com/restaurant/channel.html
165
166Other weird things around: NTSC 4.43 is a modificated NTSC, which is mainly
167used in PAL VCR's that are able to play back NTSC. PAL 60 seems to be the same
168as NTSC 4.43 . The Datasheets also talk about NTSC 44, It seems as if it would
169be the same as NTSC 4.43.
170NTSC Combs seems to be a decoder mode where the decoder uses a comb filter
171to split coma and luma instead of a Delay line.
172
173But I did not defiantly find out what NTSC Comb is.
174
175Philips saa7111 TV decoder
176was introduced in 1997, is used in the BUZ and
177can handle: PAL B/G/H/I, PAL N, PAL M, NTSC M, NTSC N, NTSC 4.43 and SECAM
178
179Philips saa7110a TV decoder
180was introduced in 1995, is used in the Pinnacle/Miro DC10(new), DC10+ and
181can handle: PAL B/G, NTSC M and SECAM
182
183Philips saa7114 TV decoder
184was introduced in 2000, is used in the LML33R10 and
185can handle: PAL B/G/D/H/I/N, PAL N, PAL M, NTSC M, NTSC 4.43 and SECAM
186
187Brooktree bt819 TV decoder
188was introduced in 1996, and is used in the LML33 and
189can handle: PAL B/D/G/H/I, NTSC M
190
191Micronas vpx3220a TV decoder
192was introduced in 1996, is used in the DC30 and DC30+ and
193can handle: PAL B/G/H/I, PAL N, PAL M, NTSC M, NTSC 44, PAL 60, SECAM,NTSC Comb
194
195===========================
196
1971.2 What the TV encoder can do an what not
198
199The TV encoder are doing the "same" as the decoder, but in the oder direction.
200You feed them digital data and the generate a Composite or SVHS signal.
201For information about the colorsystems and TV norm take a look in the
202TV decoder section.
203
204Philips saa7185 TV Encoder
205was introduced in 1996, is used in the BUZ
206can generate: PAL B/G, NTSC M
207
208Brooktree bt856 TV Encoder
209was introduced in 1994, is used in the LML33
210can generate: PAL B/D/G/H/I/N, PAL M, NTSC M, PAL-N (Argentina)
211
212Analog Devices adv7170 TV Encoder
213was introduced in 2000, is used in the LML300R10
214can generate: PAL B/D/G/H/I/N, PAL M, NTSC M, PAL 60
215
216Analog Devices adv7175 TV Encoder
217was introduced in 1996, is used in the DC10, DC10+, DC10 old, DC30, DC30+
218can generate: PAL B/D/G/H/I/N, PAL M, NTSC M
219
220ITT mse3000 TV encoder
221was introduced in 1991, is used in the DC10 old
222can generate: PAL , NTSC , SECAM
223
224The adv717x, should be able to produce PAL N. But you find nothing PAL N
225specific in the the registers. Seem that you have to reuse a other standard
226to generate PAL N, maybe it would work if you use the PAL M settings.
227
228==========================
229
2302. How do I get this damn thing to work
231
232Load zr36067.o. If it can't autodetect your card, use the card=X insmod
233option with X being the card number as given in the previous section.
234To have more than one card, use card=X1[,X2[,X3,[X4[..]]]]
235
236To automate this, add the following to your /etc/modprobe.conf:
237
238options zr36067 card=X1[,X2[,X3[,X4[..]]]]
239alias char-major-81-0 zr36067
240
241One thing to keep in mind is that this doesn't load zr36067.o itself yet. It
242just automates loading. If you start using xawtv, the device won't load on
243some systems, since you're trying to load modules as a user, which is not
244allowed ("permission denied"). A quick workaround is to add 'Load "v4l"' to
245XF86Config-4 when you use X by default, or to run 'v4l-conf -c <device>' in
246one of your startup scripts (normally rc.local) if you don't use X. Both
247make sure that the modules are loaded on startup, under the root account.
248
249===========================
250
2513. What mainboard should I use (or why doesn't my card work)
252
253<insert lousy disclaimer here>. In short: good=SiS/Intel, bad=VIA.
254
255Experience tells us that people with a Buz, on average, have more problems
256than users with a DC10+/LML33. Also, it tells us that people owning a VIA-
257based mainboard (ktXXX, MVP3) have more problems than users with a mainboard
258based on a different chipset. Here's some notes from Andrew Stevens:
259--
260Here's my experience of using LML33 and Buz on various motherboards:
261
262VIA MVP3
263 Forget it. Pointless. Doesn't work.
264Intel 430FX (Pentium 200)
265 LML33 perfect, Buz tolerable (3 or 4 frames dropped per movie)
266Intel 440BX (early stepping)
267 LML33 tolerable. Buz starting to get annoying (6-10 frames/hour)
268Intel 440BX (late stepping)
269 Buz tolerable, LML3 almost perfect (occasional single frame drops)
270SiS735
271 LML33 perfect, Buz tolerable.
272VIA KT133(*)
273 LML33 starting to get annoying, Buz poor enough that I have up.
274
275Both 440BX boards were dual CPU versions.
276--
277Bernhard Praschinger later added:
278--
279AMD 751
280 Buz perfect-tolerable
281AMD 760
282 Buz perfect-tolerable
283--
284In general, people on the user mailinglist won't give you much of a chance
285if you have a VIA-based motherboard. They may be cheap, but sometimes, you'd
286rather want to spend some more money on better boards. In general, VIA
287mainboard's IDE/PCI performance will also suck badly compared to others.
288You'll noticed the DC10+/DC30+ aren't mentioned anywhere in the overview.
289Basically, you can assume that if the Buz works, the LML33 will work too. If
290the LML33 works, the DC10+/DC30+ will work too. They're most tolerant to
291different mainboard chipsets from all of the supported cards.
292
293If you experience timeouts during capture, buy a better mainboard or lower
294the quality/buffersize during capture (see 'Concerning buffer sizes, quality,
295output size etc.'). If it hangs, there's little we can do as of now. Check
296your IRQs and make sure the card has its own interrupts.
297
298===========================
299
3004. Programming interface
301
302This driver conforms to video4linux and video4linux2, both can be used to
303use the driver. Since video4linux didn't provide adequate calls to fully
304use the cards' features, we've introduced several programming extensions,
305which are currently officially accepted in the 2.4.x branch of the kernel.
306These extensions are known as the v4l/mjpeg extensions. See zoran.h for
307details (structs/ioctls).
308
309Information - video4linux:
310http://roadrunner.swansea.linux.org.uk/v4lapi.shtml
311Documentation/video4linux/API.html
312/usr/include/linux/videodev.h
313
314Information - video4linux/mjpeg extensions:
315./zoran.h
316(also see below)
317
318Information - video4linux2:
319http://www.thedirks.org/v4l2/
320/usr/include/linux/videodev2.h
321http://www.bytesex.org/v4l/
322
323More information on the video4linux/mjpeg extensions, by Serguei
324Miridonovi and Rainer Johanni:
325--
326The ioctls for that interface are as follows:
327
328BUZIOC_G_PARAMS
329BUZIOC_S_PARAMS
330
331Get and set the parameters of the buz. The user should always do a
332BUZIOC_G_PARAMS (with a struct buz_params) to obtain the default
333settings, change what he likes and then make a BUZIOC_S_PARAMS call.
334
335BUZIOC_REQBUFS
336
337Before being able to capture/playback, the user has to request
338the buffers he is wanting to use. Fill the structure
339zoran_requestbuffers with the size (recommended: 256*1024) and
340the number (recommended 32 up to 256). There are no such restrictions
341as for the Video for Linux buffers, you should LEAVE SUFFICIENT
342MEMORY for your system however, else strange things will happen ....
343On return, the zoran_requestbuffers structure contains number and
344size of the actually allocated buffers.
345You should use these numbers for doing a mmap of the buffers
346into the user space.
347The BUZIOC_REQBUFS ioctl also makes it happen, that the next mmap
348maps the MJPEG buffer instead of the V4L buffers.
349
350BUZIOC_QBUF_CAPT
351BUZIOC_QBUF_PLAY
352
353Queue a buffer for capture or playback. The first call also starts
354streaming capture. When streaming capture is going on, you may
355only queue further buffers or issue syncs until streaming
356capture is switched off again with a argument of -1 to
357a BUZIOC_QBUF_CAPT/BUZIOC_QBUF_PLAY ioctl.
358
359BUZIOC_SYNC
360
361Issue this ioctl when all buffers are queued. This ioctl will
362block until the first buffer becomes free for saving its
363data to disk (after BUZIOC_QBUF_CAPT) or for reuse (after BUZIOC_QBUF_PLAY).
364
365BUZIOC_G_STATUS
366
367Get the status of the input lines (video source connected/norm).
368
369For programming example, please, look at lavrec.c and lavplay.c code in
370lavtools-1.2p2 package (URL: http://www.cicese.mx/~mirsev/DC10plus/)
371and the 'examples' directory in the original Buz driver distribution.
372
373Additional notes for software developers:
374
375 The driver returns maxwidth and maxheight parameters according to
376 the current TV standard (norm). Therefore, the software which
377 communicates with the driver and "asks" for these parameters should
378 first set the correct norm. Well, it seems logically correct: TV
379 standard is "more constant" for current country than geometry
380 settings of a variety of TV capture cards which may work in ITU or
381 square pixel format. Remember that users now can lock the norm to
382 avoid any ambiguity.
383--
384Please note that lavplay/lavrec are also included in the MJPEG-tools
385(http://mjpeg.sf.net/).
386
387===========================
388
3895. Applications
390
391Applications known to work with this driver:
392
393TV viewing:
394* xawtv
395* kwintv
396* probably any TV application that supports video4linux or video4linux2.
397
398MJPEG capture/playback:
399* mjpegtools/lavtools (or Linux Video Studio)
400* gstreamer
401* mplayer
402
403General raw capture:
404* xawtv
405* gstreamer
406* probably any application that supports video4linux or video4linux2
407
408Video editing:
409* Cinelerra
410* MainActor
411* mjpegtools (or Linux Video Studio)
412
413===========================
414
4156. Concerning buffer sizes, quality, output size etc.
416
417The zr36060 can do 1:2 JPEG compression. This is really the theoretical
418maximum that the chipset can reach. The driver can, however, limit compression
419to a maximum (size) of 1:4. The reason for this is that some cards (e.g. Buz)
420can't handle 1:2 compression without stopping capture after only a few minutes.
421With 1:4, it'll mostly work. If you have a Buz, use 'low_bitrate=1' to go into
4221:4 max. compression mode.
423
424100% JPEG quality is thus 1:2 compression in practice. So for a full PAL frame
425(size 720x576). The JPEG fields are stored in YUY2 format, so the size of the
426fields are 720x288x16/2 bits/field (2 fields/frame) = 207360 bytes/field x 2 =
427414720 bytes/frame (add some more bytes for headers and DHT (huffman)/DQT
428(quantization) tables, and you'll get to something like 512kB per frame for
4291:2 compression. For 1:4 compression, you'd have frames of half this size.
430
431Some additional explanation by Martin Samuelsson, which also explains the
432importance of buffer sizes:
433--
434> Hmm, I do not think it is really that way. With the current (downloaded
435> at 18:00 Monday) driver I get that output sizes for 10 sec:
436> -q 50 -b 128 : 24.283.332 Bytes
437> -q 50 -b 256 : 48.442.368
438> -q 25 -b 128 : 24.655.992
439> -q 25 -b 256 : 25.859.820
440
441I woke up, and can't go to sleep again. I'll kill some time explaining why
442this doesn't look strange to me.
443
444Let's do some math using a width of 704 pixels. I'm not sure whether the Buz
445actually use that number or not, but that's not too important right now.
446
447704x288 pixels, one field, is 202752 pixels. Divided by 64 pixels per block;
4483168 blocks per field. Each pixel consist of two bytes; 128 bytes per block;
4491024 bits per block. 100% in the new driver mean 1:2 compression; the maximum
450output becomes 512 bits per block. Actually 510, but 512 is simpler to use
451for calculations.
452
453Let's say that we specify d1q50. We thus want 256 bits per block; times 3168
454becomes 811008 bits; 101376 bytes per field. We're talking raw bits and bytes
455here, so we don't need to do any fancy corrections for bits-per-pixel or such
456things. 101376 bytes per field.
457
458d1 video contains two fields per frame. Those sum up to 202752 bytes per
459frame, and one of those frames goes into each buffer.
460
461But wait a second! -b128 gives 128kB buffers! It's not possible to cram
462202752 bytes of JPEG data into 128kB!
463
464This is what the driver notice and automatically compensate for in your
465examples. Let's do some math using this information:
466
467128kB is 131072 bytes. In this buffer, we want to store two fields, which
468leaves 65536 bytes for each field. Using 3168 blocks per field, we get
46920.68686868... available bytes per block; 165 bits. We can't allow the
470request for 256 bits per block when there's only 165 bits available! The -q50
471option is silently overridden, and the -b128 option takes precedence, leaving
472us with the equivalence of -q32.
473
474This gives us a data rate of 165 bits per block, which, times 3168, sums up
475to 65340 bytes per field, out of the allowed 65536. The current driver has
476another level of rate limiting; it won't accept -q values that fill more than
4776/8 of the specified buffers. (I'm not sure why. "Playing it safe" seem to be
478a safe bet. Personally, I think I would have lowered requested-bits-per-block
479by one, or something like that.) We can't use 165 bits per block, but have to
480lower it again, to 6/8 of the available buffer space: We end up with 124 bits
481per block, the equivalence of -q24. With 128kB buffers, you can't use greater
482than -q24 at -d1. (And PAL, and 704 pixels width...)
483
484The third example is limited to -q24 through the same process. The second
485example, using very similar calculations, is limited to -q48. The only
486example that actually grab at the specified -q value is the last one, which
487is clearly visible, looking at the file size.
488--
489
490Conclusion: the quality of the resulting movie depends on buffer size, quality,
491whether or not you use 'low_bitrate=1' as insmod option for the zr36060.c
492module to do 1:4 instead of 1:2 compression, etc.
493
494If you experience timeouts, lowering the quality/buffersize or using
495'low_bitrate=1 as insmod option for zr36060.o might actually help, as is
496proven by the Buz.
497
498===========================
499
5007. It hangs/crashes/fails/whatevers! Help!
501
502Make sure that the card has its own interrupts (see /proc/interrupts), check
503the output of dmesg at high verbosity (load zr36067.o with debug=2,
504load all other modules with debug=1). Check that your mainboard is favorable
505(see question 2) and if not, test the card in another computer. Also see the
506notes given in question 3 and try lowering quality/buffersize/capturesize
507if recording fails after a period of time.
508
509If all this doesn't help, give a clear description of the problem including
510detailed hardware information (memory+brand, mainboard+chipset+brand, which
511MJPEG card, processor, other PCI cards that might be of interest), give the
512system PnP information (/proc/interrupts, /proc/dma, /proc/devices), and give
513the kernel version, driver version, glibc version, gcc version and any other
514information that might possibly be of interest. Also provide the dmesg output
515at high verbosity. See 'Contacting' on how to contact the developers.
516
517===========================
518
5198. Maintainers/Contacting
520
521The driver is currently maintained by Laurent Pinchart and Ronald Bultje
522(<laurent.pinchart@skynet.be> and <rbultje@ronald.bitfreak.net>). For bug
523reports or questions, please contact the mailinglist instead of the developers
524individually. For user questions (i.e. bug reports or how-to questions), send
525an email to <mjpeg-users@lists.sf.net>, for developers (i.e. if you want to
526help programming), send an email to <mjpeg-developer@lists.sf.net>. See
527http://www.sf.net/projects/mjpeg/ for subscription information.
528
529For bug reports, be sure to include all the information as described in
530the section 'It hangs/crashes/fails/whatevers! Help!'. Please make sure
531you're using the latest version (http://mjpeg.sf.net/driver-zoran/).
532
533Previous maintainers/developers of this driver include Serguei Miridonov
534<mirsev@cicese.mx>, Wolfgang Scherr <scherr@net4you.net>, Dave Perks
535<dperks@ibm.net> and Rainer Johanni <Rainer@Johanni.de>.
536
537===========================
538
5399. License
540
541This driver is distributed under the terms of the General Public License.
542
543 This program is free software; you can redistribute it and/or modify
544 it under the terms of the GNU General Public License as published by
545 the Free Software Foundation; either version 2 of the License, or
546 (at your option) any later version.
547
548 This program is distributed in the hope that it will be useful,
549 but WITHOUT ANY WARRANTY; without even the implied warranty of
550 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
551 GNU General Public License for more details.
552
553 You should have received a copy of the GNU General Public License
554 along with this program; if not, write to the Free Software
555 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
556
557See http://www.gnu.org/ for more information.