Display Driver for Xfree86 v3.3.6 Release Notes
Version 1.1.16
Linux
December 11, 2000

-----------------------------------------------------------------------------
PRODUCT INFORMATION
-----------------------------------------------------------------------------

This is the National Semiconductor Xfree86 v3.3.6 Display Driver Version 1.1.6 
 
This product includes: 
 
- Display Driver

Product files 
   \release.txt        This file 
   \XF86_SVGA	       Xfree86 v3.3.6 XServer Display Driver

-----------------------------------------------------------------------------
INSTALLATION INSTRUCTIONS
-----------------------------------------------------------------------------
 
Installing XFree86 Source
------------------------- 
This source tree mirrors the files which need to be added to or replaced
in the /usr/X11R6 tree.  The source files will be under /usr/X11R6/xc.
The installation of Linux will not include the source code for the XFree86
X-Window system, even if the option to install 'everything' is selected.

To get the source code for XFree86, copy the file XFree86-3.3.6-20.src.rpm
from the Linux Disk 2 under /mnt/cdrom/SRPMS.  Use the package manager
to extract the 3 compressed source files, then install each of them under
/usr/X11R6.  The package manager (for RedHat Linux) may be used to get
the XFree86 source package by doing these steps from the command-line:

	[put RedHat Linux Disk 2 in the CDROM drive]
	mount /dev/cdrom /mnt/cdrom
	rpm -U --force /mnt/cdrom/SRPMS/XFree86-3.3.6-20.src.rpm
	umount /mnt/cdrom

This package will put the 3 compressed files into /usr/src/redhat/SOURCES.

The 3 compressed files are: X336src-1.tar.bz, X336src-2.tar.bz, and 
X336src-3.tar.bz.  The first of the files contains the source code.  The
other 2 contain mostly documentation.  To reduce the size of the installation,
install only the first compressed file (X336src-1.tar.bz).  The compressed
XFree86 files in the tar+bzip format (*.tar.bz) may be uncompressed and placed 
in the correct location by moving it to the /usr/X11R6 directory and executing
the tar command like this:

	tar xfvI X336src.tar.bz

The will un-tar the archive, pass it through the bzip filter, build the
directory tree, and be verbose about what is happening.  After this, an 
'xc' subdirectory will exist with all of the source code for XFree86.  

After the 'xc' tree is created, copy the files under revision control into 
their respective places in the 'xc' tree.

This procedure works for RedHat Linux 6.2, and will probably work for other
distributions of Linux as well.

Understanding the Xserver
------------------------- 
The Xserver manages client connections and responds on behalf of clients
to user interface events (mouse, keyboard input) and protocol requests
(graphics).  It is divided into 4 major pieces: 

  - device independent layer (DIX): code shared among all implementations
  - OS layer: code which is different between operating systems but shared
    among all devices of an operating system
  - device dependent layer (DDX): code which is potentially different between
    operating systems and graphics devices
  - extension interface: the standard way to add features to the X server

For more information on this, see the xc/doc directory.

-----------------------------------------------------------------------------
BUILD INSTRUCTIONS
-----------------------------------------------------------------------------

Building the Xserver
-------------------- 
Before doing a build, copy the /usr/X11R6/bin directory to /usr/X11R6/bin.bak.
A complete build of XFree86 can take 2-8 hours, depending on processor speed,
available memory, build options, etc.  To reduce the build time, remove from
the build configuration the Xservers and components that are not needed (e.g.,
XF86_MONO, XF86_VGA16, etc.).

To prevent the unnecessary building of components not needed or not modified,
edit the /usr/X11R6/xc/config/cf/xf86site.def file.  The comments in this file
will help you determine the consequences of changing what is commented and
un-commented.  For example, to only build the XF86_SVGA server, un-comment
all of the lines in the section where each of the 'Intel x86' servers is 
'#define-d' to 'NO' -- except for 'XF86SVGAServer'.  Further in that same
file you may un-comment which server to specifically install, which of the
SVGA drivers to build, whether or not to build the fonts, etc.

