[English] README.TXT MATROX GRAPHICS INC. 2010.05.21 Matrox M-Series Linux Display Driver v1.2.4 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.2.4.run". If you're using the 64-bit package, use "m9xdriver-x86_64-1.2.4.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 - Xinerama Section 07 - Troubleshooting Section 08 - 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.3 WS and 5.4 WS - SuSE Linux Enterprise Server 10 and 11 - Fedora Core 10 - Fedora Core 11 - Open SuSE 11 and 11.1 - Ubuntu 8.10 - Ubuntu 9.04 - Ubuntu 9.10 - Ubuntu 10.04 Graphics cards: - M9120 PCIe x16 - M9120 Plus LP PCIe x16 - M9120 Plus LP PCIe x1 - M9125 PCIe x16 - M9128 LP PCIe x16 - M9138 LP PCIe x16 - M9140 LP PCIe x16 - M9148 LP PCIe x16 - M9188 ATX PCIe x16 Display configurations: - Up to 4 displays per GPU, depending on the graphics card (some graphics cards are limited to 2 displays). - Joined desktop with Xinerama to provide a larger virtual desktop. For limitations with Xinerama, see Section 06. - 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 (as well as 2560x1600 for DisplayPort products, and in dual-link mode for 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. Section 02 - Installation requirements ====================================== - X Server (7.1.0 or later). To improve performance and for OpenGL support, 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.4). - 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.2.4.run [ENTER] or, depending on your system (like Ubuntu) # sudo sh m9xdriver-x86_32-1.2.4.run [ENTER] 2) Make sure an X Server configuration file exists: # 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) Restart the system. # reboot [ENTER] After the system restarts, the X Server should start automatically using the M-Series driver. If the system restarts 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 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 without Xinerama, 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 additional "Monitor", "Device", and "Screen" sections. 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 additional "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 the following in a shell: # xrandr [ENTER] This generates a list of all connected monitors (for example, "mon0, mon1, ...") and their supported modes. However, because X server version 7.1.x doesn't support the xrandr 1.2 protocol, it only provides information about the first monitor. 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 - Xinerama ====================== Xinerama can be used to join the frame buffers of multiple GPUs to provide a larger virtual desktop for X server. To use Xinerama, you must configure each GPU individually. You can do this by defining a Screen, a Device, and a Monitor section for each GPU in the config file. You must also add a ServerLayout section in the X server config file specifying the placement of each screen relative to each other. You must also specify the option Xinerama in this section. A possible ServerLayout section with Xinerama enabled could look like this: Section "ServerLayout" Option "Xinerama" "on" Identifier "ServerLayout0" Screen "Screen0" Screen "Screen1" RightOf "Screen0" InputDevice "Mouse0" "CorePointer" InputDevice "Keyboard0" "CoreKeyboard" EndSection The following limitations apply when using Xinerama: - All "Screen" sections must use the same DefaultDepth. - The dynamic reconfiguration of the monitors using xrandr isn't supported (see Section 05). - The "Indepedent" option can't be used in the config file. That is, each GPU can only support one frame buffer at a time. - The desktop layout doesn't provide information on the individual monitors connected to the GPU (for example, the position and resolution of each monitor connected). It provides information only on the frame buffer of each GPU. So, for example, a window will maximize across all the monitors connected to a particular GPU. - OpenGL is supported only on the first initialized GPU. Section 07 - 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] # ls -l /usr/lib/xorg/modules/extensions/libglx.a [ENTER] # ls -l /usr/lib/libGL.so -> /usr/lib/libGL.so.1 [ENTER] # ls -l /usr/lib/libGL.so.1 -> /usr/lib/libGL.so.2.0.0 [ENTER] # ls -l /usr/lib/libGL.so.2.0.0 [ENTER] Resolving conflicts with /usr/lib/libGL.so ------------------------------------------ If other shared libraries (files with the ".so" extension) are conflicting with Matrox libraries, "ldconfig" (the library manager) may create incorrect symlinks. We recommend you manually remove or move conflicting libraries, rerun "ldconfig", and check that correct symlinks were made. Verifying that applications are using appropriate libraries ----------------------------------------------------------- Use the 'ldd' command on a 3D application to check that it's using the appropriate libraries. For example, "ldd glxgears | grep libGL.so" should give you: libGL.so.1 => /usr/lib/libGL.so.1 [ENTER] The "/usr/lib/libGL.so.1" should be a symbolic link pointing to "/usr/share/MSeries/current/libGL.so.2.0.0". If this isn't the case, either remove the conflicting library or adjust the LD_LIBRARY_PATH environment variable. For more information, see the "ldconfig" and "ldd" man pages. 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 the kernel module, it 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, the kernel module is enabled by default if your system supports it. The following is an example of a "Device" section disabling the kernel module: Section "Device" Identifier "device1" Driver "m9x" BusID "PCI:1:0:0" Option "UseKernelModule" "off" EndSection If you don't use use the kernel module, you won't be able to run OpenGL applications. Section 08 - Frequently asked questions ======================================= Q: Do you support AIGLX extension? A: No, 3D based desktops aren't supported. 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 the randr 1.2 extension? A: Yes, the randr 1.2 extension is fully supported, except when Xinerama is used. 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 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: After upgrading my Linux kernel, X Server no longer uses the kernel driver module and 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 using your latest kernel. 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 . - A GLX extension module. The GLX extension module is an interface between the OpenGL library and the X Server. The GLX extension module is usually located in the following X Server extensions path /usr/lib/xorg/modules/extensions/libglx.so . - An OpenGL library. This library allows 3D applications to use the OpenGL API. It processes the commands and sends them to the kernel module and X server. The OpenGL library is usually located in the following software library path /usr/lib/libGL.so.2.0.0 with two symlinks to /usr/lib/libGL.so and /usr/lib/libGL.so.1 . 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.2.4.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.