------------------------------------------------------------------------------ DIAMOND Fire GL1 Graphics Accelerator DIAMOND Fire GL1 Video Driver for Linux Driver Version 4.0.2-2.3.1 ------------------------------------------------------------------------------ Please read the entire contents of this document. Information in this file may not appear in printed documentation or online help. This READ-ME file contains the following information: 1. GENERAL INFORMATION 1.1 Requirements 1.2 List of Product Files 2. INSTALLING THE DIAMOND FIRE GL1 SERIES VIDEO DRIVER 2.1 How to get the correct binary distribution package 2.2 Installing the driver using the Install.sh script 2.3 Generating a kernel with ISSE support (Kernel 2.2.x) 2.4 Generating a customized kernel module 2.5 Enabling AGP support 3. CHANGING THE VIDEO SETTINGS 3.1 Changing the settings using the firegl1config program 4. CONFIGURATION FEATURES AND INFORMATION 5. NOTES, PROBLEMS, AND LIMITATIONS 6. SERVICE, SUPPORT, AND SOFTWARE UPGRADES 1. GENERAL INFORMATION ---------------------- This driver is based on the xfree86 version mentioned in the document header. (see http://www.xfree86.org/4.0/ for documentation) You must install this version of xfree86 before installing the drivers for the DIAMOND Fire GL1. If your Linux distribution does not include the current version of XFree86, you must download the xfree86 4.0.2 binaries from 'ftp://ftp.xfree86.org/pub/XFree86/4.0.2/binaries/'. 1.1 Requirements ---------------- 1. Only Linux/x86 versions based on libc 6.1 (=glibc 2.1) and libc 6.2 (=glibc 2.2) are supported. 2. XFree86 Version 4.0.2 must be installed beforehand. Note: If you are a RedHat 7.0 user you are required to get a new plugin capable libGL.so.1.2 from XFree86.org. A full update to XFree86 Version 4.0.2 is highly recommended. 3. If you have a processor that is ISSE capable and install a ISSE enabled Linux kernel, the Fire GL1 driver can use a highly optimized ISSE OpenGL client driver. (ISSE: Internet Streaming Single-Instruction, Multiple-Data Extensions; an extension of the IA-32 instruction set in Pentium III processors) At the moment you can add ISSE support to the Linux kernel as follows: - apply a patch to the kernel (see 2.3) - recompile the kernel - install the recompiled kernel. NOTE: The AMD 3DNow! enhanced OpenGL driver does not need a kernel patch. NOTE: Kernel 2.4.x comes with Pentium 3 support already built in. You do not need the ISSE kernel patch. 4. To generate version-specific kernel modules on your local machine, you need a full kernel sources tree on your workstation machine. 1.2 List of product files ------------------------- ReadMe.txt - This document. Install.sh - The installer script. fglibc21.tgz - Binary distribution for ix86 systems with libc6.1 (=glibc2.1) ( e.g. SuSE 6.2/6.3/6.4/7.0, RedHat 6.1/6.2/7.0 ). fglibc22.tgz - Binary distribution for ix86 systems with libc6.2 (=glibc2.2) ( distributions that are newer than above versions ). 2. INSTALLING THE DIAMOND Fire GL1 VIDEO DRIVER ----------------------------------------------- 2.1 How to get the correct binary distribution package ------------------------------------------------------ First determine which binary distribution you need for your system. To find out which binary distribution you need, download the script 'Install.sh' and run it: sh Install.sh -check This should provide information on which binary distribution is suitable for your system. NOTE: Getting the correct binary distribution information may prevent you from wasting time by downloading the wrong distribution. 2.2 Installing the driver using the Install.sh script ----------------------------------------------------- Save the script 'Install.sh' and the downloaded binary distribution file into a single directory (choose a temporary location with enough space). Get super user (root) privileges and change (cd) to the selected directory. Then run the installer script as follows: sh Install.sh When the driver files are installed, the sytem asks you to configure the settings. Answer 'Y' when prompted for calling firegl1config. This will start the firegl1config program. Respond to the questions of the firegl1config program and save the settings to /etc/X11/XF86Config. 2.3 Generating a kernel with ISSE support (Kernel 2.2.x) -------------------------------------------------------- If your kernel does not have Pentium III ISSE support, you need a kernel patch to get benefit from the Pentium III ISSE instruction set. +++ The Fire GL1 driver was tested with a patched kernel 2.2.14 +++ The patches on 'http://people.redhat.com/mingo/mmx-patches/' may be useful. Please note that all these patches still represent only 'alpha' or 'beta' code. Our experience with version "mmx-2.2.14-A0" was quite positive. You must only use the exactly matching kernel source from www.kernel.org. Any distribution-specific kernel, e.g. 2.2.14-5.0 from RedHat or 2.2.14.SuSE may not work. +++ It is highly recommended to backup the old kernel sources before applying the patch! +++ Extract the kernel sources to a directory of your choice, typically in /usr/src. Make sure that the new linux kernel sources are referenced by a symbolic link called /usr/src/linux before continuing. Copy the patch file to /usr/src and extract it from there: - for a gzip-packed patch use 'zcat piii.gz | patch -p0 -E' - for unpacked patches use 'cat piii | patch -p0 -E' No queries or errors are displayed if your kernel matches exactly the kernel the patch was designed for. Change to '/usr/src/linux' and type 'make menuconfig' to start the kernel configuration program. Enter "Processor type and features". Select "PIII/Xeon/Deschutes" as Processor family to display ISSE or MMX2 menu items. For a fully working, ISSE-capable kernel select the following options: - Processor type and features (PIII/Xeon/Deschutes) Processor Family - [*] Enable CPU Specific (MMX/MMX2) Optimization Functions - [*] MTRR (Memory Type Range Register) support - Loadable Module Support - [*] Enable loadable module support - [*] Kernel module loader support Save your settings and leave the menuconfig program. Build your kernel. See the documentation of your distribution vendor for details. Install the newly compiled kernel and test it. +++ Keep your previous kernel bootable in case you experience problems. +++ In case of doubt or trouble please check the files /var/log/XFree86.0.log and /var/log/messages for hints on possible failures. After you have successfully compiled and installed the new, patched kernel, reboot your system with the new kernel. Install the driver for a second time. Use the Install.sh script again. Remember, you must be logged in with super user (root) privileges. Now the necessary kernel driver module and client driver will be installed. A software tool, called 'cpu_check' may be useful to check the system CPU and the kernel patch. 2.4 Generating a customized kernel module ----------------------------------------- The Fire GL1 is a graphics adapter that uses the performance capacity of your workstation intensively. Some features, like AGP support, busmaster DMA transfers, or memory mapping, need support from a precisely tailored kernel module. This module gets loaded at boot time and remains present for the driver all the time. (If the module is missing, you do not have hardware-accelerated 3D-support, but you can still use 2D at a reduced performance level.) The binary package comes with several fully working kernel modules for several distributions and kernel versions. So, in most cases, you don't need to build a kernel module. However, it is possible that none of the delivered kernel modules will fit your needs. For example: - if you have a new or customized Linux kernel, or - if you have kernel symbols versioning enabled. In these cases you must build the configured sources of your kernel at the location /usr/src/linux, which is allowed to be a symlink. Building a customized kernel module is an administrator's task. This is far less complex than building a new Linux kernel itself - you only need to manually invoke two shell scripts. The steps to perform a build are listed here: - get the matching Linux kernel source - setup that kernel source with the correct config file - go to /lib/module/firegl1/build_mod and start ./make.sh - go to /lib/module/firegl1 and start ./make_install.sh If you do not have hardware 3D support (run fireglinfo to check), or you have done any other important system change, e.g. a changed kernel, then you must start the kernel module build manually: Enter /lib/module/firegl1/build_mod and enter (as root) "./make.sh". This will force the creation of a new customer-tailored kernel module. Should the creation fail you will find hints on the cause in the shell and in the related logfile called "make.log". Note: in some configurations you will see lines like: compiling... /tmp/ccOWu6AI.s: Assembler messages: /tmp/ccOWu6AI.s:9: Warning: Ignoring changed section attributes for .modinfo This warning comes due to a specific combination of Linux kernel sources and C compiler. Similar messages do appear if you build your own Linux kernel. This is a widely known Linux issue that does not affect your builds and therefore you can ignore this warning. To set up a kernel module build you need the Linux kernel headers that match exactly the kernel you are running. This means: - if the kernel is configured SMP with P-III support and agpgart enabled - you must have a kernel source that is configured exactly the same way. If your kernel was already built by your Linux distribution: - Get the related source RPM file - Extract the matching configuration settings contained there. - Set up your kernel source with these settings - Perform "make dependencies" ("make dep"). Note: If you want to build multiple modules for some reasons we highly recommend a "make distclean" between each cycle. In case you can no longer build the matching kernel headers it is best to - build a new kernel from scratch that is optimal tailored to your machine, - install it and boot it - if it runs, continue with setup. To perform the final step on each customized kernel module build: - Go to /lib/modules/firegl1 - Start ./make_install.sh This copies the matching kernel module into the loadable modules tree of your running kernel. The script further does the required update of the module loader dependency list. If you have several identical machines the kernel modules build on one machine are as exchangeable as the related Linux kernels are themselves. Copy the module into /lib/modules/firegl1 and restart the ./make_install.sh script. 2.5 Enabling AGP support ------------------------ Several up-to-date distributions already come with built-in and, possibly, activated AGP support like an 'agpgart' kernel module, for example, SuSE 7.0 or RedHat 7.0. If the kernel module of the graphics driver detects this feature, it tries to use it by connecting to the AGP module. To verify if the related module is loaded, enter 'lsmod' as root. When the XServer is running and the connection was established, the usage count of the agpgart module is listed as different from zero. Note: agpgart is not a 'hard dependency' for module operation. Therefore the modules dependency list does not list it as a requirement for the firegl1 kernel module. This is to allow the system's administrator maximum control of what he wants to run on a specific machine. The latest version of the driver's kernel module is shipped with 'built-in' agp support. If your distribution's kernel setup does not provide agpgart-compatible services, the built-in agpgart module will be used. 3. CHANGING THE VIDEO SETTINGS ------------------------------ +++ Use only the firegl1config tool to generate the XF86Config file! +++ To generate the XF86Config file you must know the type of monitor, keyboard, and mouse of your system . IMPORTANT: Do not specify a monitor type with a horizontal sync rate that exceeds the performance scope of your actually attached monitor. ++++ Wrong monitor settings may damage your monitor! ++++ 3.1 Changing the settings with firegl1config --------------------------------------------- 1. Log on with root privileges. 2. Run the Fire GL1 configuration program. Enter: firegl1config 3. Answer the questions of the firegl1config program and save the settings to /etc/X11/XF86Config. 4. Restart the XServer. 4. CONFIGURATION FEATURES AND INFORMATION ----------------------------------------- 1. To check, if 3D acceleration is working properly, use the 'fireglinfo' program installed together with the Fire GL1 driver. To run the test program enter: fireglinfo Typical output information (3D acceleration is working properly) may read like this: OpenGL vendor string: Diamond Multimedia OpenGL renderer string: Fire GL1 (ISSE) OpenGL version string: 1.2.1118 2. There are other tools, for example, from XFree86 group that may be of some help, e.g. xdpyinfo or glxinfo. 3. For information on the CPU support of your running system run the application "cpu_check". 5. NOTES, PROBLEMS, AND LIMITATIONS ----------------------------------- 1. You cannot perform a graphic installation of Linux with the Fire GL1. You need a different VGA-compatible graphics board. 2. Corel users: It is not yet possible to install Corel Linux (Corel Linux 1.0 / 1.1) using a DIAMOND Fire GL1 graphics adapter. To install drivers for the Fire GL1, you must first install Linux and the drivers for the Fire GL1 using another VGA-compatible board before you can install the Fire GL1 graphics adapter into your system. To run this driver version with hardware acceleration, it is necessary to install a kernel (together with other system-depending settings, e.g. SCSI support) with, at least, the following settings - Processor type and features (PPro/6x86MX) Processor Family - [*] MTRR control and configuration - Loadable Module Support - [*] Enable loadable module support - [*] Kernel module loader support To get benefit from ISSE you need the following settings (patch installed, call as root, 'make menuconfig'): - Processor type and features (PIII/Xeon/Deschutes) Processor Family - [*] Enable CPU Specific (MMX/MMX2) Optimization Functions - [*] MTRR (Memory Type Range Register) support - Loadable Module Support - [*] Enable loadable module support - [*] Kernel module loader support For generating a new kernel please consult your Linux manual CAUTION! Be careful when generating a new Linux Kernel!!!! Make sure you have an emergency boot diskette ready in case your systems stalls and does not start again! 3. RedHat users: To install RedHat Linux together with the Fire GL1, you must install it in text mode. ( after CD boot choose text ). After RedHat Linux and the Fire GL1 drivers are installed, edit the file "/etc/inittab" Change the line "id:3:initdefault:" to "id:5:initdefault:" Reboot the system. 4. SuSE users: Use YAST1 to install SuSe Linux together with the Fire GL1. SuSE 6.3: boot with CD2, SuSE 6.4: boot with CD1. At the "boot:" prompt type "manual" within 3 secondes and press . When asked, select 'Yast1'. After installing the 'on CD' XServer 4.0 (at /cdrom/unsorted/XFree86-4.0) you may have to generate or redo some symbolic links to complete the installation. - The symbolic link /var/X11R6/bin/X must point to the (again) symbolic link /usr/X11R6/bin/X which itself must point to the file /usr/X11R6/bin/XFree86 . Use 'ln -s -f /usr/X11R6/bin/XFree86 /var/X11R6/bin/X' and 'ln -s -f /var/X11R6/bin/X /usr/X11R6/bin/X'. Also, you may have to rename an older glx library (this is fixed since XFree86 4.0a): - delete the file /usr/X11R6/lib/modules/glx.so (or move it to a backup location). The new glx library will be libglx.a at '/usr/X11R6/lib/modules/extensions/'. - create (change, if it exists already) a symbolic link /usr/lib/libGL.so.1 pointing to /usr/X11R6/lib/libGL.so.1 by using 'ln -s -f /usr/X11R6/lib/libGL.so.1 /usr/lib/libGL.so.1'. - create (change, if it exists already) the symbolic link /usr/lib/libGL.so.1.2 pointing to /usr/X11R6/lib/libGL.so.1 by using 'ln -s -f /usr/X11R6/lib/libGL.so.1 /usr/lib/libGL.so.1.2'. Install the FireGL1 driver and reboot your system. Start the X server with startx and test your Xserver system using '/usr/X11R6/bin/fireglinfo' Typical program output information for a properly installed system: ------------------------------------------------------------------- OpenGL vendor string: Diamond Multimedia OpenGL renderer string: Fire GL1 (ISSE) OpenGL version string: 1.2.1118 Output information for a system with bad libGL.so links: --------------------------------------------------------- No default configuration 'mesa3.1' in init file OpenGL vendor string: Brian Paul OpenGL renderer string: Mesa X11 OpenGL version string: 1.2 Mesa 3.1 Wrong glx library used (old library not renamed or deleted): ------------------------------------------------------------ Xlib: extension "GLX" missing on display ":0.0". Xlib: extension "GLX" missing on display ":0.0". Error: couldn't find RGB GLX visual! 5. Limitations - Libc 6.0 systems are not supported. 6. OpenGL Applications, DRI, DRM please refer to the Precision Insight Documentation README.DRI located at /usr/X11R6/lib/X11/doc or http://www.xfree86.org/4.0/DRI.html 7. Other OpenGL implementations - Your system may have some other OpenGL compatible libraries (i.e. MesaGL) installed - Your applications may link to other GL libs than provided with the Fire GL1. This may result in software rendering techniques which are quite slower than the hardware-accelerated render libs of the Fire GL1. In this case we recommend that you consult an experienced Unix/Linux expert who can either recompile the application appropriately or can modify your library environment that the correct libs are found. If you are not sure what libs your program is using: - type in ldd and you will get extended information. Especially if the GL libs come from your X11R6 subdirectory the application uses hardware. A reference to libGL.so.1.2 is rather good, however, a reference to, for example, libMesaGL.030300 is rather unlikely to serve your needs. For other references, please check if the file is a symlink and which file is the final target of the existing symlinks. Also, please note that RedHat 7.0 only supplies a non-plugin-enabled libGL.so.1.2. Therefore you have to replace this file with the improved equivalent from the XFree86.org ftp site. Fire GL1 only supports Xfree86 4.0.2, so we recommend that you upgrade to X4.0.2 and related drivers. 8. DRI and Security The Section "dri" in your XF86Config file may, for example, look like: Section "DRI" Group "video" Mode 0660 EndSection This implies that only users assigned to the group "video" can use 3D Hardware acceleration. To add a user to the group "video", do the following: - edit [as root] the file /etc/group, - search for "video" - add the new user(s) at the end of the 'video' line, separated by a comma (,). Example: adding a new user 'henryc' to video:x:33:frankh,michaelg will result in video:x:33:frankh,michaelg,henryc 9. Old GLX Library Files If there is a glx library file other than libglx.a, for example, libglx.so., or similar, in directory /usr/X11R6/lib/modules/extensions, an old graphics driver installation may prevent a correct XServer access to the glx library. Rename any glx library file(s), except of libglx.a, or move it/them to another directory. 10. Commonly used OpenGL utility libraries (GLU, GLUT) Most distributions come with a complete set of OpenGL utility libraries. Sometimes running a specific application may require a specific library version which is not in the system. Since most libs are exchangeable (libMesaGLU.??? -> libGLU.so, libMesaGLUT -> libGLUT) for most applications all you need is - create a symlink to the existing target - run 'ldconfig' afterwards. Since these libs are running in user mode this modification is not critical. Normally your application will run smoothly. In worst case you will get a segmentation fault or an unresolved external. . Typical locations for libraries are: - /lib - /usr/lib - /usr/local/lib - /usr/X11R6/lib Make sure that there are no duplicate names so that you know what gets active. If some application requires a specific lib in a specific tree consider to create a symlink from the applications location to your preferred location rather than moving the files around each time. A typical error scenario is that you have an application which uses the GLU tesselation API but you have only MesaGLU (e.g. Mesa version 3.4). Your application will prompt you about unresolved symbols that start with 'gluTess'. In this case go to the download section of http://www.mesa3d.org. There you will find ready-to-install packages of the open source SGI sample implementation of GLU. Currently the direct link to the download location is: ftp://mesa3d.sourceforge.net/pub/mesa3d/SI-GLU/ where the file oss-opengl-glu-20000925-1.i386.rpm should work for you. For the GLUT library, you will find the latest release version at http://reality.sgi.com/mjk_asd/glut3/glut3.html for free download. Since the glut library is released in less frequent cycles, some of the attached sample programs may show errors. Sometimes you can find a fixed source for a sample in the glut/win32 package at http://www.xmission.com/~nate/glut.html because of the shorter release cycles there. Note that this package currently does not compile under Linux, since the project's work was not focussed on this target for a while - but this may possibly change. You must move the selected source files into a regular GLUT-3.7 environment. There are other more or less important toolkits available. Some of them are included in GLUT (like gle, mui, glsmap) and others are distributed separately. It is beyond the limited scope of this document to further evaluate this area. In any case it is the responsibility of the respective toolkit team to supply the latest releases and doing OpenGL-compatible implementations. 11. RedHat Linux 7.0 The 'desktop setup' option is sufficient to get your workstation running with our graphics card. Several common tools (like the binutils) are required for setup. Also you may have to select (or install manually afterwards) the XFree86 4.0.1 rpm packages. You may need to create a symlink for the XServer binary as described in Section 5 point 4. Note: We recommend that you obtain X4.0.2 as described above. For running RedHat 7.0 get Xbin.tgz from the ftp at XFree86.org in the glibc2.1 version. You have to replace your already installed libGL.so.1.2 file. This is necessary since your original library is likely missing 'plugin' capability and therefore could prevent running hardware-accelerated OpenGL. For any Linux, and especially for RedHat, it is recommended to have a real LoginShell for working as root. - Log into the system directly from the console or - Use the SubstituteUser command with 'su -l' from any user and any shell. This will set all required paths for your root environment. 12. Linux kernels with built-in dri/drm support Some newer Linux kernel sources already come with a few XFree86 kernel modules for miscellaneuous graphics adapters. Theses files are not compatible with FireGL drivers. They are not required for running the Fire GL with its drivers. As of today there is no perfect implementation of the XFree86 kernel driver loading process. Especially if you have multiple kernel drivers selected and compiled directly into your Linux kernel, XFree86 may no longer start the repsective FireGL kernel module automatically. It simply scans all present dri devices and concludes that dri is active but there is no suitable driver. Thus the required kernel module is not loaded. Solutions for the above scenario: - don't compile any dri/drm devices hard into your Linux kernel, if you need other modules than provided by FireGL: use modules. - manually load the FireGL kernel modules before starting your XServer. This will force the FireGL modules to get loaded and properly detected. 13. Corel Linux Linux drivers for the Fire GL1 are not bundled with COREL(R)-LINUX(R) OS. Please disregard any information to the contrary in the Fire GL1 User's Guide. 14. GL Quake Benchmark Please ensure that the mode, in which you want to test the benchmark quake at full screen, is referenced in the 'modes' line of your XF86Config file. For example, if you are running your XServer in 1280x1024 and you want to benchmark quake in the 800x600 mode, your modeline must read like: modes "1280x1024" "800x600" 6. SERVICE, SUPPORT, AND SOFTWARE UPGRADES ------------------------------------------ Video driver updates can be obtained from the following web location: http://www.firegl.com -> DRIVERS Please send any feedback and bug reports to http://www.firegl.com -> SUPPORT -> FEEDBACK Thank you!