[English] README.TXT MATROX GRAPHICS INC. 2002.02.25 Matrox Beta Drivers For XFree86 Package Version: 2.0 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 driver package includes previously released drivers for XFree86 versions 4.0.3, and 4.1.0, and a new driver for version 4.2.0. Notes ===== 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. 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. 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 (G400 only). 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 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 and 4.2.0. 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 is not required for basic DualHead support (without a DVI monitor) with G450- and G550-based graphics hardware. Also please take not that TV output is not supported with G450- and G550- based graphics hardware in Linux. 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.0.3, 4.1.0, or 4.2.0 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 or 4.2.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 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