[English]
README.TXT              MATROX GRAPHICS INC.             2001.10.12

                   Matrox beta drivers for XFree86
                       Version 1.3.2 / 1.4.2


Contents
========

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


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

This release of the Matrox display driver includes support for 
Matrox G550 graphics hardware. It's also compatible with Matrox 
PowerDesk for Linux. Matrox G200-, G400-, and G450-based graphics 
hardware is also supported.

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. To use this 
feature you also need the latest version of Matrox PowerDesk, which 
is available from the Matrox Web site (www.matrox.com/mga).


Notes
=====

The display drivers included in this package support XFree86 
4.0.2, 4.0.3, and 4.1.0. Two driver versions are included -- 
driver  1.3.2 supports XFree86 4.0.2 AND 4.0.3, and driver 1.4.2 
supports XFree86 4.1.0. The installation procedure described in 
this document automatically chooses the appropriate driver.

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

Matrox PowerDesk is software to help you configure display 
settings for Matrox graphics hardware under XFree86. With this 
software, you can more easily adjust display resolutions, color 
palettes, refresh rates, and display positioning. With PowerDesk, 
you can also enable special Matrox features such as DualHead, DVI, 
and TV output. Matrox PowerDesk software for Linux is available 
for download from the Matrox Web site (www.matrox.com/mga). For 
more information, see the "Readme" file included with 
PowerDesk.

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 MMS 
products, and for DVI support with G550 products. It's also needed 
for certain PowerDesk features such as adjusting refresh rates, 
display positioning, and the "DualHead Multi-Display - Merged" 
feature. The HAL library isn't required for just DualHead support 
(without a DVI monitor) with G450- and G550-based graphics 
hardware. (With Linux, TV output isn't supported with G450- and 
G550-based graphics hardware.)

The DualHead Multi-Display - Merged feature is available on G450- 
and G550- based products only.

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 7.1. The directory locations and procedures listed may 
differ slightly with other distributions.



Binary installation
===================

A working installation of XFree86 4.1.0, 4.0.3, or 4.0.2 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 install script as "root":

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

If you're using XFree86 4.1.0, you're also given the option of
replacing the DRI module ("mga_dri.so") with an updated version. 
This new version contains a multi-texturing fix that should 
improve performance with certain 3D accelerated games such as 
Tribes II and Descent 3.

The installation script makes a back-up copy of "mga_drv.o" and, 
if it exists, of "mga_hal_drv.o". To restore your original 
drivers, simply run the script with the "restore" option 
specified:

  sh install.sh restore


Installation from source
========================

The driver source code is provided for those who are upgrading 
XFree86 from source and want to compile the Matrox driver 
simultaneously. Please note that compiling the driver from source 
isn't necessary as the binary Matrox drivers can be installed 
after the upgrade is complete. Installing the binary drivers is 
the recommended method of installation for most users.

To install the driver from source, you need the XFree86 source 
files. These files are available for download at the XFree86 
Project, Inc Web site (www.xfree86.org).

After the XFree86 source files have been extracted, the 
existing "mga" directory should be backed up and renamed. This is 
replaced by the new "mga" directory, which is extracted from the 
driver source file. Use the following commands to backup the "mga" 
directory:

  cd /xc/programs/Xserver/hw/xfree86/drivers

  mv mga mga_old

Now move or copy the Matrox driver source file into the drivers 
directory and extract the files by using the following command
where <mga_filename> is the name of the driver file you want to 
extract:

  tar xvzf <mga_filename>.tgz

IMPORTANT: If you want to use the HAL library, you need to create 
and edit a "host.def" file from within the XFree86 source tree:

  cd /xc/config/cf

  cp xf86site.def host.def

