 [English]
README.TXT                  MATROX GRAPHICS INC.              2000.08.29
  
                          BETA DRIVER FOR XFree86 4.0.1                    
                        

DESCRIPTION OF THIS RELEASE
===========================

This beta driver adds new features to the currently existing XFree86 mga
driver. It includes support for the Matrox G450, G400, and G200 graphics
adapters. Newly added features include DualHead, digital flat panel, and 
TV out support for the G400, DualHead support for the G450, and multiple
display support for the G200 Multi-Monitor series. This driver is also
programmed to set the internal clock speeds to production levels, increasing 
2D and 3D performance under Xfree86.

This driver can either be installed by adding the mga_drv.o module to a 
working installation of Xfree86 4.0.1, or by compiling the module from source.

The driver is for x86 based architectures only. Support for other
architectures is planned for future release. 

Please take note that this is a beta driver and is not supported by Matrox. 


NOTES
=====

The installation instructions in this document are based on Red Hat Linux
6.x. The directory locations and procedures listed may differ slightly when
working with other distributions.

This driver is based on the open source development being done within the
XFree86 Project. The driver remains unmodified, with the exception of the
display adapter initialization, which has been replaced with a closed
source Matrox library. This special library enables features such as
DualHead, TV out, and support for digital flat panel monitors.

Due to certain legal liabilities and for the protection of intellectual
property, Matrox reserves licensing rights to the library and prohibits
reverse engineering but allows free distribution under any operating system.
Matrox encourages members of the open source community to freely distribute
and assist in the further development of this driver.


INSTALLATION
============

A working installation of XFree86 4.0.1 is required before the driver can
be installed. The XFree86 source files and installation instructions are
available from http://www.xfree86.org/ 

Once Xfree86 4.0.1 is installed and working properly, the driver can be
installed by copying the mga_drv.o file into /usr/X11R6/lib/modules/drivers
(or wherever your X11R6 directory is located.)
It is recommended to back up the existing mga_drv.o file. The mv command
can be used to back up the mga_drv.o file as shown below.

      cd /usr/X11R6/lib/modules/drivers 
      mv mga_drv.o mga_drv.o_old



INSTALLATION FROM SOURCE
========================

To install the driver from source you will need to download and untar the
XFree86 4.0.1 source files, which are available from http://www.xfree86.org.
Once the XFree86 source tree has been extracted, the existing mga directory
should be backed up and renamed. This will be replaced by a new mga
directoy which will later be extracted from the driver source file. Use the
following command to back up the mga directory:

	cd /xc/programs/Xserver/hw/xfree86/drivers	
	mv mga mga_old

Now move or copy the mga driver source file into the /drivers directory and
extract the files by using the following command:

        tar xvzf mga_filename.tgz  


You will now need to create and edit a host.def file in the Xfree86 source
tree: 

	cd /xc/config/cf
	cp xf86site.def host.def
	
Using a text editor such as pico or emacs, insert the following line at the
bottom of the host.def file:

	#define UseMatroxHal YES

XFree86 can now be compiled normally. It is recommended that you save your
current XFree86 configuration by renaming the /USR/X11R6 directory, but
this is not necessary. It is possible to overwrite your old version of
XFree86 with version 4.0.1, however, this may cause problems such as
conflicting GL libraries left over from previous versions. To build and
install XFree86 4.0.1 go back to the /xc directory and enter the following
commands:

	make World    (this will take awhile)
	make install

Now that the source has been compiled and installed, the new XFree86 binary
needs to be linked to X: 

	cd /etc/X11/	

	ln -sf /usr/X11R6/bin/XFree86 ./X

If you are upgrading from Xfree86 3.3.6 or older, a new XF86Config file
needs to be created:

	cd /usr/X11R6/bin

	./xf86config 

The xf86config command will start a text based configuration program. The
values you specify here will determine the parameters for your mouse,
keyboard, monitor, and graphics card. This will create an XF86Config file
in /etc/X11, which will need to be edited later. Once the values you
specified have been saved, you will need to edit the XF86Config file to
include references to the newly supported features. 
	    

DRI
===

DRI is not enabled by default in XFree86 4.0.1. Direct rendering requires
agpgart support, therefore a recent development kernel needs to be
installed. When configuring the kernel make sure to enable support for
agpgart (as a module) and select the proper chipset. Disabling DRI support
in the kernel is recommended, since it is not required for direct rendering
to work.
Once the development kernel is installed and working properly, DRI can be
enabled from within the following directory:

/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel

Note: Unless your system is set up to load modules automatically, each time
the system is rebooted you will have to return to the /kernel directory to
load the mga.o module. It is recommended that you specify an alias for this
in the .bashrc file, or add the location to your path.

