[English]
README.TXT               MATROX GRAPHICS INC.            2001.07.11

                      Matrox driver for XFree86
                        Version 1.3.1 / 1.4.1

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.


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.1 
supports XFree86 4.0.2 AND 4.0.3, and driver 1.4.1 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 PowerDesk "Readme" file included with this software.

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 and 
display positioning. 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.)

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.

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


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

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

  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

