README.TXT                   MATROX GRAPHICS INC.             2001.05.09

                           BETA DRIVER FOR XFree86 
                               Version 1.3.0 
                     For Use With Matrox PowerDesk For Linux
                        

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

This release is for use with Matrox PowerDesk for Linux. It is based on the
1.2.0 beta driver and is required to support PowerDesk specific escape calls. 

PowerDesk is a utility that allows users to configure Matrox graphics
adapters under XFree86. This utility makes it easier to adjust resolutions,
color depths, refresh rates, and screen positioning. Users can also use
PowerDesk to enable Matrox specific features such as DualHead and TV
output. PowerDesk is available for download from our website:
http://www.matrox.com/mga.
For more information please see the PowerDesk readme file.

*****************************************************************************
The remainder of this document contains the readme file that was included
with the 1.2.0 driver, which this release is based on. If you are using
Matrox Powerdesk to configure your graphics adapter you will not need to
manually edit the XF86Config file to enable DualHead, TV output, or digital
monitor support as suggested below. 
*****************************************************************************

This XFree86 4.0.2/4.0.3 beta driver introduces open source DualHead
support for the G450 graphics adapter. The G400 and G200 series are also
supported through use of the Matrox HAL library, which can be optionally
installed to provide extra features that are not included with the standard
XFree86 mga driver. These features include DualHead, digital flat panel,
and TV out support for the G400, and multiple display support for the G200
Multi-Monitor series. Please take note that there have been no changes made
to the HAL library since the previous driver release, therefore G400 and
G200 users will not see any performance improvements in this release. This
driver is also programmed to set the internal clock speeds to production
levels, increasing 2D and 3D performance under XFree86.

The driver can either be installed by copying the binary file(s) 
into a working installation of XFree86 4.0.2 or 4.0.3, or by compiling the
modules from source.

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

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


NOTES
=====

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

This driver is based on the open source development being done within the 
XFree86 Project. The driver remains unmodified, with the exception of the
HAL module, which is a closed source library used to enable features 
such as DualHead, TV out, and support for digital flat panel monitors.
Please take note that TV out and digital flat panel support are available
on the G400 only. The HAL module is not required for DualHead support on
the G450.

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


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

A working installation of XFree86 4.0.2 or 4.0.3 is required before the
binaries can be installed. If your Linux distribution uses an older version
of XFree86 you will either need to upgrade your X server, or your Linux
distribution.

XFree86 4.0.2 and 4.0.3 source files and installation instructions are
available from: http://www.xfree86.org/, or from one of their mirror sites:
http://www.xfree86.org/#mirrors. 

Once the new version of XFree86 is installed and working properly, the G450
open source driver can be installed by copying mga_drv.o into
/usr/X11R6/lib/modules/drivers (or wherever your X11R6 directory is located.)

G400 and G200 MMS users will need to copy both files (mga_drv.o and
mga_hal_drv.o) into the drivers directory in order to enable DualHead or
multiple monitor support. The HAL module can also be used with the G450. If
the mga_hal_drv.o file is present in the drivers directory the HAL module
will be used instead of the open source driver. 

It is recommended to back up the existing mga_drv.o file before installing
the new one. The mv command can be used to back up the mga_drv.o file as
shown below.

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


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

To install the driver from source you will need the XFree86 4.0.2 or 4.0.3
source files, which are available for download from the sites listed above.
Once the XFree86 source files have been extracted, the existing mga
Directory should be backed up and renamed. This will be replaced by the new
mga directoy, which will be extracted from the driver source file. Use the
following command to make a backup of the mga directory:

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

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

      tar xvzf mga_filename.tgz  


Important: If you wish to use the Hal library instead of the G450 open
source driver you will 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 such as pico, vi, or emacs, 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 once 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 it may be easier 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 a G450 and have chosen to compile the Hal module, it can always
be disabled later by removing the mga_hal_drv.o file from the
usr/X11R6/lib/modules/drivers directory. This will automatically enable use
of the G450 open source driver.

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

	make World    (this will take awhile)
 
	make install

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

	ls -l X
	
