[English]
README.TXT               MATROX GRAPHICS INC.           2005.12.02


                         Matrox Parhelia Series 
                       Linux Display Driver v1.4.3


================================================================================
Preface
================================================================================

    This document and the associated software are currently only available in
    English. We apologize for the inconvenience. 

    The use of the term X config file, XF86Config, XF86Config-4 and xorg.conf
    are used interchangeably. The actual file names to use vary depending on the
    X server or distribution used.  These files are located in the /etc/X11 
    directory.

    The use of the term X log file, XFree86.0.log and Xorg.0.log are used
    interchangeably. The actual file names to use vary depending on the X server
    or distribution used. These files are located in the /var/log directory.

    Don't enter the '#' sign in the example command sequences, this represents
    what would be seen on the command line. Note that [ENTER] means 
    pressing the 'Enter' key on your keyboard.

    Note that on some systems you may need to enter "su - root" instead of
    "su root" when changing to the root user account.  For more information 
    about root user, see Appendix C.


================================================================================
Contents
================================================================================

Preface    - Document clarifications
Section 01 - Description of this release
Section 02 - Installation requirements
Section 03 - Binary installation
Section 04 - Sample X config files
Section 05 - XFree86 & X.org driver options
             1 - Single Head
             2 - DualHead Independent
             3 - DualHead Merged
             4 - TripleHead Independent
             5 - TripleHead Merged
             6 - Digital Monitors
             7 - Bus Mastering
             8 - Xv Video Blitting
Section 06 - Using AGP capabilities
Section 07 - Frequently asked questions
Section 08 - Troubleshooting
Section 09 - Matrox technical support information
Appendix A - Installer options
Appendix B - Installed files
Appendix C - Important preliminary informations for new Linux users


================================================================================
Section 01 - Description Of This Release 
================================================================================

This release was tested with the following items:

Distributions:

    - Redhat Enterprise Linux 3 WS
    - Redhat Enterprise Linux 4 WS
    - SuSE Professional 9.2
    - SuSE Professional 9.3

Cards:

    - Parhelia (PCI, AGP)
    - Millennium P750 (AGP)
    - Millennium P650 (PCI, PCIe, AGP)
    - Parhelia APVe (PCIe) - no video input & video editing support

Display configurations:

    - Single display - Only 1 display through the main connector. 

    - Two displays   - Independent mode: 2 displays with different display 
                       resolutions. 

    - Two displays   - Merged mode: 2 displays with the same display 
                       resolution. These 2 displays use a single frame buffer.  

    - Three displays - Independent mode: 3 displays with the same display 
                       resolution. This mode is not available on all cards 
                       covered by this driver.

    - Three displays - Merged mode: 3 displays with the same display 
                       resolution. These 3 displays use a single frame buffer. 
                       This mode is  not available on all cards covered by 
                       this driver.

Resolutions:

    - Analog: 640x480, 800x600, 1024x768, 1280x1024, 1600x1200, 1920x1440

    - Digital: 640x480, 800x600, 1024x768, 1280x1024, 1600x1200


Note: 
    - The driver included in this package should also be compatible with 
      additionnal Linux distributions provided that items outlined in 
      Section 02 are installed and available.

    - Additionnal features and information about the configuration of 
      specialized Matrox cards are described in our advanced Readme file 
      available as a separate file along with this driver package 
      on the Matrox Web Site.

          http://www.matrox.com/mga/support/drivers/latest/home.cfm


================================================================================
Section 02 - Installation Requirements
================================================================================

Some features, such as Busmastering, OpenGL, and Xv, contain functionality
implemented at the kernel level and therefore require a Matrox kernel
module.  A kernel module must be compiled specifically for the targeted kernel.
In order to compile your kernel module, the following packages need to be
installed and available on your system:

    - X server (either XFree86 4.3.0 or X.org 6.7.0 or later).

    - Linux kernel 2.4 (version 2.4.18 or later) or 2.6 (2.6.0 or later) 
      and the corresponding kernel source code and header files.

    - Gcc compiler version 3.2 or later.

    - Glibc 2.3.2 or later.

    - Binutils 2.13 or later.

    - Make 3.77 or later.

The install script verifies that these requirements are satisfied.  You can
also run :
    # su root [ENTER]
    # sh mtxdriver-X.X.X-X.run --test-only [ENTER]
    # exit [ENTER]