Using a text editor (for example, "vi", "emacs", or "pico"), 
uncomment the "HaveMatroxHal" line in the "host.def" file by 
removing the "*/" comment from the line after "HaveMatroxHal" and 
placing it at the end of the previous line. Here is an example of 
how this section should appear after it has been edited:

  /*
    * If you have the HALlib.a binary installed in
    * xfree86/drivers/mga/HALlib,
    * uncomment this:
  */
  #define HaveMatroxHal   YES

If this seems confusing, you may prefer to simply insert the 
following line at the bottom of the "host.def" file:

  #define HaveMatroxHal YES

Note: The option "#define UseMatroxHal" is also required, but 
should already be enabled by default in the "host.def" file.

If you have Matrox G550-base graphics hardware, you need to modify 
one of the XFree86 source files to support your graphics hardware:

  cd /xc/programs/Xserver/hw/xfree86/common

Using a text editor, edit the file "xf86PciInfo.h". In the example 
below, the "vi" text editor is used.

  vi xf86PciInfo.h

Search for "G400", which appears in two places. You need to add a 
G550 entry in both locations. You can perform a search in "vi" by 
typing "/G400" and then use the "n" key to find the next G400 
entry.

After the first G400 entry, add a G550 line as shown below:

  #define PCI_CHIP_MGAG400 0x0525
  #define PCI_CHIP_MGAG550 0x2527

The next G400 entry appears as follows. Again, you need to add the 
G550 line (as shown) directly below it:

  {PCI_CHIP_MGAG400, "MGA G400 AGP", 0},
  {PCI_CHIP_MGAG550, "MGA G550 AGP", 0},

To compile and install XFree86, go back to the "/xc" directory and 
enter the following commands:

  make World

  make install

The "make World" command may take a long time. After the source 
has been compiled and installed, the new XFree86 binary may need 
to be linked to X:

  cd /etc/X11

  ls -l X

This shows which binary X is linked to. If it lists anything other 
than XFree86, you can link it to 4.x.x by using the following 
command:

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

If you're upgrading from XFree86 3.3.6 or older, a new 
"XF86Config" file needs to be created.

  cd /usr/X11R6/bin

  ./xf86config

The "xf86config" command starts a text-based configuration 
program. The values you specify here determine the parameters for 
your mouse, keyboard, monitor, and graphics hardware. This creates 
an "XF86Config" file in "/etc/X11", which needs to be edited 
later. If newer graphics hardware (for example, Matrox G450 or 
G550) isn't listed when choosing a graphics device, it's safe to 
choose other graphics hardware that uses the Matrox display driver 
(for example, Matrox G200). After the values you specified have 
been saved, you need to edit the "XF86Config" file to include 
references to the newly supported features.

Note: Some Linux distributions install more than one version of 
XFree86. If XFree86 4.0. or higher is installed on your system, 
you may already have a config file specific to that version. For 
example, if your Linux distribution has installed both XFree86 
3.3.6 and 4.0.1, there's likely to be a separate config file for 
each in "/etc/X11"; "XF86Config" for 3.3.6, and "XF86Config-4" 
for 4.0.1.

If the X server doesn't start after the upgrade, you may need to 
run "ldconfig". Although running "ldconfig" should get your X 
server running, it may cause problems with linked GL libraries. If 
you experience problems, such as "segfault" errors when running 3D 
accelerated programs such as "glxgears" and "glxinfo", you may 
need to reinstall the GL libraries from the XFree86 source tree:

  cd ../xc/lib/GL

  make install


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 MMS support
=============================

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

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

With G400-, G450-, and G550-based graphics hardware, we strongly 
recommend using the Matrox PowerDesk software to enable DualHead 
features. (G200 MMS products currently aren't supported by 
PowerDesk.)

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 enable these features using Matrox PowerDesk software. 
Alternatively, 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:

  Option "DigitalScreen" "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"
    # Option    "DigitalScreen "yes"
EndSection

Section "ServerLayout"
     Identifier "Layout1"
     Screen     "Screen0"
     Screen     "Screen1"
     Option     "Xinerama"
     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 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 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


