Imagination Technologies, Ltd. Linux Driver README =================================================== Copyright 2003 Imagination Technologies Ltd All rights reserved. =================================================== CONTENTS ======== Introduction Installation Instructions SuSE, Red Hat or Mandrake with vendor kernels Rpm based system with custom kernel Non-rpm based system XFree86 Configuration SuSE Red Hat & Mandrake Configuration Options Verifying your installation Installed Components FAQs Known Issues Feedback Change Log INTRODUCTION ============ The Imagination Technologies Linux Driver kit provides 2D and 3D acceleration for PowerVR KYRO family of graphics chips running in 16 and 32 bpp depths. The drivers are based on the standard DRI mechanism shipped with XFree86 > 4.0. This is the README for driver version 2.01.21-7. The license for installation and use of this software is found in: Red Hat: /usr/share/doc/powervr-2.00.20/LICENSE.TXT SuSE: /usr/share/doc/packages/powervr/LICENSE.TXT Mandrake: /usr/share/doc/powervr-2.00.20/LICENSE.TXT Other distributions: /usr/share/doc/powervr/LICENSE.TXT INSTALLATION INSTRUCTIONS ========================= Installation instructions depend upon your Linux configuration. Choose the appropriate section from the list below: * SuSE, Red Hat, or Mandrake running the vendor supplied kernel * rpm based system with a custom kernel * non-rpm based system SuSE, Red Hat or Mandrake with vendor kernels ============================================== Download the package appropriate for your system (see list below). For all distributions, first quit the X server and return to the console before installing. Run the command indicated below as root: SuSE ---- rpm -Uvh powervr-2.01.21-7.suse82.i586.rpm Note: Depending on how SuSE was installed the rpm may indicate that a required package is missing (xf86_glx). This package should be installed and the PowerVR package should then install cleanly. See this document for more information: http://sdb.suse.de/en/sdb/html/xf86glx_int.html Red Hat ------- For i386 class Intel Machines (Uni processor only) rpm -Uvh powerv-2.01.21-7.rh90.i386.rpm For i686 class Intel Machines (Uni processor only) rpm -Uvh powervr-2.01.21-7.rh90.i686.rpm For AMD Athlon Machines (Uni processor only) rpm -Uvh powervr-2.01.21-7.rh90.athlon.rpm Mandrake -------- Mandrake 9.0: rpm -Uvh powervr-2.01.21-7.mdk90.i586.rpm In all systems above, to complete the installation for the first time, the X server must be configured as described in the "XFree86 Configuration" section. Rpm based system with custom kernel =================================== Requirements: linux kernel 2.4.x or >= 2.5.8, source in /usr/src/linux. Download powervr-2.01.21-7.src.rpm. Run the following as root: rpm --rebuild powervr-2.01.21-7.src.rpm If running Red Hat 8.0 (or another distribution with a newer version of rpm), the command is "rpmbuild" instead of "rpm". Look for a line near the end of the output which says where the resulting rpm is being placed. This line will read something like this: Wrote: /usr/src/redhat/RPMS/i386/powervr-2.01.21-7.i386.rpm Run "rpm -Uvh" on the indicated file. For this example, the command would be: rpm -Uvh /usr/src/redhat/RPMS/i386/powervr-2.01.21-7.i386.rpm To complete the installation for the first time the X server must be configured, described in the "XFree86 Configuration" section. Non-rpm based system ==================== Requirements: linux kernel 2.4.x or >= 2.5.8, source in /usr/src/linux. Download powervr-2.01.21-7.tgz. Run the following commands as root: tar zxvf powervr-2.01.21-7.tgz cd powervr-2.01.21-7 make install Slackware distribution note: if you are using the original kernel and kernel source that were installed, check if the source is configured the same as the kernel you are running. In particular a SMP mismatch will cause the resulting powervr kernel module to fail to depmod/insmod with kernel_flag undefined. To complete the installation for the first time the X server must now be configured, described in the "XFree86 Configuration" section. XFREE86 CONFIGURATION ===================== Generally the XFree86 configuration process only needs to be done the first time the KYRO driver is installed, unless another video card has be installed in the interim. Follow the appropriate instructions below, depending on yor Linux configuration: * SuSE * Red Hat & Mandrake SuSE ---- The SaX2 utility on SuSE can be used to easily set up the X configuration. SuSE 8.0: 1) Run "sax2 -b /var/opt/sax/profile/kyro -m 0=powervr" 2) SaX2 will ask if you want to enable 3D. Answer "yes". 3) SaX2 will then show its configuration panel. Select "Change configuration" to setup the mouse, keyboard, and desktop. Make sure the color depth is set to 16bit or 24bit. 4) After pressing finish to exit SaX2, run the command "switch2xf86_glx" from a command prompt as root. This changes some symlinks on the system so that OpenGL is not hardcoded to Mesa. 5) Restart X. Problems and Troubleshooting ---------------------------- Quake3 explicitly tries to open the shared library "libGL.so". This may not exist on SuSE systems or may be a symbolic link to the Mesa3D software rendering library, which will result in very slow rendering. The solution is to execute Quake3 the first time with the command: quake3 +set r_gldriver /usr/lib/libGL.so.1 This setting is then saved in: ~/.q3a/baseq3/q3config.cfg and from next time on Quake3 can simply be executed with "quake3". SuSE 8.2 -------- For SuSE 8.2 and above follow the instructions below rather than the ones from the general SuSE category. 1) /etc/X11/XF86Config file needs to be manually changed: a) First you must determine the busID of your KYRO card, this is done by the command: /sbin/lspci | grep VGA | grep SGS This should result in an output of the form: XX:YY.Z VGA compatible controller: SGS Thomson Microelectronics: Unknown device 0010 (rev BB) where XX:YY.Z is the bus ID of the device BB is the type of KYRO 01 = KYRO-I, 07 = KYRO-II b) Edit the XF86 config file (/etc/X11/XF86Config) to modify the line: BusID "PCI:1:0:0" to be BusID "PCI:XX:YY:Z" c) identify Section "Device" and change Driver to be "powervr" 2) Run the command "switch2xf86_glx" from a command prompt as root. This changes some symlinks on the system so that OpenGL is not hardcoded to Mesa. 3) Restart X. Problems and Troubleshooting ---------------------------- Quake3 explicitly tries to open the shared library "libGL.so". This may not exist on SuSE systems or may be a symbolic link to the Mesa3D software rendering library, which will result in very slow rendering. The solution is to execute Quake3 the first time with the command: quake3 +set r_gldriver /usr/lib/libGL.so.1 This setting is then saved in: ~/.q3a/baseq3/q3config.cfg and from next time on Quake3 can simply be executed with "quake3". Red Hat & Mandrake ------------------ Red Hat and Mandrake (unlike SuSE) do not provide tools to easily automate XF86 configuration, as the standard tools provided only recognize devices of which XF86 itself is aware of, and KYRO is not among these. If your configuration is simple, i.e. standard type of mouse, keyboard and only one graphics card it is recommended, unless you are expert at XF86 configuration, that you base your config file on the supplied sample and modify as per the following guidelines. 1) First you must determine the busID of your KYRO card, this is done by the command: Red Hat: /sbin/lspci | grep VGA | grep SGS Mandrake: /usr/bin/lspci | grep VGA | grep SGS This should result in an output of the form: XX:YY.Z VGA compatible controller: SGS Thomson Microelectronics: Unknown device 0010 (rev BB) where XX:YY.Z is the bus ID of the device BB is the type of KYRO 01 = KYRO-I, 07 = KYRO-II 2) Now copy the sample XF86 config file (/etc/X11/XF86KyroSampleConfig) to /etc/X11/XF86Config-4. If there is an existing XF86Config-4 file rename to something safe first. 3) Edit the XF86 config file (/etc/X11/XF86Config-4) to modify the line: BusID "PCI:1:0:0" to be BusID "PCI:XX:YY:Z" Notice that XX, YY are returned as hex while XF86Config-4 must have decimal values. 4) Again in the XF86 config file uncomment the mouse appropriate section for your mouse, either PS/2 intellimouse or 2 button PS/2 mouse. The country code of your keyboard can also be edited at this time, it is immediately above the mouse sections. 5) Uncomment the appropriate font server section (located at the top of the file immediately after the serverlayout section). 6) Check that there is a symlink from /etc/X11/X to /usr/X11R6/bin/XFree86 (there may already be a symlink from /etc/X11/X, this should be removed) i.e if [ -e /etc/X11/X ]; then rm -f /etc/X11/X; fi; ln -s /usr/X11R6/bin/XFree86 /etc/X11/X Note: On some systems the link to X may be somewhere else, to /usr/X11R6/bin/X for instance, but otherwise the procedure is the same. The path variable for the X startup process should be examined to see where the link to X may be. 7) Run startx Problems and Troubleshooting ---------------------------- The above (1-6) is aimed at simple standard configs. If you have a more complex setup or less common input devices a suggested approach is to replace the KYRO with a card which XF86 knows of, and generate a XF86Config file using a standard tool. Once generated the section relating to the temporary video card is removed and replaced with the appropriate lines from the sample config file. Additionally ensure that the "Module" section contains the lines: Load "GLcore" Load "dri" Load "glx" and that the following section is included Section "DRI" Mode 0666 EndSection Configuration Options --------------------- A list of possible configuration options. These should be left as defaults unless you are experiencing problems. Option "SWCursor" "boolean" Enable or disable software rendering of the X cursor. Default: off. Option "HWCursor" "boolean" Enable or disable hardware rendering of the X cursor. Default: on. Option "NoAccel" "boolean" Enable or disable 2D hardware acceleration. Default: off. Option "PixmapCacheLines" "integer" Number of lines in the offscreen pixmap cache used by XAA. Default: VirtualY of screen. VERIFYING YOUR INSTALLATION =========================== To check your installation, run "glxinfo". The output should contain the lines: OpenGL vendor string: Imagination Technologies OpenGL renderer string: PowerVR KYRO OpenGL version string: 1.2.1 INSTALLED COMPONENTS ==================== * XFree86 2D driver (/usr/X11R6/lib/modules/drivers/powervr_drv.o) * XFree86 DRI component (/usr/X11R6/modules/dri/powervr_dri.so) * kernel DRM module (/lib/modules/`uname -r`/char/drm/powervr.o) * internal libraries (/usr/lib/lib{PVR2D,PVR2OS,PVRMMAP,SGL2,SGLMID7B}.so) * library symlink (/usr/X11R6/lib/modules/drivers/libPVR2D.so) FAQs ==== 1) Undefined symbol "MTRR_TYPE_WRCOMB" when compiling the drivers. This means the kernel you are trying to compile against does not have MTRR support. SOLUTION: reconfigure the kernel to support MTRR, compile and install it and then compile and install the PowerVR drivers. 2) "can't find powervr module" error reported after running startx (XFree86 quits without reaching graphic mode) It is possible the kernel module did not load due to undefined symbols. To check this, as root try to load manually the module: "modprobe powervr.o". If it reports undefined symbols then you have installed a package which does not match your distribution/kernel. Download either the .tgz or .srpm package and install that. 3) error message regarding missing k_deflt when installing the rpm package under SuSE. This means you are either missing the kernel sources alltogether or the kernel source package you have installed does not match the driver version you are installing. Note: For further FAQs and help on using PowerVR cards with Linux try one of the many developer or fan sites e.g. http://www.pvr-net.com KNOWN ISSUES ============ No multiple video card support. This will be supported in a future release. Mode timing (besides vertical refresh) and sync polarity from the XF86Config mode lines are ignored by the driver. This will be resolved in a future release. This driver has not been tested on SMP systems. Tuxracer commercial version will not run. Issue is being discussed with tuxracer developers. If an OpenGL application is forcibly terminated by closing the X connection then there may be leftovers on the desktop. This appears to be a problem in the DRI infrastructure the driver is based upon. Mandrake 9.0 systems with the default kernel might experience random kernel crashes. This is due to a security patch that Mandrake installs and interferes with our kernel module. This security patch does not exist in any other standard kernel version. The solution is either to recompile the kernel while making sure the GRsecurity is turned off, install the kernel and then recompile and install the PowerVR drivers, or install a standard stock kernel (which will not have the patch). FEEDBACK ======== Please report bugs to: linux_bugs@powervr.com As these drivers are unsupported drivers we cannot guarantee that bugs will be fixed, but we will do our best. When filing a bug report, please include the following information: Type of KYRO card Version of PowerVR drivers Which driver package was used for installation Processor Motherboard chipset Amount of memory Kernel version Linux distribution XFree86 version Window manager and/or desktop environment Application (and version) experiencing the problem Steps to reproduce the problem For general queries or comments regarding the PowerVR Linux drivers, write to: linux@powervr.com CHANGELOG ========= powervr-2.01.21-7 Fixed: startup problem on some system configurations Added: support for gcc 3.x compilers and kernels compiled with gcc 3.x powervr-2.00.20-427 Fixed: Xv overlays sometimes vanishing/reappearing after geometry change Fixed: Unreal Tournament 2003 problems powervr-2.00.20-369 Added: AGP support Added: Xv support Added: DPMS support powervr-2.00.20-234 Fixed: drivers not working on some system configurations Fixed: XawTV startup abort Added: gamma support Added: .tgz and .src.rpm packages powervr-2.00.20-180 Initial public beta release