To initiate a full build, open a shell window and switch to the '/usr/X11R6/xc'
directory.  Enter 'make World >& world.out'.  This will start the build process.
If all of the configuration parameters are correct, this step will only needed
once.  Only the XF86_SVGA image will need to be replaced after modifications to 
the driver.  This image uses library archive libdriver256.a, which is built
from the driver objects.


LinkKit
-------- 
The XFree86 build tree also includes a 'LinkKit'.  The Link Kit has everything 
that is needed to re-link the server.  You can write a new driver and build a 
new server without having the server source installed.  


Integrating New Driver Source
-----------------------------
Use the 'crlf' utility to remove MSDOS-style CRLFs in the code.  The file 
'crlf.c' is provided.  Execute 'cc crlf.c' to build this utilty.  If the 
source code includes MSDOS-style CRLFs, then the correct Makefile will not 
be built with 'make Makefiles' and the source will fail to build.

The Makefile is generated from the 'Imakefile' during the process of 'make 
Makefiles'.

The National-specific driver code will be located at:

For XFree86 3.3.x:
/usr/X11R6/xc/programs/Xserver/hw/xfree86/vga256/drivers/geode

For XFree86 4.x.x:
/usr/X11R6/xc/programs/Xserver/hw/xfree86/drivers/geode


Building the Geode driver
------------------------- 
This driver was built and tested in the FreeBSD environment, version 3.1.
It was also built and tested under Linux.
V1.1.2 was only tested under Linux.

Directions for compiling this driver:
- Source files placed in "/usr/X11R6/lib/Server/drivers/vga256/cyrix", but
  first delete any old files which reside in this directory.
- From "/usr/X11R6/lib/Server" typed "./mkmf" to update dependencies.
- Edited "Makefile" in "vga256" directory to remove "nv" from list of 
  drivers (first entry), which in this release did not build properly.
- Back in "Server" directory, typed "make".
- Once built, start server with "xinit -- ./XF86_SVGA".
- Or, "xinit -- ./XF86_SVGA -bpp 16" for 16 BPP.
- Bring up window manager such as "twm &".

To test performance:
- Use Ctrl-Plus to go to 1024x768 mode (Ctrl-Alt-Plus under linux).
- Type "x11perf -v1.3 -rop GXcopy GXxor -all > datafile".
- Then "Xmark datafile".
- A 266 MHz GX gets about 6.8 in 8 BPP.

If editing files on a Windows based PC:
- Use "mcopy" to transfer files from a floppy.
- Use "undos" (provided) to remove extra carriage returns.
  (type "./undos sourcefile").
- use "todos" (if available) to return files to dos compatibility for
  configuration control under vss (type "todos <sourcefile >dos_sourcefile")

Configuring the Xserver
-----------------------
Before configuring the Xserver, copy /etc/X11/XF86Config to XF86Config.bak.
A Geode mode specific XF86Config is supplied to install this copy the supplied 
XF86Config to /etc/X11/XF86Config.
Run 'Xconfigurator'.  This will create a new XF86Config file.  Select 'Geode'
or 'MediaGX' from the available display adapters.  The list of display adapters
is read from /usr/X11R6/lib/X11/Cards.  Select your monitor or 'custom'.  When
asked to 'Probe' or 'Dont Probe', select 'Dont Probe' for legacy Cyrix display
hardware and 'Probe' for newer hardware.  If you do not want the Xserver
to start right away after booting, do not select the default button to start
X after booting.


Recovering from Failure to Start X
----------------------------------
To boot without starting the Xserver, enter 'linux 4' at the LILO boot prompt.
This will initialize the system to run-level 4.  'linux' is the name of the
kernel image.  It may be a different name if a new kernel was built and set
as the boot image.  After logging-on as root, run Xconfigurator and answer
'no' to the question of whether to run the Xserver automatically at startup.

