Display Driver for Xfree86 v3.3.6 Release Notes
Version 1.1.9
Linux 2.4
January 18, 2001

-----------------------------------------------------------------------------
PRODUCT INFORMATION
-----------------------------------------------------------------------------
This is the National Semiconductor Xfree86 v3.3.6 Display Driver Version
1.1.9 BETA. This version of the driver works with the new linux graphics 
driver architecture followed by National. This driver has been tested with
Linux Kernel 2.4.0-test1. 
 
This product includes: 
 
- Display Driver 
 
Product files 
------------- 
   \readme.txt         This file 
   \XF86_SVGA	       Xfree86 v3.3.6 XServer Display Driver

-----------------------------------------------------------------------------
INSTALLATION INSTRUCTIONS
-----------------------------------------------------------------------------
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
-----------------------------------------------------------------------------
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.

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.  

GAL Library
-----------
For the XServer to compile you require libgal.a. To build a GAL library Pl.
follow the GAL install and build instructions.

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

Copy the supplied setup files in their respective tree locations.

Make sure you run "crlf" on all files added to remove carriage returns.

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.


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.

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/

-----------------------------------------------------------------------------
REVISION HISTORY
-----------------------------------------------------------------------------
11/13/00 1.1.9

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
* Companion Framebuffer driver v1.08, GAL lib v1.0.4
* Removed Debug messages.
* Added GeodeGetRefreshRate function to map dotclock to refreshrate. This 
  will eliminate the unnecessary refreshrates not supported by h/w.
* Added compression support, this dosen't seen to work with framebuffer. so 
  disabled.

-----------------------------------------------------------------------------
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.

* The following modes will not work using the default modelines from the
  XF86Config file included with the 1.1.9 driver:
  8bit:
  1024x768 -- 85Hz, 75Hz, 70Hz, 43Hz(Note 43Hz is not documented as supported
  and is not in XF86Config by default)
  800x600 -- 85Hz, 75Hz(The 75Hz setting is not an existing modeline in
  XF86Config. See Issue 81.9), 56Hz(As with 43Hz, 56Hz is not documented as
  supported)
  640x480 -- 72Hz
  16bit:
  1280x1024 -- 85Hz, 75Hz, 60Hz(None of the modes work. See issue 81.12)
  1024x768 -- 85Hz, 75Hz, 70Hz, 43Hz(Note 43Hz is not documented as supported
  and is not in XF86Config by default)
  800x600 -- 85Hz, 75Hz(The 75Hz setting is not an existing modeline in
  XF86Config. See Issue 81.9), 56Hz(As with 43Hz, 56Hz is not documented as
  supported)
  640x480 -- 72Hz

* All of the above modes except for 1024x768 at 70Hz can be achieved by
  adjusting the modelines.  The following modelines have worked:
  #Modeline "640x480at72"   31.5   640 664 704 832   480 489 492
  520  -hsync -vsync
  #Modeline "800x600at75"   49.5   800 816 896 1056   600 601 603
  624  -hsync -vsync
  #Modeline "800x600at85"   56.25   800 832 896 1048   600 601 604
  631 -hsync -vsync
  #Modeline "1024x768at75"   78.75   1024 1040 1136 1312   768 769 772
  800 -hsync -vsync
  #Modeline "1024x768at85"   94.5   1024 1072 1168 1376   768 769 772
  808 -hsync -vsync

* The framebuffer does not support 1280x1024x16.  This resolution is also not
  supported by Durango in XWindows with the framebuffer driver installed.

* List of Current Issues
	- No Spec for Framebuffer
	- Durango/release.txt not updated
	- Cannot return to Virtual Terminals after starting X on a SC2200
	- XF86Config has incorrect monitor name
	- Maximum allowed dot-clock reported incorrect on Dorado
	- XF86Config missing Modeline for 800x600at75Hz
	- XFree86 driver does not support Flat Panels 81.11 FrameBuffer
	  readme.txt missing vga= lilo.conf setting
	- 1280x1024-16 FrameBuffer Mode hangs system .
	- Virtual Terminal is corrupt after X session with only 1 Modeline
	- Missing Resolutions in XWindows

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

10/24/00 1.1.8

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
Companion Framebuffer driver v1.06, GAL lib v1.0.2
* Added support for new GAL 1.0.2

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

10/20/00 1.1.7

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
Companion Framebuffer driver v1.05, GAL lib v1.0.1
* Added support for GAL layer
* Driver works on Gxm and SC1200.
* Files modified geode_init.c, geode_accl.c, geode_curs.c

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

9/27/00 1.1.6

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
Companion Durango v2.11
* Added our own XF86Config file for the mode support.
* Checking the pixel frequency if supported by durango.
* Enabled support for SC1200.

-----------------------------------------------------------------------------
DEFECTS CORRECTED
-----------------------------------------------------------------------------
* Edited the Xf86.cf file to have geode entry.

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

8/7/00 1.1.5

-----------------------------------------------------------------------------
FUNCTIONAL CHANGES
-----------------------------------------------------------------------------
Companion Durango v2.06
* Added DEBUGMSG macro to control the debug messages. If condition is 1 then 
  the debug message is printed else ignored.

-----------------------------------------------------------------------------
DEFECTS CORRECTED
-----------------------------------------------------------------------------
* The durango code is always latching to 85Hz for any refresh rate. The bug 
  fix was done in gfx_get_refreshrate_from_frequency.

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

7/21/00 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

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

6/14/00 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.

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

3/3/00 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.

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

2/21/00 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).