================================================================================
Section 03 - Binary Installation
================================================================================

To install the driver execute the following from a shell terminal as the 'root' 
user :

    # su root [ENTER]
    # sh mtxdriver-X.X.X-X.run [ENTER]
    # exit [ENTER]
    
Note:
    - On some systems you may need to enter "su - root" instead of "su root" 
      when changing to the root user account.


This starts the installation script and asks where to extract the files 
(usually /root). Choose the location and press [ENTER]. The installer proceeds
with the installation of the X driver and related files.

Once the installation is completed, you need to create a new configuration 
file for your current hardware so that the X server knows how to start up. 
This file may be called XF86Config (XFree86 v3 and v4), XF86Config-4 (XFree86 
v4), or xorg.conf (X.org 6.7.0 and up) and is usually located in the 
directory /etc/X11 . Configuration samples can be found by running the
installation package with the "--extract-only" option (See Appendix A).
For example :

    # sh mtxdriver-X.X.X-X.run --extract-only [ENTER]

You can find these samples in the 'samples' directory, where the package 
extracts its files to. These samples require editing to match your 
current installed hardware. In many instances, if this is an installation right 
after a clean install of the OS, the config file will reference the VESA or MGA 
driver. You will have to change it to use the mtx driver instead.

To continue the installation, use a text editor.  
For more information about text editors in GNU/Linux, see Appendix C.

As an example, here is the complete installation process on X.org 6.8.1

    1 - Install Matrox Driver

            # su root [ENTER]
            # sh mtxdriver-X.X.X-X.run [ENTER]
            # exit [ENTER]

    2 - Locate your Matrox hardware on the peripheral bus 
	
        The location of your Matrox card will be reported by the installation
        script in the following format: bus:device.function. 

        For example:

        1:0.0 VGA compatible controller: Matrox Graphics, Inc. MGA Parhelia AGP

    3 - Edit the X Server configuration file
      
            # vi /etc/X11/xorg.conf [ENTER]
     
        For more information on how to use the 'vi' text editor, please refer to 
        Appendix C.

    4 - Select the Matrox driver

        In the "Device section", replace the string 'Driver "somedriver"' with
        'Driver "mtx"'.

        For example replace this line if the 'vesa' driver was previously
        installed:

        Replace:
            Driver  "vesa"
        by 
            Driver "mtx"

    5 - Select the appropriate graphics card

        In the "Device" section, make sure that the BusID value matches with 
        the one you previously identified in step 2.

        For example if your Bus ID was 1:0.0, edit or add the following line to
        read :

            BusID       "PCI:1:0:0"

    6 - In the "Monitor" section, make sure your horizontal and vertical 
        settings are valid for your monitor. If no values are specified, the X 
        Server may not start.  If incorrect values are specified, you risk
        damaging your monitor. See your monitor's documentation the correct
        values.  

        Typical values are:

            "HorizSync  30.0-95.0"
        and 
            "VertRefresh 50.0-75.0"

    7 - Remove unnecessary modules
    
        In the "Module" section, only the "dbe", "extmod", "freetype", "type1", 
        "glx" (if oOpenGL is required) should be listed. Comment out any other 
        lines if they exist by adding a '#' (pound symbol) at the beginning of
        the line.

        For example, if the "dri" module was listed as below, add '#' 
        (pound symbol) in front of it :

        Before -
                 Load "dri"

        After -
                 #Load "dri"

    8 - Start the X Server
      
        To start the X server from the command line, type the following line :

            # startx [ENTER]

        To switch to the graphical run level, change to the 'root' user, run
        the telinit application and switch to run level 5. 

        For example one could run the following sequence.

            # su root [ENTER]
            # telinit 5 [ENTER]
            # exit [ENTER]

For more information on the XFree86 config file format, simply type 
'man XF86Config' in a shell terminal to list all available options that
can be used in an X config file. Typing 'man xorg.conf' should bring up 
the same information for X.org users. More information can also be found at
http://www.xfree86.org for XFree86 or http://xorg.freedesktop.org/wiki/ and
http://wwwx.org for X.org.


================================================================================
Section 04 - Sample X Config Files
================================================================================