Start the Xserver from the command-line with: 'startx >& startx.out'.  This 
will provide Xserver error messages.  Better, you can open the file
/var/log/XFree86.0.log after invoking the Xserver.


Interactively Debugging the XFree86
----------------------------------- 
Debugging XFree86 can be difficult.  You can use gdb to interactively debug
the server from another system.  You can use a special module-aware gdb to
debug modules.

In the Xfree86 4.x distributions, see the file: 
/usr/X11R6/xc/programs/Xserver/xfree86/DebuggingHints for useful tips.


Framebuffer Devices
------------------- 


Useful Information and Documentation
------------------------------------ 
"How to add an (S)VGA driver to XFree86" by David E. Wexelblat.  This is a small
	text file which is part of the XFree86 documentation.
"{The Concise Guide to} XFree86 For Linux" by Aron Hsiao.  This is a book which
	covers the configuration and use of XFree86 for Linux.  
	ISBN 0-7897-2182-1

http://www.xfree86.org
http://www.x.org
/usr/X11R6/


Notes, Problems, and Limitations
-------------------------------- 
  - xfs: Font server fails to start.  Even a straight build of xfs from the distribution
source will fail to load.


-----------------------------------------------------------------------------
REVISION HISTORY
-----------------------------------------------------------------------------

September 27, 2000 - 1.1.6 Companion Durango v2.11

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
- Fixed the Bug 81.3
  Edited the Xf86.cf file to have geode entry.
- Added our own XF86Config file for the mode support.
- Checking the pixel frequency if supported by durango.
  geode_init.c
- Enabled support for SC1200.
  durango.c

-----------------------------------------------------------------------------
VALIDATION NOTES
-----------------------------------------------------------------------------
* THE DRIVER DOES NOT SUPPORT FLAT PANELS. On Dorado, the driver does not use
the video mode setup by XpressROM for the flat panels. #81.6 and 81.10 
* The included XF86Config names the monitor as "Generic Monitor" in the 
Monitor section. All of the screen sections use "ViewSonic P815". To make the
config file usable, change "Generic Monitor" to "ViewSonic P815" in the 
monitor section.
* List of Current Issues
	#81.6 Cannot return to Virtual Terminals after starting X on a SC2200
		see above
	#81.7 XF86Config has incorrect monitor name
		see above
	#81.8 Maximum allowed dot-clock reported incorrect on Dorado
		The driver reports a maximum dot-clock of 157.5 MHz on Dorado. The
		SCx200 processors only support 135 MHz.
	#81.9 XF86Config missing Modeline for 800x600at75Hz
		Not all modes supported are defined the the XF86Config.
	#81.10 XFree86 driver does not support Flat Panels
		see above

=============================================================================

August 07, 2000 - 1.1.6 Companion Durango v2.06

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
- Fixed the Bug 81.2
  The durango code is always latching to 85Hz for any refresh rate. The bug fix
  was done in gfx_get_refreshrate_from_frequency.
- Added DEBUGMSG macro to control the debug messages. If condition is 1 then 
  the debug message is printed else ignored.
  geode_init.c

=============================================================================

July 21, 2000 - 1.1.4

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
- Added support for Pyramid(12801024x16)
- Support for 85Hz RefreshRate.
- Added durango code to switch to correct modes.
- Added code for unsupported mode in GeodeValidMode

=============================================================================

June 14, 2000 - 1.1.2

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
- Incorporated version 2.1CE of Durango
- Fixed some initialization problems in both Durango and XFree86 code.
- Added support for 1280x1024x16bpp mode for Pyramid.

=============================================================================

March 3, 2000 -  1.01

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
- Incorporates version 2.1 of Durango.
- Fixed problem with using Ctrl-Alt-Plus to change resolutions.
- Fixed problem restoring to text mode under Linux.

=============================================================================

February 21, 2000 - 1.00

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
- Incorporates version 2.0 of Durango.
- Uses Durango routines for all hardware access (CPU detection, mode sets
  using VGA registers, graphics acceleration, and hardware cursor).
