[English]
README.TXT               MATROX GRAPHICS INC.           2005.03.07

            Matrox Parhelia, Millennium P650/P750, QID, HR256
                         LINUX Display Driver
                            v1.4.1 Beta Pro

Note: This document and the associated software are currently only
available in English. We apologize for the inconvenience.


Contents
========

- Description of this release
- Available configurations
- Using TripleHead (Parhelia and Millennium P750 only)
- Sample XF86Config Files
- Changing the amount of offscreen memory
- Using digital monitors
- Using a hardware accelerated mouse-pointer
- Binary Installation
- Enabling bus mastering
- Enabling TV out
- Video Blitting
- Enabling dual and quad head support for HR256 and QID
- Kernel module options
- Known driver problems
- New features


Description of this release
===========================

Supported XFree86 versions:
- 4.2.0
- 4.2.1
- 4.3.0

Supported X.org versions:
- 6.7.0
- 6.8.0
- 6.8.1
- 6.8.2

Supported modes of operation:
- Bus mastering / Direct access
- Color (8, 16, 32 bpp)

OpenGL:
- OpenGL 1.3 compliant when bus mastering is available and enabled.

Xv:
- Xv is enabled when bus mastering is available and enabled.

See the section "Enabling bus mastering" for details.


Available configurations
========================

With this driver, you can choose amongst the following multi-display
configurations:

  (1) Single display: Only 1 display. This mode supports bus
      mastering. For HR256 and QID, when enabling the QID option 
      will enable dual outputs on the primary connector(s).

  (2) 2 displays - independent mode: 2 displays with different
      display resolutions. This mode supports bus mastering. For
      HR256 and QID, when enabling the QID option will enable
      quad outputs.

  (3) 2 displays - stretched mode: two displays with the same
      display resolution and refresh rate. These 2 displays use 1 big
      frame buffer. This mode supports bus mastering. For HR256 and QID, 
      when enabling the QID option will enable quad outputs.

  (4) 3 displays - stretched mode (TripleHead): 3 displays with the
      same display resolution and refresh rate. These 3 displays
      use 1 big frame buffer. This mode supports bus mastering.


Using TripleHead
================

(Note: TripleHead is not supported on the Millennium P650)

While using TripleHead, all 3 displays must have the same refresh rate and
resolution because all 3 displays are using the same frame buffer.

In order to enable Triple Head, add

    Option "TripleHead"

to the screen section of your XF86Config-4 file

Here's a sample Screen Section for Triple Head:

Section "Screen"
        Identifier   "Screen 1"
        Device       "MGA CARD 1"
        Monitor      "My Monitor"
        DefaultDepth 24
        DefaultFbbpp 32
        Option       "TripleHead"

        SubSection "Display"
            Depth    24
            Virtual  2400 600
            Modes    "800x600"
        EndSubSection
EndSection

To enable 2 analog + digital mode you will need to add the following
line to your device section:

    Option "DigitalScreen1" "on"


Sample XF86Config Files
=======================

There are sample XF86Config files in the "Samples" directory. To use them,
you must either:

- Copy the file to your /etc/X11 directory and rename it to
  "XF86Config-4" or "xorg.conf" depending if using XFree86 or X.org
  X servers

OR

- Type "startx -- -xf86config FILENAME" where FILENAME is the sample
  config file.

For
     Single display                               --> XF86Config.single
     2 displays - independent mode                --> XF86Config.dual
     2 displays - stretched mode                  --> XF86Config.merged
     3 displays - stretched mode                  --> XF86Config.triple
     Quad Display (QID, HR256) merged             --> XF86Config.T221-Merged
     Quad Display (QID, HR256) (dual independant) --> XF86Config.T221-Xinerama
     
    Note: these are samples and may require modification to
          be usable with your particular system configuration.


Changing the amount of offscreen memory
=======================================

If you need to change the offscreen allocation of memory the "OffScreen"
option can be used for this purpose by using an integer value between
"0" and "5" to be used as a multiplier against the memory used for onscreen
memory. For example we want the offscreen memory to use twice as much ram
as what the onscreen memory would use, we would add the following line
to your device section in your config :

    Option "OffScreen" "2"


