[English] README.TXT MATROX GRAPHICS INC. 2001.02.08 BETA DRIVER FOR XFree86 4.0.2 DESCRIPTION OF THIS RELEASE =========================== This XFree86 4.0.2 driver includes support for the G450, G400 and G200 graphics adapters. Supported features include DualHead support for the G450, DualHead, digital flat panel, and TVout support for the G400, and multiple display support for the G200 Multi-Monitor series. 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 mga_drv.o and mga_hal_drv.o modules into a working installation of XFree86 4.0.2, or by compiling the module from source. The driver is for x86 based architectures only. Support for other architectures is planned for 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 display adapter initialization, which has been replaced with a closed source Matrox library. This special library enables features such as DualHead, TV out, and support for digital flat panel monitors. 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 is required before the driver can be installed. For users who wish to upgrade from an older version of XFree86, the 4.0.2 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 XFree86 4.0.2 is installed and working properly, the driver can be installed by copying mga_drv.o and mga_hal_drv.o into /usr/X11R6/lib/modules/drivers (or wherever your X11R6 directory is located.) 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 to download and untar the XFree86 4.0.2 source files, which are available 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 back up 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 You will now need to create and edit a host.def file in the XFree86 source tree: cd /xc/config/cf cp xf86site.def host.def Using a text editor such as pico, vi, or emacs, insert the following line at the bottom of the host.def file: #define HaveMatroxHal YES Note: The option #define UseMatroxHal is also reqired, but is enabled by defaultin the xf86site.def file. 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 properly link it 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. 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.1 or higher is installed on your system, there may already exist 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 4.0.2. However, some of the upcoming XFree86 4.0.2 based Linux distributions may automatically enable DRI support through the kernel during setup. Direct rendering also requires agpgart support. These newer distributions should also automatically configure agpgart, making it unnecessary to upgrade the kernel as suggested below. If you are using an older kernel that does not include agpgart support, it will be necessary to upgrade to a later version. When configuring the kernel, be sure to enable support for agpgart (as a module) and select the proper chipset. Once the development kernel is installed and working properly, DRI can be enabled from within the following directory: /xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel Note: Unless your system is set up to load modules automatically, each time the system is rebooted you will have to return to the /kernel directory to load the mga.o module. The mga.o module needs to be compiled and loaded from within the /kernel directory. If you have an Xserver running it should be shut down before compiling. If you are using a 2.4.x kernel you will have to modify a line in one of the source files before compiling the mga.o module: cd /xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel The file which needs to me modified is mga_dma.c. Line 821 should be changed from: dev->tq.next = NULL to: dev->tq.list.next = NULL If your text editor has a search option you may want to use it to find "tq.next". Vi allows you to go to line 821 directly by typing /821. Once mga_dma.c has been edited and saved, use the following commands to build and load the mga.o module. make -f Makefile.linux mga.o insmod agpgart insmod mga.o lsmod (to make sure the modules are loaded) 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 Xserver startup log. Please note that dri will not be enabled if you are using a dualhead configuration. 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 MultiMonitor boards, the following sections of the XF86Config file need to be modified: Graphics 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 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. 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. Note: The TV out feature is currently only supported on the G400 series. 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" 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