5. XF86Config specifications

The driver recognises a number of XF86Config options.
In general, all such options should be specified in a ``Device'' section, and
affect only that ``Device'' section.

Those options that affect how the driver associates adapters with ``Device''
sections are described first.
The driver will ignore (with a message) a ``Device'' section if the section
cannot be associated with exactly one adapter in the system.
Similarly, the driver will ignore, or disable, (with a message) any adapter
that cannot be associated with exactly one ``Device'' section.
Thus, these options will be required in those uncommon cases where such unique
associations cannot automatically be made by the driver.

Other options affect the driver's operation once an adapter has been assigned
to the ``Device'' section which contains them.

5.1. Driver ``ati''

The use of this specification is highly recommended if the ``Device'' section
is to be recognised by the driver.
In fact, it is almost (but not quite) mandatory, particularly when using the
loader server as it indicates what driver is to be loaded and associated with
the ``Device'' section.

5.2. ChipSet ``name''

The default ChipSet name for this driver is ``ati''.
In this case, any ATI adapter can be associated with the ``Device'' section.
If an ATI accelerator is detected and the driver supports it, the accelerator's
CRTC will be used to drive the screen.
Otherwise, the driver will programme the adapter's SuperVGA CRTC.

If ``ativga'' is specified instead, the driver will ignore any ATI
accelerator it detects, but otherwise operate as if ``ati'' had been
specified.
This specification ensures the VGA CRTC is used.

A ChipSet name of ``ibmvga'' causes any VGA-capable adapter in the
system to be associated with the ``Device'' section.
It enables the driver's generic VGA support, but only for non-ATI adapters.
If an ATI adapter is associated with the ``Device'' section, the driver will
operate as if ``ativga'' had been specified instead.

A ChipSet name of ``vgawonder'' is equivalent to ``ativga'',
except that only VGAWonder-capable adapters can be assigned to the ``Device''
section.
This specifically excludes the newer integrated Mach64 controllers.

In some PCI or AGP systems, the driver will not, by default, probe for non-PCI
Mach32's or Mach64's.
This is because, before doing any such probe, the driver attempts to determine
if the probe can cause a lockup.
If the driver has enough information to determine that a lockup would occur, it
will skip the probe.
In some situations, this determination cannot be accurate, and the driver will
err on the side of caution, skipping the probe.
Specifying a ChipSet name of ``mach32'' or ``mach64'', as
appropriate, will force the driver to probe for the non-PCI adapter.
These ChipSet names should, therefore, only be used when there is in fact such
an adapter in the system.
They are otherwise equivalent to ``ati''.

5.3. ChipID & ChipRev specifications

These specifications will cause the driver to associate the ``Device'' section
only with an adapter having the same attributes, or an adapter whose PCI device
ID the driver does not recognise.
In the second case, these options cause the driver to treat the adapter as if
it was one with the specified PCI device ID or revision.
ChipID can only be used with Mach32 or Mach64 adapters, and, thus, specifically
excludes any other adapter from matching the ``Device'' section.
ChipRev is meaningful only with Mach64 adapters, and then only if ChipID is
also specified in the same ``Device'' section.

5.4. BusID

This option limits the adapters that can be associated with the ``Device''
section to the one with the specified PCI Bus ID.
This specification excludes non-PCI adapters.

5.5. Clocks

For the purpose of specifying a clock line in your XF86Config, one of four
different situations can occur, as follows.

Those configuring the driver's generic VGA support for a non-ATI adapter,
can skip ahead to the ``Clocks for non-ATI adapters'' section below.
Those not trying to configure the driver for a Mach64 adapter, can
skip ahead to the ``Clocks for fixed clock generators on ATI
adapters'' section below.

The very earliest Mach64 adapters use fixed (i.e. non-programmable) clock
generators.
Very few of these (mostly prototypes) are known to exist, but if you have one
of these, you can also skip ahead to the ``Clocks for fixed clock
generators on ATI adapters'' section below.

The two cases that are left deal with programmable clock generators, which are
used on the great majority of Mach64 adapters.

If you are uncertain which situation applies to your adapter, you can run a
clock probe with the command ``X -probeonly''.

5.5.1. Clocks for supported programmable clock generators

At bootup, video BIOS initialisation programmes an initial set of frequencies.
Two of these are reserved to allow the setting of modes that do not use a
frequency from this initial set.
One of these reserved slots is used by the BIOS mode set routine, the other by
the particular driver used (e.g. MS-Windows, AutoCAD, X, etc.).
The clock numbers reserved in this way are dependent on the particular clock
generator used by the adapter.

The driver currently supports all programmable clock generators known to exist
on Mach64 adapters.
In this case, the driver will completely ignore any XF86Config clock
specification, and programme the clock generator as needed by the modes used
during the X session.

5.5.2. Clocks for unsupported programmable clock generators

This case is unlikely to occur, but is documented for the sake of
completeness.

In this situation, the driver will probe the adapter for clock frequencies
unless XF86Config clocks are already specified.
In either case, the driver will then attempt to normalise the clocks to one of
the following specifications:

VGAWonder VLB, VGA 1024 VLB, Mach32 and Mach64 owners should only specify up to
the first 32 frequencies.
Any more will be ignored.

