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