zoran

《嵌入式系统设计与实例开发实验教材二源码》Linux内核移植与编译实验

# 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<set your input and norm here> (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  [e-mail].
Unsubscribe with a message (with "unsubscribe" in the subject) to
[e-mail]. 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 <[e-mail]> 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 <[e-mail]>