mgavideo README

Copyright (C) 1999 Ryan Drake (stiletto@mediaone.net)  See COPYING.


Generic all-caps "cover my ass" statement:
------------------------------------------

************************************************************************
THIS RELEASE IS FOR SERIOUS KERNEL HACKERS ONLY.  IT IS NOT INTENDED FOR
EVERYDAY USERS.  THIS IS NOT BETA CODE.  THIS IS NOT EVEN ALPHA CODE.
IT IS AN EXPERIMENTAL DEVICE DRIVER, SO HANDLE IT WITH CARE.  IF YOU
DON'T KNOW WHAT YOU ARE DOING YOU SHOULDN'T BE USING THIS YET.
************************************************************************

Once it is more stable, and I am sure it won't blow up anyone's computer,
I will make a more public release, but for now, use it at your own risk.


New from last release:
----------------------

        Read the CHANGELOG.
        Read apps/appsreadme.txt <--------- (please do this!)

        Some new apps.  One to change the tv channel and one to turn preview
        window on and off.  Read apps/appsreadme.txt

        insmod parameter for setting your video memory size.  Hopefully this
        will help the driver play nice at high resolutions/color depths.

        Support for setting contrast, brightness and hue--saturation is next.

        Backend scaler colorkeying support added.  I've turned off normal
        non-colorkeying overlay, but eventually we will support both and glue
        it to v4l2.


        NOTE! - I have only tested this in the following environment:
                Desktop resolution: 1024x768x16bit
                Briefly tested in: 32bit
                Video card: Matrox Marvel 8MB
                Video input: Composite line-in, and TV Tuner
                Video format: NTSC

                I'd love to hear from people who have gotten this working
                on other configurations, but I doubt it will "just work" at
                this stage in the game.


What you get in this tarball:
-----------------------------

        mgavideo.c - this module is the interface to the G100 and G200's video
        mgavideo.h - extension registers.  It also registers itself as an i2c
                     bus, and includes an api for sending commands to each
                     of the devices on the i2c (currently there is support
                     for the ks0127, the msp3400, and the TV tuner).

        ks0127.c   - this module is an interface to the KS0127 video decoder
        ks0127.h   - chip, which is used on the Matrox Rainbow Runner-G series
                     cards, and the Matrox Marvel card.

        maven.c    - Skeleton driver for the Maven TV-out.  Currently does
        maven.h    - nothing but detect the chip.

        i2c.c      - These files are all from the Linux 2.2.7 kernel.  They
        tuner.h    - will compile and work fine, as long as you have a 2.2
        msp3400.h  - version of the kernel installed with the ORIGINAL FILES.
                   - More on this below...
        
        i2c.h      - These files were also taken from the Linux 2.2.7 kernel.
        tuner.c    - They needed to be patched to support the Matrox cards.
        msp3400.c  - Hopefully I can get the patched versions back into the
                     kernel.

        videodev2.h- I've just gone and renamed the videodev.h from V4L2 to
                     this, so not to confuse the drivers that still need
                     V4L1's videodev.h.

        v4l2cap.c  - Video4Linux2 interface to this driver.  This need a lot
                     of work, but for now it works OK.
                     
        i, r       - Two very simple shell scripts I cooked up to easily
                     install and remove the drivers.  You can probably guess
                     which one is which.

        Makefile   - you know what this is for

        apps/*     - Sample V4L2 apps.


So how do I build this thing:
-----------------------------

        Make sure you have the Linux kernel source installed.  You need this.
        I've tested it on 2.2.7, but it should work for all versions 2.0 and
        above.  If it doesn't I'd like to know.

        Run make:
                make

        As root, run my "i" script, or insmod them yourself if my script
        doesn't work, or if you don't trust it :)
                ./i

        Back as a normal user, run the xcaptest that was just built.  Other
        versions of xcaptest wont work so make sure you get the right one:
                ./xcaptest

        A strange bug I just recently started seeing.  Sometimes it won't
        work the first time you load the modules.  I don't know why.
        The solution is to unload the modules:
                ./r
        And then reload them.  That should fix it.

        If things don't work, it may be helpful to open up an xconsole and
        have a look at what's going on.  All of the driver .c files have
        a line  int debug = 0;  And if you change any of these to = 1, you
        can get even more debug information.

        Again, this stuff could mess up your card if it doesn't work right
        so make sure you know what you're doing before running them.


What needs to be done:
----------------------

        APPS NEEDED!  If you are a bored hacker trying to think of a cool
        project, we could use a nice V4L2-capable video displayer that
        supports capture, preview, TV tuner (including channel changes.. see
        freq.c) ... all that good stuff.  Something with a nice shiny GTK+
        GUI or whatever would be ideal!  I know this is just wishful thinking
        but I'll put the request out for the record ;-)

        Implement other V4L2 devices.  V4L2 can interface to other kinds of
        devices besides video.  From what I can tell, we can probably implement
        /dev/codec, /dev/vout, /dev/radio, and /dev/vbi, in addition to the
        currently implemented /dev/video.

        Work on Maven support.  Any volunteers?

        
Extra:
------

        Anyone know if the Maven TVOut spec is available anywhere?

        The mgavideo module contains basic code to set up the video capture
        and vbi windows, and to start and stop the grabber.  Matrox has
        released specs for the G200 chip, which you can get here:

        http://www.matrox.com/mga/dev_relations/chips_tech/mga-g200.htm

        You need to register to get the specs, and it doesn't cost anything
        to get them.

        The KS0127 module works, but will need more features implemented
        in order to be very useful.  Specs for this chip can be found here:

        http://www.usa.samsungsemi.com/products/prodspec/videodecoder/KS0127/ks0127ov.htm 



Ryan Drake
stiletto@mediaone.net
