[English] README.TXT MATROX GRAPHICS INC. 2001.10.17 Matrox beta drivers for XFree86 Version 1.3.3 / 1.4.3 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.3 and 4.1.0. Two driver versions are included -- driver 1.3.3 supports XFree86 4.0.3, and driver 1.4.3 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. Please take note that this feature does not support DVI monitors in XFree86 4.1.0. 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 or 4.0.3 is required before the binaries can be installed. To extract the driver files, enter the following command where is the name of the driver file you want to extract: tar xvzf .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 is the name of the driver file you want to extract: tar xvzf .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