The mga.o module needs to be compiled and loaded from within the /kernel
directory. If you have an Xserver running it should be shut down before
compiling.

	make -f Makefile.linux mga.o
	insmod agpgart
	insmod mga.o
	lsmod (to make sure the modules are loaded) 

The XF86Cconfig file must now be configured to load dri: 

Section "Module"
 Load "glx"
 Load "dri"
EndSection 

# this section is optional
Section "DRI"
Group 4000
Mode 0666
EndSection 


After starting X there should be a "direct rendering enabled" message in
the Xserver startup log. Remember that dri will not be enabled if you are
using a dualhead configuration. You may want to keep two XF86Config files
on hand; one for dri and the other for dualhead.


DUALHEAD AND MULTIMONITOR
========================

To add DualHead support for the G450/G400 and multiple display support for
the G200 MultiMonitor boards, the following sections of the XF86Config file
need to be modified:

Graphics device section

Screen Sections

ServerLayout sections

Use the sample XF86Config files provided at the end of this document as an
example of what needs to be added to your config file. Take note of the
"BusID" lines. You will need to edit these to match the BusID output shown
in your Xfree86 log file. You can create a log file by redirecting the X
output to a text file: 

	startx >& Xoutput.log


The section of the output file which lists the BusID values will look
similar to the following example. Search the output file for "scanpci" to
find the PCI BusID's more quickly.

II) Loading /usr/X11R6/lib/modules/libscanpci.a
(II) Module scanpci: vendor="The XFree86 Project"
compiled for 4.0, module version = 0.1.0
(II) Unloading /usr/X11R6/lib/modules/libscanpci.a
(--) PCI:*(2:0:0) Matrox MGA G200 AGP rev 3, Mem @ 0xf0000000/24,
0xd2000000/14, 0xd0000000/23

Use the following command to start the Xserver in multi display mode:

	Startx -- +xinerama 


OTHER FEATURES
==============

Matrox is one of the first graphics chip companies to offer TV out
capabilities as well as support for digital flat panel monitors under
XFree86. This driver provides preliminary support for these features, while
improved performance and added features are planned for future releases. 

To add digital flat panel and TV out support the following lines must be
added to the device section of your XF86Config file (usually located in
/etc/X11/) 

Opt1on "Tv" "yes"

Option "DigitalScreen" "yes"

Both the TV out and digital flat panel features can be used either in clone
mode or virtual mode by using the xinerama extension. In order for the TV
out feature to work the display resolution must be set to 640x480 with a
refresh rate of 60Hz for NTSC. PAL support is not included in this version
but will be supported in a future release. The TV out feature can be
enabled with the G400 DualHead, the G200 Mystique, and the G200 Tvout
add-on module.

The DigitalScreen option can be enabled if you have a G400 digital flat
panel module. Digital flat panels generally require a vertical refresh of
50-60Hz.
The "Tv" and/or "DigitalScreen" option must be added to the second device
section of the XF86Config file. The example below is configured for clone
mode, in which the desktop is cloned on the second screen. If you wish to
span the desktop across two screens, the ServerLayout section must appear
as it does in Sample 1. Do not use the "Tv" and the "Digital Screen"
options together. You can disable one or the other by placing the # symbol
in front of the option you do not wish to use, or by simply excluding that
option from the config file.


Example: Clone Mode 

Section "Device"
    Identifier  "G400_1"
    Driver      "mga"
    BusID	"PCI:1:0:0"
    Screen	0
EndSection

Section "Device"
    Identifier  "G400_2"
    Driver      "mga"
    BusID	"PCI:1:0:0"
    Screen	1
    Option "Tv" "yes"
   #Option  "DigitalScreen "yes"       
EndSection


Section "ServerLayout"
     Identifier    "Layout1"
     Screen        "Screen0"
     Screen        "Screen1"
     InputDevice   "Mouse0" "CorePointer"
     InputDevice   "Keyboard0" "CoreKeyboard"
EndSection 



SAMPLE XF86Config FILES
===========================


 Sample 1: DualHead

# **********************************************************************
# Graphics device section
# **********************************************************************
Section "Device"
    Identifier  "G400_1"
    Driver      "mga"
    BusID	"PCI:1:0:0"
    Screen	0
EndSection

Section "Device"
    Identifier  "G400_2"
    Driver      "mga"
    BusID	"PCI:1:0:0"
    Screen	1       
EndSection


# **********************************************************************
# Screen sections
# **********************************************************************

# Any number of screen sections may be present.  Each describes
# the configuration of a single screen.  A single specific screen section
# may be specified from the X server command line with the "-screen"
# option.
Section "Screen"
    Identifier  "Screen 1"
    Device      "G400_1"
    Monitor     "Nokia"
    DefaultDepth 16

    Subsection "Display"
        Depth       8
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       16
        Modes       "1024x768" "800x600" "640x480"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       24
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
EndSection