There are sample XF86Config files in the "Samples" directory. To use them, copy
the file to your /etc/X11 directory and rename it to "XF86Config-4" or
"xorg.conf" depending if you're using the XFree86 or X.org servers or as 
the 'root' user type (where FILENAME is the sample config file).

    # startx -- -xf86config /My/Path/FILENAME [ENTER]

These are the available samples :

    Single display                                 --> XF86Config.single
    2 displays - independent mode                  --> XF86Config.dual
    2 displays - merged mode                       --> XF86Config.merged
    3 displays - independent mode                  --> XF86Config.triple
    3 displays - merged mode                       --> XF86Config.triple_merged

The following section provides more details on these various configuration
options.
     
Note:
    -  These are samples and may require modification to be usable with your 
       particular system configuration.
    

================================================================================
Section 05 - XFree86 & X.org Driver Options
================================================================================

1 - Single display

    While using a single head (or output) setup, you need to edit your X config
    file to contain a single entry for the device, monitor and screen sections.

    Here's a sample X partial config section :

        Section "Monitor"
            Identifier "monitor1"
            HorizSync   30-95
            VertRefresh 50-60
        EndSection

        Section "Device"
            Identifier   "device1"
            Driver       "mtx"
            BusID        "PCI:1:0:0"
            Screen       0
        EndSection

        Section "Screen"
            Identifier "screen1"
            Monitor    "monitor1"
            Device     "device1"
            DefaultDepth 24

            Subsection "Display"
                Depth 24
                Modes "1600x1200" "1280x1024" "1024x768" "800x600" "640x480"
            EndSubsection
        EndSection

2 - DualHead Independent

    While using DualHead Independent, both displays can have different refresh 
    rate and resolutions. These displays can be set to be independent, or 
    unified using the Xinerama extension.

    Here's a sample X partial config section :

        Section "Monitor"
            Identifier "monitor1"
            HorizSync   31-90
            VertRefresh 50-60
        EndSection

        Section "Monitor"
            Identifier "monitor2"
            HorizSync   31-90
            VertRefresh 50-60
        EndSection

        Section "Device"
            Identifier   "device1"
            Driver       "mtx"
            BusID        "PCI:1:0:0"
            Screen       0
        EndSection

        Section "Device"
            Identifier   "device2"
            Driver       "mtx"
            BusID        "PCI:1:0:0"
            Screen       1
        EndSection

        Section "Screen"
            Identifier "screen1"
            Monitor    "monitor1"
            Device     "device1"
            DefaultDepth 24

            Subsection "Display"
                Depth 24
                Modes "1600x1200" "1280x1024" "1024x768" "800x600" "640x480"
            EndSubSection
        EndSection

        Section "Screen"
            Identifier "screen2"
            Monitor    "monitor2"
            Device     "device2"
            DefaultDepth 24

            Subsection "Display"
                Depth 24
                Modes "1600x1200" "1280x1024" "1024x768" "800x600" "640x480"
            EndSubSection
        EndSection

    Add the following section to the above config file to unify both independent
    displays to behave as a single desktop:

        Section "ServerFlags"
            Option "Xinerama"
        EndSection

3 - DualHead Merged

    DualHead merged enables the use of 2 displays using a single framebuffer. 
    The following options are used to enable DualHead merged mode:

        MergedFB                    Enables merged mode

        Monitor2Position            Sets layout orientation. Valid values are 
                                    LeftOf, RightOf, Below and Above.

        MetaModes                   Specifies the Left screen - Right screen 
                                    resolution to use in this mode. These should
                                    be set to one of the resolutions listed in 
                                    the Modes line of the current screen 
                                    subsection.

        Monitor2HSync               The secondary monitor horizontal sync values.
                                    This can be a single value or a value range.

        Monitor2VRefresh            The secondary monitor vertical sync values.
                                    This can be a single value or a value range.

    The following example sets two displays at 1600 x 1200 at 60 Hz refresh rate:

        Section "Monitor"
            Identifier "monitor1"
            HorizSync   30-95
            VertRefresh 50-60
        EndSection

        Section "Device"
            Identifier "device1"
            Driver     "mtx"
            BusID      "PCI:1:0:0"
            Screen     0
        EndSection

        Section "Screen"
            Identifier "screen1"
            Monitor    "monitor1"
            Device     "device1"
            DefaultDepth 24

            Option "MergedFB"
            Option "Monitor2Position" "RightOf"
            Option "MetaModes" "1600x1200-1600x1200"
            Option "Monitor2HSync" "30-85"
            Option "Monitor2VRefresh" "50-60"

            Subsection "Display"
                Depth 24
                Modes "1600x1200" "1280x1024" "1024x768" "800x600" "640x480"
            EndSubSection
        EndSection

