[English]
README.TXT              MATROX GRAPHICS INC.             2006.07.25

                   Matrox Beta Drivers For XFree86
                        Package Version: 4.4.0


Contents
========

- Description of this release
- Notes
- Binary installation
- Installation from source
- DRI
- DualHead and G200/G450 MMS support
- Other features
- Sample configuration files


Description of this release
===========================

This release of the Matrox display driver includes support for 
Matrox G200, G400, G450 and G550 based graphics hardware.

This driver package includes previously released drivers for XFree86 
versions 4.3.0 and X.org versions 6.7.0, 6.8.0, 6.8.1, 6.8.2, 6.9.0
and 7.0.0


Notes
=====

The included display drivers are based on the Matrox driver source 
included with XFree86. Modifications made by Matrox include the 
addition of the Matrox HAL library, which can be optionally 
installed to enable Matrox specific features.

This display driver supports the option of using your main and 
secondary displays as if they were a single display ("merged" 
displays) divided between your two monitors. If your system is 
configured for 3D acceleration, this feature allows for 3D 
acceleration on both your displays at the same time. 

The DualHead Multi-Display - Merged feature is available on G450- 
and G550- based products only. Please take note that this feature 
does not support DVI monitors in XFree86 4.3.0, and X.org versions  
6.7.0, 6.8.0, 6.8.1, 6.8.2, 6.9.0, 7.0.0. 

The Matrox HAL ("Hardware Abstraction Layer") is a special library 
to enable features not supported by the standard XFree86 driver. 
It's required for DualHead, TV output, and DVI support with G400- 
based graphics hardware, for multi-display support with G200/G450 MMS 
products, and for DVI support. The HAL library is not required for 
basic DualHead support (without a DVI monitor) with G450- and G550-based 
graphics hardware. Also please take not that TV output is not supported 
with G450- and G550- based graphics hardware in Linux.


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.

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

Note: 
1) Digital support currently doesn't work with X.org v6.7.0 under
   Fedora Core 2. Installing X.org v6.7.0 from X.org sources seems
   to fix the issue when used with the matrox binaries provided
   here-in.
2) Vesa consoles do not currently work on PCIe G550 based cards.
   To get a working console requires setting lilo/grub to use 
   vga=normal giving a text only console (80x25).


Binary install
==============

A working installation of XFree86 4.3.0, and X.org versions 6.7.0, 
6.8.0, 6.8.1, 6.8.2, 6.9.0, 7.0.0 is required before the binaries 
can be installed.

To extract the driver files, enter the following command where 
<mga_filename> is the name of the driver file you want to extract:

  tar xvzf <mga_filename>.tgz

  cd mgadrivers

To install the drivers, run the script as "root" with no option:

  sh install.sh

The install script prompts you to install both the XFree86 2D 
driver ("mga_drv.o") and the HAL library ("mga_hal_drv.o"). Unless 
otherwise specified, these files are placed in 
"/usr/X11R6/lib/modules/drivers".

The installation script makes a back-up copy of "mga_drv.o" and, 
if it exists, of "mga_hal_drv.o". 


Binary uninstall
================

To extract the driver files, enter the following command where 
<mga_filename> is the name of the driver file you want to extract:

  tar xvzf <mga_filename>.tgz

  cd mgadrivers

To uninstall the drivers, run the script as "root" with -uninstall:

  sh install.sh -uninstall

The script prompts you to choose uninstall, restore or cancel. At
which point choose the uninstall option to remove the current
driver files.


Binary restore
==============

To extract the driver files, enter the following command where 
<mga_filename> is the name of the driver file you want to extract:

  tar xvzf <mga_filename>.tgz

  cd mgadrivers

To restore a previously backed up driver, run the script as "root":

  sh install.sh -restore

The script will ask you whether to proceed or not. Choosing yes
will restore the last backed up files.


DRI
===

DRI ("Direct Rendering Infrastructure") enables hardware-based 3D 
acceleration under Linux. DRI requires a 2.4.x kernel with 
"agpgart" support. If you're using an older kernel that doesn't 
include "agpgart" support, you need to upgrade to a newer version 
to enable DRI acceleration. Most recent Linux distributions 
automatically enable DRI support through the kernel during setup. 
Although it's disabled by default, XFree86 also contains the files 
necessary to enable DRI. You can find out if DRI is enabled by 
looking at the output created when starting X. An X output file 
can be created by typing:

  startx >& Xoutput.log

