/*****************************************************************************
$Workfile: readme.txt $
$Revision: 11 $
$Date: 11/13/00 12:55p $

Copyright (C) 2000 National Semiconductor Corporation. All Rights Reserved.

Permission is granted, royalty-free, to any person obtaining a copy of this 
software and associated documentation files (the "Software"), to deal in the 
Software without restriction, including without limitation the rights to use, 
copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 
the Software, and to permit persons to whom the Software is furnished to do so, 
subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software in whatever form or media.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
IN NO EVENT SHALL NATIONAL SEMICONDUCTOR BE LIABLE FOR ANY CLAIM, 
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this permission notice, the name of National Semiconductor 
shall not be used in advertising or otherwise to promote the sale, use or other 
dealings in this Software without prior written authorization from National Semiconductor.

*****************************************************************************/

National Semiconductor Corp. Display Driver for Xfree86 v3.3.6.
 
Table of Contents 
----------------- 
- Release description 
- Product files 
- Installing XFree86 Source
- XFree86 4.0.x
- Understanding the Xserver
- Building the Xserver
- Configuring the Xserver
- Recovering from Failure to Start X
- Interactively Debugging the XFree86
- Notes, Problems, and Limitations 
- Version changes 


Release description 
------------------- 
This is the National Semiconductor Xfree86 v3.3.6 Display Driver Version 1.1.9.
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


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.


XFree86 4.0.x
------------- 
There are many significant changes to XFree86 reflected in the 4.0.1 release.
To use XFree86 4.0, download the source (or binaries) from:

http://www.xfree86.org/

The *.tar.bz files ("tar balls") will be extracted and installed in a similar
fasion as the XFree86 3.3.6 files.

There is only one Xserver in 4.0: XFree86.  It will load the modules/drivers
that it needs at run-time.  These drivers are located at:

/usr/X11R6/lib/modules/drivers

The XF86Config file format has changed, too.  The Xconfigurator program may 
not be available to create this file, so you may have to use xf86config, instead.  

For a more comprehensive description of changes, visit the XFree86 web site 
and go to the documentation section.


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.



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.

	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/


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

Version changes
---------------
-----------------------------------------------------------------------------
1.1.9 (11/13/2000) 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.
 geode_init.c
-----------------------------------------------------------------------------
1.1.8 (October 24, 2000) Companion Framebuffer driver v1.06, GAL lib v1.0.2

- Added support for new GAL 1.0.2
-----------------------------------------------------------------------------
1.1.7 (October 20, 2000) 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
-----------------------------------------------------------------------------
1.1.6 (September 27, 2000) Companion Durango v2.11

- 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
-----------------------------------------------------------------------------
1.1.5 (August 07, 2000) Companion Durango v2.06

- 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
-----------------------------------------------------------------------------
1.1.4 (July 21, 2000)
- Added support for Pyramid(12801024x16)
- Support for 85Hz RefreshRate.
- Added durango code to switch to correct modes.
- Added code for unsupported mode in GeodeValidMode
-----------------------------------------------------------------------------
1.1.2 (June 14, 2000)
- Incorporated version 2.1CE of Durango
- Fixed some initialization problems in both Durango and XFree86 code.
- Added support for 1280x1024x16bpp mode for Pyramid.
-----------------------------------------------------------------------------
1.01 (March 3, 2000)
- Incorporates version 2.1 of Durango.
- Fixed problem with using Ctrl-Alt-Plus to change resolutions.
- Fixed problem restoring to text mode under Linux.
-----------------------------------------------------------------------------
1.00 (February 21, 2000)
- 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).
-----------------------------------------------------------------------------