4 - TripleHead Independent

    While using Triplehead, all 3 displays must have the same refresh rate and
    resolution.

    To enable TripleHead independent, add

        Option "THI" "on"

    to the three "device" sections of your XF86Config-4 file.

    Here's a sample Device Section for TripleHead:

        Section "Device"
            Identifier   "device1"
            Driver       "mtx"
            BusID        "PCI:1:0:0"
            Screen       0
            Option       "THI" "on"
        EndSection

        Section "Device"
            Identifier   "device2"
            Driver       "mtx"
            BusID        "PCI:1:0:0"
            Screen       1
            Option       "THI" "on"
        EndSection

        Section "Device"
            Identifier   "device3"
            Driver       "mtx"
            BusID        "PCI:1:0:0"
            Screen       2
            Option       "THI" "on"
        EndSection

    Note:
        -  This mode is only available in analog mode.

5 - TripleHead Merged

    To enable TripleHead merged, add

        Option "Triplehead"

    to the "screen" section of your XF86Config-4 file

    Here's a sample "Screen" section for TripleHead:

        Section "Screen"
            Identifier   "Screen1"
            Device       "Device1"
            Monitor      "Monitor1"
            DefaultDepth 24
            Option       "Triplehead"

            SubSection "Display"
                Depth    24
                Modes    "800x600"
            EndSubSection
        EndSection

    To enable 2 analog + digital mode, add the following line to your "device"
    section:

        Option "DigitalScreen1" "on"

6 - Digital monitors

    Digital monitors are automatically detected by the Matrox driver.  If your
    monitor can't supply this information to the driver, you can specify 
    the type of your monitors in the "Device" section of the configuration 
    file.

        Option "DigitalScreen1" "on"
    or
        Option "DigitalScreen2" "on"

    "DigitalScreen1" and "DigitalScreen2" correspond respectively to the
    digital monitor connected to the primary and secondary connector of your
    graphics card. 

    When using both outputs for the Parhelia, Millennium P750 and P650 cards in
    merged mode, the "device" section of your X config needs to contain only
    the DigitalScreen1 option.

7 - Bus mastering

    Bus mastering allows the processor to share some tasks with the graphic 
    chipset and results in higher performances.  Bus mastering is required for 
    accelerated 3D OpenGL and is only available for x86 architecture.  To
    enable bus mastering a Matrox kernel module must be compiled specifically
    for your system. On most configurations the installation script seamlessly
    takes care of the kernel driver compilation, assuming that the
    kernel source code is properly installed as mentioned in Section 02.

    To enable or disable bus mastering, add the following to the X config
    file in the appropriate "Device" section:

        Option "Busmastering" "on"
    or
        Option "Busmastering" "off" 

    If no option is specified, bus mastering is enabled by default, provided 
    that your system supports it.

    The following "device" example illustrates its use:

    Section "Device"
        Identifier "device1"
        Driver     "mtx"
        BusID      "PCI:1:0:0"
        Option     "Busmastering" "off"
    EndSection

    Note:
        - For AGP systems using a Matrox AGP card, load the 'agpgart' module
          before the Matrox kernel module so that it can benefit from AGP
          capabilities. If 'agpgart' isn't loaded, refer to Section 06 for
          more information on AGP.

8 - Xv Video Blitting

    If you experience some problems with your video playback, Video blitting can
    be used instead of hardware overlays by using the "XFB" switch in the 
    "Device" section of your X config. The following example illustrates its 
    use:

    Section "Device"
        Identifier "device1"
        Driver     "mtx"
        BusID      "PCI:1:0:0"
        Option     "XFB" "on"
    EndSection


================================================================================
Section 06 - Using AGP Capabilities
================================================================================

The AGP bus is a dedicated bus for graphics hardware. AGP stands for Advanced 
Graphics Port.  This technology was designed to improve performances over the 
standard PCI bus.  To benefit from this technology, you need an AGP capable 
graphic card as well as an AGP capable system.  