Look for the "direct rendering" line, which tells you whether DRI 
is enabled or disabled. You can also use a utility called 
"glxinfo" to determine whether or not DRI is enabled. If you don't 
have "glxinfo" installed, you can get the source code from the 
resources section of the DRI Web site 
(http://dri.sourceforge.net/)

If direct rendering is disabled, it may be possible that the 
module exists but isn't loading. From a console or terminal, type:

  lsmod

This lists the modules loaded. If "agpgart" and "mga" are on the 
list then DRI should be enabled. If they aren't listed, you can 
load them manually using the following commands:

  insmod agpgart

  insmod mga

  lsmod (agpgart and mga should now appear on the list)

The "insmod" command loads the "mga.o" module if it exists and is 
located in the proper directory. The "lsmod" command lists all of 
the modules currently loaded. This doesn't include modules built 
into the kernel. If "lsmod" shows that the "mga" and "agpgart" 
modules are loaded, then the X output log file should state that 
direct rendering is enabled.

If you've upgraded XFree86 and can't load DRI because of a version 
mismatch error, you need to compile and install a new "mga.o" 
module from within the XFree86 source tree. This can only be done 
if you have the XFree86 source code installed, which isn't 
included with XFree86 binary RPM ("Red Hat Package Manager") 
packages. The kernel source must also be installed.

Here are the instructions for compiling and installing a new 
"mga.o" module:

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

  make -f Makefile.linux mga.o

  insmod agpgart

  insmod mga.o

  lsmod (to make sure the modules are loaded)

You may want to copy the "mga.o" module into the proper kernel 
modules directory. This should be located in one of the following 
locations:

  /lib/modules/your_kernel_version/kernel/drivers/char/drm/

  /lib/modules/your_kernel_version/misc/

This should allow you to load the module from within any directory 
by using the "lsmod" command. Otherwise, you have to return to the 
kernel directory each time you want to reload "mga.o". If there's 
already an older "mga.o" module in the "misc" directory, you may 
want to make a backup before installing the new version. You can 
also have the "agpgart" and "mga.o" modules load automatically 
each time you restart Linux by inserting "insmod agpgart" and 
"insmod mga" at the bottom of "/etc/rc.local":

You can then configure the "XF86Config" file to load DRI. These 
lines may already be in the "Module" section of your "XF86Config" 
file:

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

After starting X, there should be a "direct rendering enabled" 
message in the X server startup log. Please note that DRI isn't 
enabled if you're using the Xinerama extension. You may want to 
keep two "XF86Config" files on hand -- one for DRI and the other 
for DualHead.

For more information on DRI, please visit the DRI project home 
page (http://dri.sourceforge.net/).


DualHead and G200/G450 MMS support
==================================

To add DualHead support for the G400/G450/G550-based graphics 
hardware and multi-display support for G200/G450 MMS products, the 
following sections of the "XF86Config" file need to be modified:

- "Device" section
- "Screen" section
- "ServerLayout" section

Note that on some systems when using the G450 MMS, the following
line may need to be added to each device section to avoid display
corruption:

Option "MGASDRAM"

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 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 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

Note: The Xinerama extension can be set up to load automatically 
by adding the following line to the "ServerLayout" section of the 
"XF86Config" file:

  Option "Xinerama"


Other features
==============

For G400-based graphics hardware with TV output or G400/G550-based 
graphics hardware with DVI (digital flat panel monitor) support, you 
can manually enable these features using the instructions below.

Note: With Linux, TV output isn't supported with G450- and G550- 
based graphics hardware.

To add TV output, add the following line to the device section of 
your "XF86Config" file (usually located in "/etc/X11/"):

  Option "TV" "yes"

To add DVI support, add the following line to the device section
(Note: For G400 with the DVI module you will need to use the
DigitalScreen2 option on the secondary device for it to enable):

  Option "DigitalScreen1" "yes"

    or

  Option "DigitalScreen2" "yes"

For TV output, the default TV standard is NTSC (used in North 
America and Japan, among other places). To use the PAL TV standard 
(used in Western Europe and China, among other places), add the 
following line to the device section:

  Option "TVStandard" "PAL"

The default cable type for TV output is Composite/S-video. To use 
a SCART cable type, add *one* of the following lines to the device 
section:

  Option "CableType" "SCART_RGB"

  Option "CableType" "SCART_COMPOSITE"

  Option "CableType" "SCART_TYPE2"

With the Xinerama extension, you can use TV output or DVI output 
in "DualHead Clone" mode or in "virtual" mode. For TV output to 
work, the display resolution must be set to 640 x 480 and the 
refresh rate must be set to 60 Hz for NTSC or 50 Hz for PAL.

If you have a G400 digital flat panel module or G550-based 
graphics hardware, you can enable the "DigitalScreen" option. 
Digital flat panels generally require a vertical refresh of 50 to 
60 Hz. The "Tv" and/or "DigitalScreen" option must be added to the 
second device section of the "XF86Config" file. The example below 
is configured for "DualHead Clone" mode. (With this feature, you 
can view a copy of your main display on your secondary display.) 
If you want to span the desktop across two displays, the 
"ServerLayout" section must appear as it does in Sample 1. Don't 
use the "Tv" and "Digital Screen" options together. You can 
disable one or the other by placing the "#" symbol in front of the 
option you don't want 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"
EndSection

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

How the driver exits to console either int10 mode 3 (default 80x25 text 
mode) or the old style vga mode can be controlled by the use of the 
UseMode3Vga option. Using this option would return to vga using the 
int10 mode 3 return mode.

For example :

Section "Device"
    Identifier  "G400_1"
    Driver      "mga"
    BusID       "PCI:1:0:0"
    Option      "UseMode3Vga" "on"
    Screen      0
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 display. A single specific 
# "Screen" section may be specified from the X server command line 
# with the "-screen" option.

Section "Screen"
    Identifier  "Screen 0"
    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 1"
    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 displays 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 displays. The four
# names after main "Screen" name are the displays to the top,
# bottom, left, and right of the primary display. In this example,
# "Screen" 2 is located to the right of "Screen" 1.

    Screen "Screen 0" LeftOf "Screen 1"
    Screen "Screen 1"

# 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/G450 Multi-Monitor
---------------------------------
# *****************************************************************
# 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 display. 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 displays 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 displays. The four
# names after primary name are the displays to the top, right
# of the primary display. In this example, display 2 is  bottom,
# left and located to the right of display 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