[English] README.TXT MATROX GRAPHICS INC. 2009.01.23 Matrox M-Series Linux Display Driver v1.0.0 Preface ======= The terms "X Server config file" and "xorg.conf" are used interchangeably. The file is located in the "/etc/X11" directory. The terms "X log file" and "Xorg.0.log" are used interchangeably. The file is located in the "/var/log" directory. In the command sequence examples, the pound ('#') sign represents the command prompt and shouldn't be typed. Note that [ENTER] means pressing the 'Enter' key on your keyboard. The command sequence examples in this Readme file refer to the 32-bit package named "m9xdriver-x86_32-1.0.0.run". Note: On some systems you may need to enter "su - root" instead of "su root" when changing to the root user account. Some systems prevent this operation. The alternative is to use the "sudo" command at the beginning of every command that must be run as root. For more information on root user, see Appendix C. Note: Some steps of the driver installation require that you manually edit files. If you're not familiar with text editing under Linux, see Appendix C. Contents ======== Section 01 - Description of this release Section 02 - Installation requirements Section 03 - Driver installation and configuration Section 04 - Multi-display configuration 1 - DualHead independent 2 - DualHead merged 3 - TripleHead independent 4 - TripleHead merged 5 - QuadHead independent 6 - QuadHead merged 7 - Pivot Section 05 - Dynamic configuration Section 06 - Troubleshooting Section 07 - Frequently asked questions Appendix A - Installer options Appendix B - Installed files Appendix C - Important preliminary information for new Linux users Section 01 - Description of this release ======================================== This release was tested with the following: Distributions: - Red Hat Enterprise Linux 5.2 WS - SuSE Linux Enterprise Server 11 - Fedora Core 9 - Fedora Core 10 - Open SuSE 11 - Ubuntu 8.04 - Ubuntu 8.10 Graphics cards: - M9120 PCIe x16 - M9120 Plus LP PCIe x16 - M9120 Plus LP PCIe x1 - M9125 PCIe x16 - M9140 LP PCIe x16 Display configurations: - Up to 4 displays, depending on the graphics card (some graphics cards are limited to 2 displays). - Single, Clone, Merged, and Independent modes. - Pivot support can be controlled for each display. Display resolutions: - Analog: up to 2048x1536 (up to 1920x1200 with a quad analog upgrade cable or with the M9140 LP PCIe x16). - Digital: up to 1920x1200 (up to 2560x1600 in DualLink for the M9125 PCIe x16). Note: The driver included in this package may be compatible with additional Linux distributions, provided that the installation requirements outlined in Section 02 are met. Note: Xdmx support is untested in this release. Section 02 - Installation requirements ====================================== - X Server (7.1.0 or later). To improve performance, a kernel module must be compiled specifically for the targeted kernel. To compile your kernel module, the following packages must be installed on your system: - Linux kernel 2.6 with the corresponding kernel source code and header files. - GCC compiler version 3.2 or later (up to 4.1.2). - Glibc 2.3.2 or later. - Binutils 2.13 or later. - Make 3.77 or later. Section 03 - Driver installation and configuration ================================================== The following steps will help you install the driver and start your X Server in cloned display mode: 1) Install the Matrox display driver. # su root [ENTER] # sh m9xdriver-x86_32-1.0.0.run [ENTER] or, depending on your system # sudo sh m9xdriver-x86_32-1.0.0.run [ENTER] 2) Verify the presence of an X Server configuration file: # cat /etc/X11/xorg.conf [ENTER] If you get an error message (such as "No such file or directory"), you'll need to create a new default X Server configuration file. To do this, type: # cd /root # X -configure # mv /root/xorg.conf.new /etc/X11/xorg.conf 3) Open the X Server configuration file for editing. # vi /etc/X11/xorg.conf [ENTER] For more information on how to use the 'vi' text editor, see Appendix C. 4) Select the Matrox M-Series driver. In the "Device section", replace the string 'Driver "somedriver"' with 'Driver "m9x"'. For example: Replace: Driver "vesa" with: Driver "m9x" 5) Select the appropriate graphics card address. In the "Device" section, enter the proper BusID value for your card. For example, if your Bus ID is 1:0.0, add the following line or edit the existing line to read: BusID "PCI:1:0:0" To obtain the BusID value for your card, use the command: # lspci -d 102b:* [Enter] You'll see the following output: 0000:01:00.0 VGA compatible controller: Matrox Graphics, Inc. Unknown device 0540 (rev 01) Ignore the first string of numbers (i.e. "0000"). In this example, the BusID would be PCI:1:0:0. Note: The output of lspci is in hexadecimal, and X Server config requires it in decimal. You need to convert the numbers. 6) Specify your default display pixel depth. In the "Screen" section, replace the string "DefaultDepth" with the desired bits-per-pixel value (8/16/24). For example: Section "Screen" Identifier "screen1" Device "device1" Option "monitor-mon0" "monitor1" DefaultDepth 24 EndSection 7) Reboot the system. # reboot [ENTER] After the reboot, the X Server should start automatically using the M-Series driver. If the system reboots in a text console, log in and type: # startx [ENTER] to manually start the X Server. For more information on the "Xorg config" file format, type 'man xorg.conf' in a shell terminal to view all options available in an X Server config file. For more information, see the Web sites http://xorg.freedesktop.org/wiki/ and http://www.x.org for X.org. Section 04 - Multi-display X.org configuration ============================================== The following explains how to manually modify your X Server configuration file to configure your driver in one of the multi-display configurations supported by your Matrox driver. The configurations are based on the RandR 1.2 specification. For more information, see its documentation found on the Web or in "man xorg.conf". In RandR, each display must have a name. For the m9x driver, the names are respectively "mon0", "mon1", "mon2", and "mon3". These names must be used in the "Screen" section of the xorg.conf to describe the configuration. For independent configurations, each "Device" section must specify the Option "Independent". You can copy and paste any of the statements below that apply to the configuration you want to enable. 1 - DualHead independent ------------------------ While using DualHead independent mode, each display can have different refresh rates and resolutions. Each display uses a different frame buffer. The following is a partial sample of an X Server config section: Section "Monitor" Identifier "monitor1" EndSection Section "Monitor" Identifier "monitor2" EndSection Section "Device" Identifier "device1" Driver "m9x" BusID "PCI:1:0:0" Screen 0 Option "Independent" EndSection Section "Device" Identifier "device2" Driver "m9x" BusID "PCI:1:0:0" Screen 1 Option "Independent" EndSection Section "Screen" Identifier "screen1" Device "device1" Option "monitor-mon0" "monitor1" DefaultDepth 24 EndSection Section "Screen" Identifier "screen2" Device "device2" Option "monitor-mon1" "monitor2" DefaultDepth 24 EndSection Section "ServerLayout" Identifier "X.org Configured" Screen "screen1" Screen "screen2" LeftOf "screen1" EndSection 2 - DualHead merged ------------------- While using DualHead merged mode, all displays use the same frame buffer. The following is a partial sample of an X Server config section: Section "Monitor" Identifier "monitor1" EndSection Section "Monitor" Identifier "monitor2" Option "RightOf" "monitor1" EndSection Section "Device" Identifier "device1" Driver "m9x" BusID "PCI:1:0:0" Screen 0 EndSection Section "Screen" Identifier "screen1" Device "device1" Option "monitor-mon0" "monitor1" Option "monitor-mon1" "monitor2" DefaultDepth 24 EndSection 3 - TripleHead independent -------------------------- TripleHead independent mode is similar to DualHead independent mode. It needs a new "Monitor", "Device", and "Screen" section. The new "Screen" section is added to the server layout section with the desired relative position. The following is a partial sample of an X Server config section: Section "Monitor" Identifier "monitor1" EndSection Section "Monitor" Identifier "monitor2" EndSection Section "Monitor" Identifier "monitor3" EndSection Section "Device" Identifier "device1" Driver "m9x" BusID "PCI:1:0:0" Screen 0 Option "Independent" EndSection Section "Device" Identifier "device2" Driver "m9x" BusID "PCI:1:0:0" Screen 1 Option "Independent" EndSection Section "Device" Identifier "device3" Driver "m9x" BusID "PCI:1:0:0" Screen 2 Option "Independent" EndSection Section "Screen" Identifier "screen1" Device "device1" Option "monitor-mon0" "monitor1" DefaultDepth 24 EndSection Section "Screen" Identifier "screen2" Device "device2" Option "monitor-mon1" "monitor2" DefaultDepth 24 EndSection Section "Screen" Identifier "screen3" Device "device3" Option "monitor-mon2" "monitor3" DefaultDepth 24 EndSection Section "ServerLayout" Identifier "X.org Configured" Screen "screen1" Screen "screen2" LeftOf "screen1" Screen "screen3" LeftOf "screen2" EndSection 4 - TripleHead merged --------------------- TripleHead merged mode is similar to DualHead merged mode. It needs a third "Monitor" section with the desired relative position. This new "Monitor" section must be declared in the "Screen" section and bound to the next available output. The following is a partial sample of an X Server config section: Section "Monitor" Identifier "monitor1" EndSection Section "Monitor" Identifier "monitor2" Option "RightOf" "monitor1" EndSection Section "Monitor" Identifier "monitor3" Option "RightOf" "monitor2" EndSection Section "Device" Identifier "device1" Driver "m9x" BusID "PCI:1:0:0" Screen 0 EndSection Section "Screen" Identifier "screen1" Device "device1" Option "monitor-mon0" "monitor1" Option "monitor-mon1" "monitor2" Option "monitor-mon2" "monitor3" DefaultDepth 24 EndSection 5 - QuadHead independent ------------------------ QuadHead independent mode is similar to DualHead independent mode. It needs two new "Monitor", "Device", and "Screen" sections. The two new "Screen" sections are added to the server layout section with the desired relative position. The following is a partial sample of an X Server config section: Section "Monitor" Identifier "monitor1" EndSection Section "Monitor" Identifier "monitor2" EndSection Section "Monitor" Identifier "monitor3" EndSection Section "Monitor" Identifier "monitor4" EndSection Section "Device" Identifier "device1" Driver "m9x" BusID "PCI:1:0:0" Screen 0 Option "Independent" EndSection Section "Device" Identifier "device2" Driver "m9x" BusID "PCI:1:0:0" Screen 1 Option "Independent" EndSection Section "Device" Identifier "device3" Driver "m9x" BusID "PCI:1:0:0" Screen 2 Option "Independent" EndSection Section "Device" Identifier "device4" Driver "m9x" BusID "PCI:1:0:0" Screen 3 Option "Independent" EndSection Section "Screen" Identifier "screen1" Device "device1" Option "monitor-mon0" "monitor1" DefaultDepth 24 EndSection Section "Screen" Identifier "screen2" Device "device2" Option "monitor-mon1" "monitor2" DefaultDepth 24 EndSection Section "Screen" Identifier "screen3" Device "device3" Option "monitor-mon2" "monitor3" DefaultDepth 24 EndSection Section "Screen" Identifier "screen4" Device "device4" Option "monitor-mon3" "monitor4" DefaultDepth 24 EndSection Section "ServerLayout" Identifier "X.org Configured" Screen "screen1" Screen "screen2" LeftOf "screen1" Screen "screen3" LeftOf "screen2" Screen "screen4" LeftOf "screen3" EndSection 6 - QuadHead merged ------------------- QuadHead merged mode is similar to DualHead merged mode. It needs two new "Monitor" sections with the desired position. These new "Monitor" sections must be declared in the "Screen" section and bound to the next available outputs. The following is a partial sample of an X Server config section: Section "Monitor" Identifier "monitor1" EndSection Section "Monitor" Identifier "monitor2" Option "RightOf" "monitor1" EndSection Section "Monitor" Identifier "monitor3" Option "RightOf" "monitor2" EndSection Section "Monitor" Identifier "monitor4" Option "RightOf" "monitor3" EndSection Section "Device" Identifier "device1" Driver "m9x" BusID "PCI:1:0:0" Screen 0 EndSection Section "Screen" Identifier "screen1" Device "device1" Option "monitor-mon0" "monitor1" Option "monitor-mon1" "monitor2" Option "monitor-mon2" "monitor3" Option "monitor-mon3" "monitor4" DefaultDepth 24 EndSection 7 - Pivot --------- To enable display rotation, add the following option to the "Monitor" section of your X Server config file: Option "Rotate" ["normal"|"left"|"inverted"|"right"] where "right" stands for clockwise rotation, "left" for counter- clockwise rotation, and "inverted" for 180-degree rotation. The following example sets the monitor to pivot clockwise: Section "Monitor" Identifier "monitor1" Option "Rotate" "right" EndSection Section 05 - Dynamic configuration ================================== To dynamically change the desktop configuration while running the X Server, use the "xrandr" command-line tool or the GUI installed with the distribution if it's xrandr 1.2 compatible. For information on the monitors currently connected and the supported modes for each monitor, type: # xrandr [ENTER] in a shell. This generates a list of all connected monitors (ex. "mon0, mon1, ..") and their supported modes. To change the resolution of a specific monitor, specify a mode from the mode list and the monitor's xrandr name. For example, to change the mode of monitor "mon0" to "1024x768", type: # xrandr --output mon0 --mode 1024x768 You can also control the pivot of a specific monitor. For example, to pivot the second monitor clockwise, type: # xrandr --output mon1 --rotate right You can also change the relative position of each monitor to combine them into a larger desktop. For example, to swap the second monitor from left to right while in DualHead mode, type: # xrandr --output mon1 --right-of mon0 For more information, see the documentation for "xrandr". Section 06 - Troubleshooting ============================ 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/lib/xorg/modules/drivers/m9x_drv.so [ENTER] # ls -l /lib/modules/`uname -r`/kernels/drivers/video/m9x.ko [ENTER] Forcing digital monitors ------------------------ Digital monitors are automatically detected by your Matrox driver. If your monitor isn't automatically detected by the driver, you can force your monitor type in the "Device" section of the configuration file. Option "mon0_forcedvi" "on" Option "mon1_forcedvi" "on" Option "mon2_forcedvi" "on" or Option "mon3_forcedvi" "on" Each number in the option name corresponds respectively to the output number used by the display. Disabling/enabling a kernel module ---------------------------------- With a kernel module, the processor can share some tasks with the graphics chipset, resulting in higher performance. To enable bus mastering with the Linux kernel, a Matrox kernel module must be compiled specifically for your system. In most configurations, the installation script compiles the kernel driver if the kernel source code is installed as mentioned in Section 02. To disable the kernel module, add the following option to the X Server config file in the appropriate "Device" section: Option "UseKernelModule" "off" If no option is specified, bus mastering is enabled by default if your system supports it. The following is an example of a "Device" section disabling bus mastering: Section "Device" Identifier "device1" Driver "m9x" BusID "PCI:1:0:0" Option "UseKernelModule" "off" EndSection Section 7 - Frequently asked questions ====================================== Q: Why does the installer stop when I try to run it? A: Your kernel source and headers may not be properly installed or they may not be supported. Q: What determines the color of the Matrox logo screen that appears when my X Server starts? A: The color depends on whether or not the kernel module is being used. Blue = The kernel module is being used. Bus mastering is in PCI mode. Magenta = The kernel module isn't being used or isn't available. Bus mastering is in local video memory. Q: Do you support AIGLX and OpenGL? A: No, OpenGL and 3D based desktops aren't supported by this driver. Q: Do you support the randr 1.2 extension? A: Yes, the randr 1.2 extension is fully supported. Q: Which driver should I set when installing Linux? A: During installation of your 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 the version of my X Server and now my configuration file no longer works. What can I do? A: When upgrading your X Server, you need to reinstall the Matrox driver package to make sure the appropriate driver components are installed. Q: I upgraded my Linux kernel and now X Server isn't using the kernel driver module and the Bus mastering is being done in local video memory (magenta logo screen). How do I re-enable the kernel driver? A: When upgrading your Linux kernel, you need to reinstall the Matrox driver package to make sure the appropriate kernel driver is compiled against your latest kernel. Q: Can I use Xinerama in my config file to join multiple displays and create a large virtual desktop? A: No, Xinerama isn't currently compatible with RandR 1.2. Instead, you can use Xdmx to join multiple displays. Q: My kernel module isn't loaded. A: Try to modprobe the kernel driver from a shell using the command # modprobe m9x [enter] to determine the cause of the problem. On some distributions, you may need to edit the file /etc/modprobe.d/unsupported-modules to allow the proprietary kernel module to load. Q: On Fedora Core 9, X Server won't start and I get an error message that my ABI version is wrong. What can I do? A: Update your "xorg-x11-server-common" and "libpciaccess" packages to their latest available versions. Appendix A - Installer options ============================== The following are valid options supported in the command line to be passed to the installer (used without quotation marks): --extract-only Extracts the files but doesn't run the installer portion. --uninstall Uninstalls the current driver. --installxonly Installs only the X Server driver without the kernel modules. Mostly used for thin client setups and to bypass installations where the kernel module couldn't be compiled. --nobackup Forces a driver installation without the creation of a backup script. Appendix B - Installed files ============================ The Matrox Linux driver package 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/lib/xorg/modules/drivers/m9x_drv.so - A kernel module. The kernel module adds bus mastering, memory management, and interrupts management. The kernel module is made up of two parts: a binary and an open source interface part. These parts are necessary because the kernel needs to be compiled specifically on your system. The kernel module is usually located in the following path: /lib/module//kernel/drivers/video/m9x.ko Appendix C - Important preliminary information for new Linux users ================================================================== Text editors ------------ Configuring a Linux system often requires editing text files. The following describes some text editors available to Linux users. gedit and kate -------------- Simple to use but require a graphical environment that may not be available. mcedit and nano --------------- Run in text mode and are relatively easy to use. However, they're not installed by default in most distributions. vi -- One of the most powerful text editors available. Installed by default by most distributions, but not user friendly. What follows is a basic overview to get you started. 'vi' operates in two modes: edit and command. On startup, 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 [Esc]. You can now access the type of functionality offered in a graphical application. Basic commands: i - Enter edit mode Esc - Enter command mode :w - Save :q - Quit root user --------- Once installed, most 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 3 ways to become 'root': - Log in as 'root'. - Use the substitute user command ('su') at the command prompt. This is the method used in the examples. - On some systems, use the 'sudo' utility. With this utility, you can run a specified program as 'root'. To use 'sudo', simply prefix the command you need with the 'sudo' keyword. For example: # sudo sh m9xdriver-x86_32-1.0.0.run [ENTER] We recommend you use the 'root' account only while installing your driver package. Return to your user account when the installation is completed.