Note that AGP is now being replaced by the new PCI Express (PCIe) bus 
architecture which offers even greater performances.  If you have such a system, 
this section can be skipped.

To use AGP capabilities make sure that the "agpgart" module has been loaded 
successfully.  You can verify that the 'agpgart' is loaded by typing:

    # /sbin/lsmod | grep agpgart [ENTER]

This command should output something like this:
    agpgart                33608  0

If this command yields no output, it means that the module isn't loaded, you can 
load it manually by typing:

    # /sbin/modprobe agpgart [ENTER]

On 2.6 kernels you also need to load the module corresponding to your 
motherboard chipset. Available files are intel-agp, via-agp, nvidia-agp, 
sis-agp, sworks-agp, ali-agp, ati-agp, amd-k7-agp. You can verify that one of
these is loaded by typing the following:

    # /sbin/lsmod | grep agp [ENTER]

If the chipset kernel module isn't loaded, you can load it manually by 
typing ONE of the following:

    # /sbin/modprobe intel-agp [ENTER]
    # /sbin/modprobe via-agp [ENTER]
    # /sbin/modprobe nvidia-agp [ENTER]
    # /sbin/modprobe sis-agp [ENTER]
    # /sbin/modprobe sworks-agp [ENTER]
    # /sbin/modprobe ali-agp [ENTER]
    # /sbin/modprobe ati-agp [ENTER]
    # /sbin/modprobe amd-k7-agp [ENTER]

*If you don't know your motherboard chipset, see to your system documentation.
The following command can give you a hint:

    # /sbin/lspci | grep -e "AGP Bridge" [ENTER]

You can then verify that the Matrox kernel module has been loaded with:

    # /sbin/lsmod | grep mtx [ENTER]

If the Matrox kernel module isn't loaded, you can load it manually by 
typing:

    # /sbin/modprobe mtx [ENTER]

Once you've identified the appropriate modules to load and you've tested
your system successfully, you can automatically load these modules
each time your system boots up, instead of having to retype the commands.  
To automatically load kernel modules, simply add their names to the
following file, depending on your kernel version.

    # vi /etc/modules [ENTER]           (for kernel 2.4.x) 
    or 
    # vi /etc/modprobe.preload [ENTER]  (for kernel 2.6.x) 

You can find your kernel version by typing:
    # uname -r [ENTER]

For example, to load the Matrox kernel module and benefit from AGP capabilities
on a 2.6 kernel running on an Intel system, the '/etc/modprobe.preload' would 
look like this:
    intel-agp
    agpgart
    mtx


================================================================================
Section 07 - Frequently Asked Questions
================================================================================

Q:  I'm running the installer and it stops making the kernel module, what can I
    do ?
A:  Make sure that the kernel source or kernel headers are installed. It's also
    possible that the kernel you've installed isn't yet supported. Verify at a 
    later date to see if it is supported.

Q:  I'm trying to run OpenOffice and it fails to run. What can I do ?
A:  Make sure that the libglx.a and libGL.so.1.3.0 files are installed and that 
    bus mastering is enabled. Also make sure that only the Matrox libGL.so.* 
    files are installed. Having other versions available can prevent
    applications from running properly.

Q:  I'm trying to run a video player and my systems locks up. What can I do ?
A:  Enable the XFB option to force hw blits instead of using the hw video
    overlay. See Section 5 to enable this option.

Q:  My system seems to lock up when I try to run a video or OpenGL application. 
    What can I do ?
A:  Try disabling fastwrites in your motherboard BIOS settings. Also, in some 
    systems with 1GB of RAM or more, you need to pass the following switch 
    (vmalloc=) to your boot manager (in grub on the appropriate kernel line or 
    in lilo on the append line. Note that the ram value passed is in bytes). 
    For example, if you want to reserve at least 128MB, you add this to your 
    boot manager config file:

        vmalloc=134217728

Q:  I have a system with a 1GB of RAM and cannot get any hardware acceleration
    and get memory allocation messages when modprobing the mtx kernel module.
    What can I do ?
A:  In some systems with 1GB of RAM or more, you need to pass the following 
    switch (vmalloc=) to your boot manager (in grub on the appropriate kernel 
    line or in lilo on the append line. Note that the ram value passed is in 
    bytes). For example, if you want to reserve at least 128MB, you add this 
    to your boot manager config file:

        vmalloc=134217728