This will show which binary X is linked to. If it lists anything other than
XFree86, you can link it to 4.0.x by using the following command:

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

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

	cd /usr/X11R6/bin

	./xf86config 

The xf86config command will start a text based configuration program. The
values you specify here will determine the parameters for your mouse,
keyboard, monitor, and graphics card. This will create an XF86Config file
in /etc/X11, which will need to be edited later. If newer boards such as
the G450 are not listed when choosing a graphics device, it is safe to
choose another adapter that uses the mga driver, such as the G200. Once the
values you
specified have been saved, you will 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 is likely to
be a separate config file for each in /etc/X11; XF86Config for 3.3.6, and
XF86Config-4 for 4.0.1.
	    

DRI
===

The Direct Rendering Infrastructure, also known as DRI, enables the use of
3D hardware acceleration under Linux. DRI acceleration is not enabled by
default in XFree86. However, most recent Linux distributions automatically
enable DRI support through the kernel during setup. Direct rendering
requires that your kernel version has support for agpgart. These newer
distributions should also configure agpgart automatically, making it
unnecessary to upgrade the kernel as suggested below.

You can find out if direct rendering is enabled by looking at the output
created when starting X. You can create an output file by typing:

	startx >& Xoutput.log

or you can view the output in /var/log/XFRee86.0.log, which is a log file
that gets created each time the X server is started. Look for the "direct
rendering" line, which will tell you if DRI is enabled or disabled. If
direct rendering is disabled, it may be possible that the module exists but
is not loading. From a console or terminal, type:

 insmod mga  

 lsmod 

The insmod command will load the mga.o module if it exists and is located
in the proper directory. The lsmod command lists all of the modules that
are currently loaded. This does not include modules that have been 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 are using an older kernel that does not include agpgart support, it
will be necessary to upgrade to a later version, such as 2.4.x. When
configuring the kernel, be sure to enable agpgart (as a module) and select
the proper chipset. Once the new kernel is installed and working properly,
DRI can be enabled from within the following directory by compiling and
installing the 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; usually /lib/module/your_kernel_version/misc/. This should allow
you to load the module from anywhere by using the lsmod command. Otherwise,
you will have to return to the kernel directory each time you wish to
reload the module. If there is already an older mga.o module in the misc
directory it would be a good idea to make a backup before installing the
new version.

The XF86Config file must now be configured to load DRI. These lines may
already be present 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 will not be enabled if you
are using a configuration which uses Xinerama. You may want to keep two
XF86Config files on hand; one for dri and the other for DualHead.


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

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

	Device section

	Screen Sections

	ServerLayout sections

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

	startx >& Xoutput.log


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

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

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

	startx -- +xinerama 

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

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

Note: The TV out option is not supported by the G450. This feature is
currently only supported by the G400. 

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

	Opt1on "TV" "yes"

	Option "DigitalScreen" "yes"

The default TV standard and cable types are NTSC and composite. Support for
PAL and other SCART cable types can be enabled by adding the following
options to the device section:

      Option "TVStandard" "PAL"

      Option "CableType" "SCART_RGB"
       
      Option "CableType" "SCART_COMPOSITE"

      Option "CableType" "SCART_TYPE2"

Both the TV out and digital flat panel features can be used either in clone
mode or virtual mode by using the xinerama extension. In order for the TV
out feature to work the display resolution must be set to 640x480 with a
refresh rate of 60Hz for NTSC, or 50Hz for PAL. 


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


Example: Clone Mode 

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

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


Section "ServerLayout"
     Identifier    "Layout1"
     Screen        "Screen0"
     Screen        "Screen1"
     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 screen.  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 screens are organized.  A specific ServerLayout
# section may be specified from the X server command line with the
# "-layout" option.  In the absence of this, the first section is used.
# When now ServerLayout section is present, the first Screen section
# is used alone.

Section "ServerLayout"

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

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

    Screen "Screen 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 MultiMonitor

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Section "ServerLayout"

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

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

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

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

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

EndSection