Using digital monitors
======================

If you are using a digital monitor, add the following line to the device
section:

  Option "DigitalScreen1" "on"

  or

  Option "DigitalScreen2" "on"

"DigitalScreen1" and "DigitalScreen2" correspond respectively  to the
digital monitor connected to the primary and secondary connector of your
graphics card. Note that when using both outputs for the Millenium 650, 
750 and Parhelia cards in Merged mode that the device section of your X 
config will need to contain both options (ie. both DigitalScreen1 and
DigitalScreen2) as shown in the following example :

Section "Device"
    Identifier  "Device1"
    Driver      "mtx"
    BusID       "PCI:1:0:0"
    Option      "DigitalScreen1" "on"
    Option      "DigitalScreen2" "on"
EndSection


Binary Installation
===================

A working installation of XFree86 4.2.0, 4.2.1, 4.3.0 or X.org 6.7.0,
6.8.0, 6.8.1, 6.8.2 is required before the binaries can be installed.

To install the driver execute the following from a bash shell as the 
root user :

	sh mtxdrivers-glibc2.x.x-v1.1.2-beta.run

This will extract the files to the installation directory and start the 
installation installation script. 


Enabling bus mastering
======================

The driver can run with bus mastering On or Off. Having bus mastering On generally 
gives better performances. To run with bus mastering a kernel driver, mtx.o, 
must be compiled. On most configurations the installation script will seamlessly take
care of the kernel driver compilation.

In order to use bus mastering, the following modules must be loaded:

  (1) mtx.o: Parhelia kernel module

      The kernel module must be compiled for your system. The script
      file "install.sh" will attempt to compile the module. If it does not
      succeed, you can compile it manually by entering the following:

         - cd mtxdrivers[ENTER]
         - export PARHELIUX=$PWD/src[ENTER]
         - cd src/kernel/parhelia[ENTER]
         - ln -sf ../../../kernel/mtx_parhelia.o .[ENTER]
         - cd ..[ENTER]
         - make clean[ENTER]
         - make[ENTER]
         - su root[ENTER]
         - make install[ENTER]

      Compiling the kernel module requires the kernel source to be
      installed on your system.

The "make install" command installs the kernel module in the proper
location. The X server should load the kernel module automatically. If not,
typing "insmod mtx" in the installed location will load the module. 

Before loading the "mtx" kernel module, make sure that the "agpgart" module
has been loaded sucessfully. Enter the following command and look for
"agpgart" in the list of modules.

         - lsmod

If "agpgart" is not listed, it can be loaded by typing the following for 2.4
series kernels:

         - modprobe agpgart

If "agpgart" is not listed, and you are using a 2.6 series kernel it can be loaded 
by typing one of the following lines to load the appropriate gart for your motherboard
chipset:

         - modprobe via-agp
         - modprobe intel-agp
         - modprobe sis-agp
         - modprobe ali-agp
         - modprobe nvidia-agp
         - modprobe sworks-agp
         - modprobe amd-k7-agp
         - modprobe ati-agp

To enable or disable bus mastering, add the following to the XF86Config-4
file:

  Option "Busmastering" "on"

  or

  Option "Busmastering" "off" 

Note that busmastering will always be assumed to be on if the busmastering
option isn't set in your X config file.


Kernel module options
=====================

When using the mtx.o kernel module the following options can be set 
 - Agp Rate (1x,2x,4x)
 - Agp/Pci transfers
 
The agp rate rate can be set as follows (as the user root):

    modprobe mtx agprate=4
   
Note that legal values are 1, 2, and 4 corresponding to the desired
agp speed setting.

To set the card to use agp or pci transfers use the following format 
(as the user root):

    modprobe mtx agp=0
    
Note that legal values are 0 when using pci transfers and 1 when using
agp transfers.


These options can be set up to execute automaticly by adding them to
the modules.conf (on most distributions this would be locate in the /etc
directory).

For example to set the agp rate to 2 and set pci tranfsers you would add 
the following line (as the user root) to modules.conf :

    options mtx agprate=2 agp=0

These options are set automatically any time you do 'modprobe mtx' or 
'insmod mtx' when the options are listed in modules.conf.