Q:  I'm trying to run an OpenGL application and sometimes X freezes or crashes.
    What can I do ?
A:  Make sure that you have uninstalled any reference to "DRI" from your
    X config file, as the driver doesn't use this architecture to provide
    hardware accelerated 3D. 

Q:  Is there a way to update my graphics card BIOS from Linux ?
A:  Download the appropriate utility from the following link:

        http://www.matrox.com/mga/support/drivers/bios/home.cfm

Q:  I'm installing Linux and wonder what driver I should set during the OS
    installation ?
A:  During installation of your favorite Linux distribution you may be asked 
    to set or choose a graphics card or driver. The safest option is to choose 
    the VESA driver or card.

Q:  I upgraded my version of X and now my previous configuration file doesn't
    work. What can I do ?
A:  When upgrading X you need to reinstall the Matrox driver package.

Q:  I upgraded my kernel and now my 3D and video doesn't work. What can I do ?
A:  When upgrading your kernel you need to reinstall the Matrox driver package
    so that the appropriate driver components are reinstalled.

Q:  How can I find out what driver I'm using in X ?
A:  Open your X log file (normally found in /var/log) in your favorite 
    text editor and look for a line that says "mtx_drv.o". The line below 
    contains the driver version number. For example, if the installed 
    driver package was version 1.4.3 you could see something like:

        (II) Loading /usr/X11R6/lib64/modules/drivers/mtx_drv.o
                compiled for 6.8.2, module version = 1.4.3

    The module version would indicate the driver version 1.4.3.

Q:  How can I find out what version of X the driver was compiled for ?
A:  Start X and open up your X log file (normally found in /var/log) in 
    your favorite text editor and look for a line that says "mtx_drv.o". 
    The line below contains the driver version number. For example, if 
    the installed driver package was version 1.4.3 you could see something 
    like:

        (II) Loading /usr/X11R6/lib64/modules/drivers/mtx_drv.o
                compiled for 6.8.2, module version = 1.4.3

    The version of X the driver would be indicated after the 'compiled for'
    and would be 6.8.2 in this case.

Q:  Where can I find my X config file ?
A:  Most distributions store this file in the /etc directory as either
    XF86Config, XF86Config-4 or xorg.conf.

Q:  Where can I find my X log file ?
A:  Most distributions store this file in the /var/log directory as either
    XFree86.0.log or Xorg.0.log when running either XFree86 or X.org X server.

Q:  I enabled Xinerama in my config file and when I maximize a window, it gets 
    stretched over my two display when using Qt/KDE applications.
A:  Make sure that your Qt library is compiled with Xinerama support.

Q:  I have set up DualHead (or TripleHead) Independent mode in my config file
    and the X Server locks up on start up.
A:  The numerical values of the 'Screen' keyword in the "Device" section must 
    match the screen index defined in the "ServerLayout" section.
    The 'Screen' keyword in the "ServerLayout" section is defined as:

       Screen screen-num "screen-id" position-information 

    The screen index is either defined by 'screen-num' (which is optional) or
    the order the screens are declared in the 'ServerLayout' section.

Q:  Where can I find the Readme file and sample config files contained in
    the driver package?
A:  Use the --extract-only switch and choose a directory to extract the files
    to. For example, as root you would do the following to launch the file
    extraction and access the sample directory:
    
        # su root
        # sh mtxdriver-1.4.3.run --extract-only [ENTER]
          [ENTER]
        # cd /root/mtxdriver/samples

Q:  I am trying to get a Millennium P650 or Millennium P750 to do TripleHead
    and it doesn't work, what can I do to enable it ?
A:  These card require passing the regSysMmFlags=0 switch to the mtx kernel
    module. This can be used when modprobing (ie. modprobe mtx regSysMmFlags=0) 
    or in the apropriate config file (ie. modprobe.conf or modules.conf by adding 
    'option mtx regSysMmFlags=0' to either of these files).

Q:  I am trying to get a G series card working with my Parhelia based card but
    X crashes when loading the mga driver. What can I do ?
A:  Make sure that the system BIOS is booting off the G series card.

Q:  I am trying to get a G series card working with my Parhelia based card but
    my system locks up. What can I do ?