Other clock generators that have been used on ATI adapters (which can all be
said to be clones of one of the above) might generate non-zero frequencies for
those that are zero above, or vice-versa.

The order of the clocks is very important, although the driver will
reorder the specified clocks if it deems it appropriate to do so.
Mach32 and Mach64 owners should note that this order is different than what
they would use for previous XFree86 accelerated servers.

5.5.4. Clocks for non-ATI adapters

If no clocks are specified in the XF86Config, the driver will probe for four
clocks, the second of which will be assumed to be 28.322 MHz.
The first clock will typically be 25.175 MHz, but there are exceptions.
You can include up to four clock frequencies in your XF86Config to specify the
actual values used by the adapter.
Any more will be ignored.

5.6. Option ``nopanel_display''

This specification is only effective when the driver detects that the adapter's
BIOS has initialised both the digital flat panel and CRT interfaces.
In such a situation, the driver will normally drive both the panel and the CRT.
This specification causes the driver to disable the digital flat panel and
display the screen image on the CRT instead, which could potentially allow for
larger physical resolutions than the panel can handle.

5.7. Option ``crt_display''

This specification is only effective when the driver detects that the adapter's
BIOS has initialised the digital flat panel interface, but has disabled the
CRT interface.
In such a situation the driver will normally drive only the panel.
This specification causes the driver to instead display the same image on both
the panel and the CRT.

5.8. Option ``noaccel''

By default, the driver will accelerate draw operations if a Mach64 CRTC is used
to drive the display.
As implemented in this driver, acceleration does not require a linear video
memory aperture.
This option disables this acceleration.

5.9. Option ``nolinear''

By default, the driver will enable a linear video memory aperture for
256-colour and higher depth modes if it is also using a Mach64 accelerator CRTC
or an integrated Mach64 graphics chip.
This option disables this linear aperture.

5.10. Option ``HWCursor'' and Option ``SWCursor''

Option ``HWCursor'', which is the default, specifies that hardware
facilities are to be used to paint the mouse pointer on the screen.
Option ``SWCursor'' specifies that the mouse pointer is to be drawn by
software, which is much slower.
If both options are specified, option ``SWCursor'' prevails.
Currently, these options are only acted upon for 256-colour or higher depth
modes, if a Mach64 accelerator CRTC, or a Mach64 integrated controller is being
used.
In all other situations, a software cursor will be used, regardless of what
these options specify.

5.11. Option ``SilkenMouse''

This option is only acted upon when a hardware cursor is being used.
It specifies that the cursor's position on the screen is to be updated as
quickly as possible when the mouse is moved.
This is the default behaviour.
If this option is negated, the cursor may lag the mouse when the X server is
very busy.

5.12. Option ``shadowfb''

If this option is enabled, the driver will cause the CPU to do each drawing
operation first into a shadow frame buffer in system virtual memory and then
copy the result into video memory.
If this option is not active, the CPU will draw directly into video memory.
Enabling this option is beneficial for those systems where reading from video
memory is, on average, slower than the corresponding read/modify/write
operation in system virtual memory.
This is normally the case for PCI or AGP adapters, and, so, this option is
enabled by default.
For other bus types, the default behaviour is to disable this option.

Note that, due to various limitations, this option is forcibly disabled when a
linear video memory aperture is not enabled, when the frame buffer depth is
less than 8, or when acceleration is used.

5.13. Option ``dpms''

This option enables the driver's support for VESA's Display Power Management
Specification.

5.14. Option ``backingstore''

This is not specifically a driver option.
It is used to enable the server's support for backing store, a mechanism by
which pixel data for occluded window regions is remembered by the server
thereby alleviating the need to send expose events to X clients when the data
needs to be redisplayed.

5.15. MemBase address

This specification is only effective for non-PCI Mach64 adapters, and is used
to override the CPU address at which the adapter will map its video memory.
Normally, for non-PCI adapters, this address is set by a DOS install utility
provided with the adapter.
The MemBase option can also be used to enable the linear aperture in those
cases where ATI's utility was not, or can not be, used.

For PCI and AGP adapters, this address is determined at system bootup according
to the PCI Plug'n'Play specification which arbitrates the resource requirements
of most devices in the system.
This means the driver can not easily change the linear aperture address.

5.16. Option ``ReferenceClock'' ``frequency''

This option is only applicable to non-Intel platforms, where an adapter BIOS is
not available to the driver.
The option specifies the reference frequency used by the adapter's clock
generator.
The default is 14.318 MHz, and other typical values are 28.636, or 29.5 MHz.

5.17. ClockChip ``name''

This option is only applicable to non-Intel platforms, where an adapter BIOS is
not available to the driver, and the driver cannot reliably determine whether
the clock generator the adapter uses is a variant of an ATI 18818 (a.k.a.
ICS 2595) or an unsupported clock generator.
The only values that are acted upon are ``ATI 18818-0'' or
``ATI 18818-1''.
From this specification, the driver derives a reference divider of 43 or 46
(respectively) for use in clock programming calculations.
The driver's default behaviour, in this case, is to assume an unsupported clock
generator, which means it will treat it as a fixed-frequency clock generator,
as described under the heading ``Clocks for unsupported programmable clock
generators'' above.