Section "Screen"
    Identifier  "Screen 2"
    Device      "G400_2"
    Monitor     "Nokia"
    DefaultDepth 16

    Subsection "Display"
        Depth       8
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       16
        Modes       "1024x768" "800x600" "640x480"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       24
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
EndSection
# **********************************************************************
# ServerLayout sections.
# **********************************************************************

# Any number of ServerLayout sections may be present.  Each describes
# the way multiple screens are organized.  A specific ServerLayout
# section may be specified from the X server command line with the
# "-layout" option.  In the absence of this, the first section is used.
# When now ServerLayout section is present, the first Screen section
# is used alone.

Section "ServerLayout"

# The Identifier line must be present
    Identifier  "Simple Layout"

# Each Screen line specifies a Screen section name, and optionally
# the relative position of other screens.  The four names after
# primary screen name are the screens to the top, bottom, left and right
# of the primary screen.  In this example, screen 2 is located to the
# right of screen 1.

    Screen "Screen 1" LeftOf "Screen 2"
    Screen "Screen 2"

# Each InputDevice line specifies an InputDevice section name and
# optionally some options to specify the way the device is to be
# used.  Those options include "CorePointer", "CoreKeyboard" and
# "SendCoreEvents".

    InputDevice "Mouse1" "CorePointer"
    InputDevice "Keyboard1" "CoreKeyboard"

EndSection







Sample 2: G200 MultiMonitor

# **********************************************************************
# Graphics device section
# **********************************************************************

Section "Device"
    Identifier  "G200_1"
    Driver      "mga"
    BusID	"PCI:2:0:0"
    Option      "hw cursor" "off"
EndSection

Section "Device"
    Identifier  "G200_2"
    Driver      "mga"
    BusID	"PCI:2:4:0"
    Option      "hw cursor" "off"
EndSection

Section "Device"
    Identifier  "G200_3"
    Driver      "mga"
    BusID	"PCI:2:8:0"
    Option      "hw cursor" "off"
EndSection

Section "Device"
    Identifier  "G200_4"
    Driver      "mga"
    BusID	"PCI:2:12:0"
    Option      "hw cursor" "off"
EndSection

# **********************************************************************
# Screen sections
# **********************************************************************

# Any number of screen sections may be present.  Each describes
# the configuration of a single screen.  A single specific screen section
# may be specified from the X server command line with the "-screen"
# option.
Section "Screen"
    Identifier  "Screen 1"
    Device      "G200_1"
    Monitor     "NOKIA"
    DefaultDepth 16

    Subsection "Display"
        Depth       8
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       16
        Modes       "1024x768"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       24
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
EndSection

Section "Screen"
    Identifier  "Screen 2"
    Device      "G200_2"
    Monitor     "NOKIA"
    DefaultDepth 16

    Subsection "Display"
        Depth       8
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       16
        Modes       "1024x768"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       24
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
EndSection

Section "Screen"
    Identifier  "Screen 3"
    Device      "G200_3"
    Monitor     "NOKIA"
    DefaultDepth 16

    Subsection "Display"
        Depth       8
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       16
        Modes       "1024x768"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       24
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
EndSection
Section "Screen"
    Identifier  "Screen 4"
    Device      "G200_4"
    Monitor     "NOKIA"
    DefaultDepth 16

    Subsection "Display"
        Depth       8
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       16
        Modes       "1024x768"
        ViewPort    0 0
    EndSubsection
    Subsection "Display"
        Depth       24
        Modes       "640x480" "800x600" "1024x768" "1280x1024"
        ViewPort    0 0
    EndSubsection
EndSection

# **********************************************************************
# ServerLayout sections.
# **********************************************************************

# Any number of ServerLayout sections may be present.  Each describes
# the way multiple screens are organized.  A specific ServerLayout
# section may be specified from the X server command line with the
# "-layout" option.  In the absence of this, the first section is used.
# When now ServerLayout section is present, the first Screen section
# is used alone.

Section "ServerLayout"

# The Identifier line must be present
    Identifier  "Simple Layout"

# Each Screen line specifies a Screen section name, and optionally
# the relative position of other screens.  The four names after
# primary screen name are the screens to the top, bottom, left and right
# of the primary screen.  In this example, screen 2 is located to the
# right of screen 1.

    Screen "Screen 1" LeftOf "Screen 2"
    Screen "Screen 2" LeftOf "Screen 3"
    Screen "Screen 3" LeftOf "Screen 4"
    Screen "Screen 4"

# Each InputDevice line specifies an InputDevice section name and
# optionally some options to specify the way the device is to be
# used.  Those options include "CorePointer", "CoreKeyboard" and
# "SendCoreEvents".

    InputDevice "Mouse1" "CorePointer"
    InputDevice "Keyboard1" "CoreKeyboard"

EndSection