A:  Some fixes about AGP have been incorporated into kernels 2.6.12.  If 
    upgrading your kernel is not an option for you, either disable busmastering 
    using the Busmastering option in your X config file or disable agp transfers 
    by setting agp kernel module option to 0.

    Busmastering can be disabled as shown in this sample device section:

        Section "Device"
            Identifier "Device1"
            Driver     "mtx"
            BusID      "PCI:1:0:0"
            Option     "Busmastering" "off"
            Screen     0
        EndSection
    
    AGP transfers can be disabled manually as shown below:
    
    Before starting the X server, as a 'root' user, make sure that the 
    Matrox kernel module is not loaded:
        # /sbin/rmmod mtx  [ENTER]
    And then, load the Matrox kernel module with the desired option:
        # /sbin/modprobe mtx agp=0 [ENTER]

    To make this change permanent simply add the following line to 
    /etc/modules.conf (kernel 2.4.x) or /etc/modprobe.conf (kernel 2.6.x). 
    Note you must be the 'root' user to edit this file.

        options mtx agp=0


================================================================================
Section 08 - Troubleshooting
================================================================================

1 - Setup problems

    Problems may occur if you don't use the appropriate version of a library, 
    or if a component is missing.  Make sure you have the following files:

        # ls -l /usr/X11R6/lib/modules/drivers/mtx_drv.o [ENTER]
        # ls -l /lib/modules/`uname -r`/kernels/drivers/video/mtx.* [ENTER]
        # ls -l /usr/X11R6/lib/modules/extensions/libglx.a [ENTER]
        # ls -l /usr/lib/libGL.so 	-> 	/usr/lib/libGL.so.1 [ENTER]
        # ls -l /usr/lib/libGL.so.1 	-> 	/usr/lib/libGL.so.1.3.0 [ENTER]
        # ls -l /usr/lib/libGL.so.1.3.0 [ENTER]

2 - Resolving conflicts with /usr/X11R6/lib/libGL.so* [ENTER]

    If there are other shared libraries (files containing ".so" in their 
    names) conflicting with Matrox libraries, ldconfig (the library manager)
    may create the wrong symlinks. We recommend you manually remove
    or move conflicting libraries, rerun 'ldconfig', and check that the correct 
    symlinks were made.  

3 - Verifying that applications use appropriate libraries

    You can use the 'ldd' command on a 3D application to check that it uses 
    the appropriate libraries.  For example, 'ldd glxgears | grep libGL.so' 
    should give you:

        libGL.so.1   =>   /usr/lib/libGL.so.1 [ENTER]

    If this isn't the case, either remove the library that gets in the way,
    or adjust the LD_LIBRARY_PATH environment variable.  For more 
    information, see the man pages for ldconfig and ldd.

4 - Stability and AGP problems

    Several successive improvements were made on AGP technology and the speed 
    has been steadily increased. As the AGP rate is increased, the performance
    improves. However both your graphics hardware and your motherboard must 
    support the specified rate to benefit from the increase in performance.  
    The AGP rate is automatically determined by the driver.

    However, some compatibility problems may occur. Such problems include
    signal integrity problems and timing issues, with the combination 
    of specific motherboard chipsets and some graphics cards.  If you encounter 
    stability issues, you may find it's best to set conservative kernel module 
    parameters for AGP initialization.

    When using the mtx.o/mtx.ko kernel module, the following options can be 
    specified:
 
        agp     = [ 0: Force PCI transfers 
                    1: Enable AGP transfers (default) ]

        agprate = [ 1: AGP 1x transfers (default) 
                    2: AGP 2x tranfers 
                    4: AGP 4x tranfers ]

    The AGP rate can be set by 'root' user as follows:

        # modprobe mtx agprate=4 [ENTER]
   
    For AGP systems including AGP graphics card, AGP transfers are used 
    by default.  However, if your system has stability problems, 
    you can force the use of PCI transfers using the following parameter as 
    the 'root' user:

        # /sbin/modprobe mtx agp=0 [ENTER]
    
    These options can also be set automatically by adding them to the 
    modules.conf or modprobe.conf file (on most distributions this is 
    located in the /etc directory).

    For example, to enable AGP transfers but reduce their rate to 1x, simply 
    add the following line to modules.conf (kernel 2.4.x) or modprobe.conf
    (kernel 2.6.x).  *You must be the 'root' user to edit this file.

        options mtx agp=1 agprate=1 

    Doing so automatically sets these options any time the module is loaded.