Enabling TV out
===============

This option can be enabled when using single head mode to clone its output.
The output supported are NTSC and PAL. There are 3 settings that need to be 
set in the primary Screen section of your config, "TvOut", "TvStandard", 
"SelectedRegion", and "AntiFlickerLevel". The following is a sample for 
NTSC:

Section "Screen"
    Identifier   "Screen 1"
    Device       "MGA CARD 1"
    Monitor      "My Monitor"
    DefaultDepth 24 
    
    Option "TvOut" "on"
    Option "TvStandard" "NTSC"
    Option "AntiFlickerLevel" "10"
    Option "OutputRegion"   "48 37 672 447"
    Option "SelectedRegion" "0 0 800 600" 

    SubSection "Display"
        Depth    16 
        Modes    "800x600" "640x480"
    EndSubSection

    SubSection "Display"
        Depth    24
        Modes    "800x600"  "640x480"
    EndSubSection
EndSection

Option switches -

 Options            Values                    Description
 ----------------   -----------------------   ---------------------------------
 "TvOut"            "on" or "off"             Enables/Disables TV out.
 "TvStandard"       "PAL" or "NTSC"           Select output type.
 "OutputRegion"     "Left Top Right Bottom"   Selects usable tv area.
 "SelectedRegion"   "Left Top Right Bottom"   Selects desktop region to clone.
 "AntiFlickerLevel" "0" to "25"               Sets the antiflicker levels.

For example the resolution in NTSC (and the same applies for PAL with different
values used) is 720x484 but that does not take into account the bezel (casing) of 
most TV that hides some pixels.  Therefore, to be compatible with most TVs, we suggest 
an output region of 624x410 with the parameters specified below:

Option "OutputRegion"   "48 37 672 447"


Video Blitting
==============

Video blitting can be used instead of overlays by using the "XFB" switch
in the device section of your X config. The following device section example 
would illustrate its use:

Section "Device"
	Identifier "device1"
	Driver     "mtx"
    BusID      "PCI:1:0:0"
	Option     "XFB" "on"
EndSection


Enabling dual and Quad head support for HR256 and QID
=====================================================

To enable support for dual and quad head under xfree86 using either the 
HR256 or QID cards, will require adding the following option to the device
section of your XF86Config or XF86Config-4 file :

    Option "QID"

This option will enable the use of outputs 2,3, and 4 when using hybrid mode 
(heads 1 and 2 slaved), dual head hybrid mode (heads 1 and 2 slaved and heads
3 and 4 slaved), dual head hybrid mode Xinerama, and Merged mode. When not
used the QID and HR256 will function like a single head card.

For full examples see the XF86Config.T221-Merged and XF86Config.T221-Xinerama 
sample files.


Known driver problems
=====================

- The HR256 and QID boards cannot do more than a total resolution of 4096 when doing
  a 4x1 setup in merged mode due to hardware limitations (ie. a max of four outputs of
  1024x768 per output). This can be bypassed by using two 2x1 settings (hybrid 
  independant mode).

- On Fedora Core 3 and RHEL Beta 4 the kernel module will compile but will not load 
  due to a bug in the module check feature introduced with that release. Recompiling 
  the kernel without that feature will bypass the problem. See the following bug report 
  for more information:
    
    https://bugzilla.redhat.com/beta/show_bug.cgi?id=140954

- Note for SuSE 9.2 users will need to run the following two commands as root before using
  the matrox installer :

  make cloneconfig
  make modules_prepare

- To allow v4l applications to use hw scaler (like watching tv with xawtv in full screen),
  make sure you have the "load "v4l"" declaration in the "Module" section of your 
  configuration file. The install program changes the original v4l_drv module 
  for a custom version still compatible with the older one.
  
  You must also verify that your capture module is loaded before 
  starting X (for instance, modprobe bttv). 
  
  To remove some tearing, use smaller resolution or lower the refresh rate 
  to reduce the effect.
    

New Features
============

- Added installer support for SuSE 9.2. Note see the known driver problems section before
  running the installer.
- Added fix for multi board support.
- Added digital monitor autodetection.
- Fixed some Xv issues.