================================================================================
Section 09 - Matrox Technical Support information
================================================================================

A Linux driver forum is available on the Matrox web site. In the "General Linux" 
section you can post questions, answer other users questions, and search the 
archive for previous postings. User registration is required. The site is
available at http://forum.matrox.com/mga/ .


================================================================================
Appendix A - Installer Options
================================================================================

The following are valid options supported from the command line to be passed 
to the installer (used without the quotation marks):

    --test-only     Used to verify that your system has everything it needs to
                    proceed with a successfull installation.

    --extract-only  Used to tell the installer to extract the files but not 
                    to run the installer portion.
    
    --uninstall     Used to tell the installer to uninstall the current driver.

    --overwrite     Used to tell the driver to ask the user for the files to 
                    overwrite. No backups will be created of the currently
                    installed files.
        

================================================================================
Appendix B - Installed files
================================================================================

The Matrox Linux driver set consists of the following files:

    - An X Server driver. This driver is mainly responsible for the mode 
      initialization and 2D acceleration. It's usually located in the 
      following X driver path /usr/X11R6/lib/modules/drivers/mtx_drv.o

    - A kernel module. The kernel module mainly adds 3D core functionality, 
      bus mastering, memory management, and interrupts management.  The kernel 
      module is made of two parts, a binary part and an open source interface 
      part.  This is because the kernel needs to be compiled specifically on 
      your system. It's usually located in the following kernel module path 
      /lib/module/<kernel-version>/kernel/drivers/video/mtx.[k]o

    - A GLX extension module. This module serves as an interface between the 
      OpenGL library and the X server. It's usually located in the 
      following X extensions path /usr/X11R6/lib/modules/extensions/libglx.a

    - An OpenGL library. This is the library that exposes the OpenGL API to 
      3D applications.  It processes the commands and sends them to the kernel 
      module. It is usually located in the following software library path
      /usr/lib/libGL.so.1.3.0 with two symlinks to /usr/lib/libGL.so and
      /usr/lib/libGL.so.1


================================================================================
Appendix C - Important preliminary informations for new Linux users
================================================================================  

    Text Editors
    ------------
    A lot of configuration in Linux is still done through the editing of 
    text files.  Sometimes, a graphical interface is not even available.  
    Text editors are therefore essential to everyone wishing to configure 
    a Linux system.  Because they are so essential, some text editors now 
    feature very powerful functionalities... but this comes at the cost 
    of increased complexity.  Here, we are presenting you with a few options.

    'gedit' is simple to use, but requires a graphical environment which won't
    be available if the wrong driver was chosen during installation or if
    something else goes wrong.  

    'kate' is also simple to use, but it also requires a graphical environment.
    See 'gedit'.

    'vi' is one of the most powerful text editors to use and is installed by
    default by most distributions.  However it's not easy to use. For an
    overview of the vi text editor basic commands, see 'vi' Overview.

    Alternatively, 'mcedit' or 'nano' can be used in text mode and are 
    relatively easy to use.  However, they're not installed by default by 
    most distributions. 

    'vi' Overview
    -------------
    Because 'vi' is the most powerful but the least user-friendly text 
    editor, we are introducing you with a very basic overview to get you 
    started with its usage.

    'vi' operates in two modes: edit and command. On start up, vi is in 
    command mode.

    To enter edit mode, press i.  You can then add, modify and remove text.
    To go back to command mode, press Escape.  Now you have access to a lot 
    of functionality, a bit similar to what a menu offers in a graphical 
    application.

    Basic commands:

        i   - Enter edit mode
        Esc - Enter command mode
        :w  - Save
        :q  - Quit


    root user
    ---------
    After installing, almost all distributions set up a default 
    administrative user with the username 'root'. Many options
    (such as installing the Matrox kernel driver) are available only to 'root'
    users.  

    There are three ways to become 'root'. You may log in as root as would 
    do any other user, you may use the substitute user command ('su') at 
    the command prompt as we used extensively in our examples, or, some 
    systems come with the 'sudo' utility which allows users to run a 
    specified program as root. To use 'sudo', simply prefix the command you
    need with the sudo keyword, for example: 

        # sudo sh mtxdriver-X.X.X-X.run [ENTER]

    It is generally a good practice to remain root only as long as it is 
    necessary to accomplish the task requiring root privileges.
