AMD Geode(TM) LX/GX Processor Xorg Display Driver - Release Notes
Version: 03.00.0101, Release Notes
Release Date: December 19, 2005

-----------------------------------------------------------------------------
PRODUCT INFORMATION
-----------------------------------------------------------------------------
- This driver is the Xorg Display Driver for the AMD Geode(TM) LX and 
  GX processors.

This product is avaiable as a standalone patch comprising:
	Graphics_LinuxXorg_Common_03.00.0101.patch
	README.txt (this file)

or as a tarball Graphics_LinuxXorg_Common_03.00.0101.tar.gz containing:
	Graphics_LinuxXorg_Common_03.00.0101.patch
	xorg.conf_lx
	xorg.conf_gx
	README.txt (this file)

The patch adds the following documenation to the Xorg tree:
xc/programs/Xserver/hw/xfree86/drivers/amd/amd.man
xc/programs/Xserver/hw/xfree86/drivers/amd/gfx/release.txt (GX only)
xc/programs/Xserver/hw/xfree86/drivers/amd/panel/readme.txt (GX only)

The following example files are provided in the tarball release only
	xorg.conf_lx
	xorg.conf_gx

For bugs, patches, and info requests, please subscribe to:
info-linux@geode.amd.com

To subscribe, send a blank message to:  info-linux-subscribe@geode.amd.com

Features
--------
The AMD Geode Linux Xorg driver implements Xorg XAA driver interface.
Through a hardware abstraction layer called "Durango" (GX) and "Cimarron" (LX),
the full accelerated functionality of the graphics processor is exposed to
the driver.

The AMD Geode Xorg driver implements:

 - Xv video overlay extension support 
 - Geode hardware color-space conversion 
 - V4L2 overlay functionality (Geode LX processor only)
 - Rotated graphical output
 - DDC support
 - DPMS support
 - Common X.org patch support both Geode LX and GX processors


Dependencies
------------
- Built with xorg-x11-6.7.0 from Fedora Core 2 Source Updates
- Built with X11R6.8.1 from freedesktop.org
                                                                                
- This driver has been tested with Linux Kernel 2.6.11
    using the Fedora Core 2 image environment
    using the Gentoo 2005.0 image environment

- To use the Xv adaptor interface
   1) create a "videox" link to the geodev4l2 video device in /dev
      ln -s video0 /dev/videox
   2) uncomment the '  Load "z4l"' line in xorg.conf


Functional Changes
------------------
Issue #4027

Defects Corrected
-----------------
PBZ#6538 - X.org patch is incompletely licensed
PBZ#4027 - HWCursor/Rotation, cursor does not traverse entire resolution area
Description:
When using HWCursor, cursor can not traverse the entire visable area of *MOST* 
(there are exceptions) rotated modes.  The failures exist as edges which the 
cursor can not travel to.  Failing edges differ according to rotation.
Resolution:
Cursor "hotspot" error corrected.

PBZ#4463 - 8 bpp, x11perf SWCRC --> HWCRC comparison fails paint8_03 ...
PBZ#4665 - LX Xorg Driver will not patch successfully if GX Xorg Pat...
PBZ#5025 - mode changes with xrandr, graphics distorted

Known Errata
------------
PBZ#4025 X - Rotations{90,270}, only lowest refresh rate pass mode validation
Description: 
At 90 and 270 degree rotations, only the lowest supported refresh
rate can be entered.  The rest of the refresh rates appear to fail mode 
validation (xrandr does not see them as options, and I can not CTL->ALT->+/- 
through the modes).  This issue does not occur at 0 or 180 degree rotations.  
Resolution: 
This is an inherent weakness of the X mode switch -- where even a 
full X R&R implementation would not fix this.
Steps to address will need to be:
(1) convert AMD rotation support to X R&R
(2) patch X to better handle X R&R
This may be addressed in a future version.

PBZ#5993 - HWScaling mode hsync out of range error

--------------------------------------------------------------------------------
VALIDATION ENVIRONMENT
--------------------------------------------------------------------------------
Validated on AMD Geode(TM) "Norwich" Development Board - Rev 2 Rework H and
Rev 3 Rework E with:
	
Processor:		AMD Geode LX processor, silicon rev. C1 @ 433 MHz
Chipset:		AMD Geode CS5536 companion device, silicon rev. B1
PCI Bus Speed:		66 MHz
Memory:			256 MB PC3200 RAM
CRT:			NEC MultiSync FP2141SB
Flat Panel:		Samsung LTM213U3-L07 1600x1200 2-channel LVDS,
Keyboard/Mouse:		PS/2 on Moray 1.1
	
BIOS:			GeodeROM 1.06.06
Operating System:	Gentoo 2005.0
Kernel:			v2.6.11
Kernel Patch:		LX Kernel Patch v02.02.0100
Graphics Driver:	LX Xorg Graphics driver v03.00.0100
Audio Driver:		5536 ALSA Audio driver v01.00.0500
AES Driver: 		LX AES driver v02.01.0100
AccessBus Driver: 	LX ACB Driver v01.00.0401
Video4Linux2 Driver: 	LX Video4Linux2 driver v03.02.0100
Other Software:		N/A

-------------------------------------------------------------------------------
INSTALLATION INSTRUCTIONS
-------------------------------------------------------------------------------
Acquire Xorg Tarball from the Xorg web site:
http://www.x.org/X11R6.8.1/

For more information on X.org:
http://xorg.freedesktop.org/wiki/

Acquire Graphics_LinuxXorg_Common_03.00.0100.patch

Unpack Xorg Tarball
Patch the Source
Make Xorg
Construct Install
Apply Install image

for example:
  # tar -xzf X11R6.8.1-src.tar.gz
  # cd xc
  # patch -p1 < Graphics_LinuxXorg_Common_03.00.0100.patch 
  # cp config/cf/xorgsite.def config/cf/host.def

Edit config/cf/host.def
uncomment the line:

#define BuildSpecsDocs		No

Add the line (directly following the above line)

#define InstallHardcopyDocs	No

  # make World
  # mkdir <install_path>
  # make DESTDIR=<install_path> install install.man
  # tar -C <install_path> -czf <path>/xorg-x11-geode.tgz .
      move xorg-x11-geode.tgz to the target system
      login as root on the target system and make path to tarball available
  # tar -C / -xzpf <path>/xorg-x11-geode.tgz
  # mv /etc/X11/xorg.conf /etc/X11/xorg.conf.orig
  # cp <path>/xorg-<gx/lx>.conf /etc/X11/xorg.conf


++++++++++++++++++++++++++++++++++++++++++++++++++
AMD Geode(TM) LX processor Xorg.conf Specification
++++++++++++++++++++++++++++++++++++++++++++++++++

Linux Xorg AMD GeodeLX Processor Configuration Specification


The AMD Geode driver supports an accelerated interface to the
hardware access layer for the graphical devices (cimarron library).
To operate this API, a set of operational customizations
were added to the xorg.conf configuration file.  These customizations,
for the most part, are passed unmodified to "cimarron".  This document
only provides an overview of the customizations to the standard
configuration file definitions.

The xorg configuration (xorg.conf) file usually exists in the system
configuration directory /etc/X11.  The standard contents are documented
in the manual pages, and can typically be accessed using:
man XF86Config
The file is divided into "sections".  The following information
illustrates the custom features added section by section.


1. Device section:

The devices section specifies the graphics driver selection.  The drivers 
that may be specified include:
Section "Device"
        Identifier  "DevId"
        Driver      "vesa"   - or
        Driver      "fbdev"  - or
        Driver      "amd"
...
EndSection

The "vesa" and "fbdev" selections are documented by the manual pages
man fbdev   - or
man vesa
The "amd" driver has many selections that can be used to operate
the interface configuration.  These selections follow:


2. Hardware Accelerations:

This set of options are standard to the xorg "xaa" accelerations.
The presence of the option disables the named functionality.
Note that many accelerations depend on combinations with others,
and so disabling one may have a more pervasive effect.

        Option "XaaNoCPUToScreenColorExpandFill"
        Option "XaaNoColor8x8PatternFillRect"
        Option "XaaNoColor8x8PatternFillTrap"
        Option "XaaNoDashedBresenhamLine"
        Option "XaaNoDashedTwoPointLine"
        Option "XaaNoImageWriteRect"
        Option "XaaNoMono8x8PatternFillRect"
        Option "XaaNoMono8x8PatternFillTrap"
        Option "XaaNoOffscreenPixmaps"
        Option "XaaNoPixmapCache"
        Option "XaaNoScanlineCPUToScreenColorExpandFill"
        Option "XaaNoScanlineImageWriteRect"
        Option "XaaNoScreenToScreenColorExpandFill"
        Option "XaaNoScreenToScreenCopy"
        Option "XaaNoSolidBresenhamLine"
        Option "XaaNoSolidFillRect"
        Option "XaaNoSolidFillTrap"
        Option "XaaNoSolidHorVertLine"
        Option "XaaNoSolidTwoPointLine"

Certain hardware accelerations may be armed or disarmed by using:

        Option "HWcursor"    (default)  -or
        Option "SWcursor" 

        Option "Compression" (default)  -or
        Option "No Compression"


Additionally, all accelerations may be armed or disarmed using:

        Option "Accel"       (default) -or
        Option "No Accel"

This option enables/disables all rendering accelerations, HW/SW cursor,
and display compression.  Certain accelerations may not be armed, even
though they are inferred by the configuration, if video memory is in
short supply.


3. Modes section:

The configuration file included with the driver delivery contains an
optional "modes" section.  This section asserts all of the standard
graphics/video mode configuration data.  This set of modes is a subset
of the mode data in the "cimarron" library.  Because these modes are
included, they are passed to the "cimarron" driver for validation.  Be
aware that "cimarron" will select modes using a filtering function that
uses a constrained distance search.  The mode in "cimarron's" definitions
that is "closest" to a mode defined - either builtin or user supplied -
will normally be used by "cimarron".  

This filtering effect can be factored out by specifying:

       Option "CustomMode"

This has the effect of causing the mode validation to pass any mode
in the mode pool, and allowing the selection of the specified mode
during mode switch.  Unfortunately, because the interface specification
is not complete enough to support video modes, only video modes that
exist in "cimarron" are possible when selecting a TVOUT mode.


4. More "Device" section Options:

Since flat panels have fixed timing - that is, only one "real" mode -
the mode switch operation that normally might select a wide variety
of operational states must "adjust" the mode selection to fit the
fixed panel timing.  To communicate that the mode selection is for
a flat panel, use:
       Option "FlatPanel"
Note that the code expects that the flat panel will have been already
selected by the BIOS setup.  Conflicts produce configuration errors.
The size adjustment usually involves scaling the source buffer
dimensions to the raster image size supported by the flat-panel.  The
hardware supports this scaling operation transparently, and normally
no special considerations are needed.  The hardware scaling is limited
to modes with horizontal aspects of less than 1024 pixels (buffer size
limitation for scaling/filtering).

The display may be "rotated" in three ways, ClockWise, Upside-Down and
CounterClocwise using:
       Option "Rotate" "CW"
       Option "Rotate" "Invert"
       Option "Rotate" "CCW"  
This is accomplished using a "shadow" frame buffer, and using either
a hardware or software operation to transform the image to the
operational display buffer.

Even though there is not strategic advantage, if you wish to use a
shadow frame buffer and display the unrotated image - this is specified
by using:

       Option "ShadowFB" 


5. TVOUT video modes.

In order to enable TVOUT mode selection, a TV known encoder
must be selected in the following way:
       Option "TV_Encoder" "ADV7171"   -or
       Option "TV_Encoder" "SAA7127"   -or
       Option "TV_Encoder" "FS454"     -or
       Option "TV_Encoder" "ADV7300"
There is no default for the encoder.  This selection is mandatory
to enable TVOUT modes.

Most encoders support a variety of bus formats.  Similarly, the
AMD driver can select the bus data format from the following list:
       Option "TV_Bus_Fmt" "disabled"       - VOP output is disabled
       Option "TV_Bus_Fmt" "vip1_1"         - VIP 1.1
       Option "TV_Bus_Fmt" "ccir656"        - CCIR 656 output
       Option "TV_Bus_Fmt" "vip20_8bit"     - 8-bit VIP 2.0 output
       Option "TV_Bus_Fmt" "vip20_16bit"    - 16-bit VIP 2.0 output
       Option "TV_Bus_Fmt" "601_yuv_8bit"   - 601 output, 8-bit YUV 4:2:2
       Option "TV_Bus_Fmt" "601_yuv_16bit"  - 601 output, 16-bit YUV 4:2:2
       Option "TV_Bus_Fmt" "601_rgb_8_8_8"  - 601 output, 24-bit RGB
       Option "TV_Bus_Fmt" "601_yuv_4_4_4"  - 601 output, YUV 4:4:4
Note that the "601" modes may need sync signals for correct operation.
See the 601 flags below to operate these selections.

Colorspace conversion requires a projective transformation to
perform downsampling for the implied transformation.  The sampling
method may be specified by selecting from:
       Option "TV_Conversion" "cosited"
       Option "TV_Conversion" "interspersed"
       Option "TV_Conversion" "alternating"

The TV standard selected normally specifies a known frame buffer/
TV mode geometry.  However, it is quite common that TV output
devices may expect a blanked  "overscan" area.  The dx,dy marginal
widths for the overscan area can be specified using:
        Option          "TV_Overscan" "40:30"
Note that the TV standard geometry will be scaled (and filtered) to
downscale the source buffer to destination raster image.

TVOUT operation may be conditioned with the following set of flags.
Some of these flags are not especially usable except to the kernel,
but are included for completeness.

These "TV_Flags" identifiers are specified in a quoted comma
separated list from the following identifier set: 
 singlechipcompat - Enables AMD Geode(TM) SC1200, SC2200, and SC3200 processor compatibility mode.
 extendedsav      - Enables extended SAV/EAV codes.
 vbi              - Use the task bit to indicate VBI data.
 task             - Set Task Bit to 1in VIP 2.0 mode. Default is 0.
 swap_uv          - Swap the U and V data prior to output.
 swap_vbi         - Swap the VBI bytes prior to output.
for example:
       Option "TV_Flags" "swap_uv"  -or
       Option "TV_Flags" "extendedsav:swap_uv"

These "TV_601_Flags" identifiers are specified in a quoted comma
separated list from the following identifier set: 
 inv_de_pol       - Invert the polarity of display enable
 inv_hs_pol       - Invert the polarity of hsync
 inv_vs_pol       - Invert the polarity of vsync
 vsync-4          - The VSync occurs 4 clocks earlier
 vsync-2          - The VSync occurs 2 clocks earlier
 vsync+0          - The VSync is not shifted at all
 vsync+2          - The Vsync occurs 2 clocks later
for example:
       Option "TV_601_Flags" "inv_vs_pol"

These "TV_Vsync_Select" identifiers are specified in a quoted comma
separated list from the following identifier set: 
 disabled         - VSync out disabled
 vg               - The VSync signal from the VG (video generator)
 vg_inv           - The VSync signal from the VG (inverted)
 statreg17        - 1 written to VIP status bit 17 toggles vsync (0-1-0)
 statreg17_inv    - 1 written to VIP status bit 17 toggles vsync (1-0-1)
for example:
       Option "TV_Vsync_Select" "disabled"


6. Screen section:

The screen section selects among the other various sections for
sets of operational parameters and constraints.  A typical
"Screen" section has the form:

Section "Screen"
    Identifier  "ScreenId"
    Device      "Geode"
    Monitor     "MonitorId"
    DefaultDepth 24

    SubSection "Display"
        Depth           24
        FbBpp           32
        Modes          "1280x1024" "1024x768" "800x600" "640x480" "tv-ntsc" "tv-pal"
    EndSubsection
...

EndSection

In this example, the "Modes" selection of the display subsection specifies a
list of available modes.  These modes are selectable using "Ctl-Alt-KpPlus" or
"Ctl-Alt-KpMinus" on most PC keyboards.  It is also possible to select a mode
using the xrandr utility, as well as using the X library API.

The DefaultDepth may be 24, 16 or 8.  If the depth is 24, then the "FbBpp" line
is needed to specify the frame buffer format as 32 bits (hardware limitation).
If a custom mode is specified, care should be taken to be sure it does not
collide with a "builtin" mode, since the builtin mode will supersede.

For a more complete functional description, review the "cimarron"
reference and Geode LX processor functional specifications.


--------------------------------------------------------------------------------
RELEASE HISTORY (Previous Version)
--------------------------------------------------------------------------------
Previous Version: 1.02.0900
Release Date: 26 May 2005

Dependencies
------------
- Built with xorg-x11-6.7.0 from Fedora Core 2 Source Updates
- Built with X11R6.8.1 from freedesktop.org
                                                                                
- This driver has been tested with Linux Kernel 2.6.11
    using the Fedora Core 2 image environment
    using the Gentoo 2004.3 image environment

- To use the Xv adaptor interface
   1) create a "videox" link to the geodev4l2 video device in /dev
      ln -s video0 /dev/videox
   2) uncomment the '  Load "z4l"' line in xorg.conf


Functional Changes
------------------
- First release

Defects Corrected
-----------------
- First release

Known Errata
------------
Issue: 

PBZ#4025 X - Rotations{90,270}, only lowest refresh rate pass mode validation
Description: 
At 90 and 270 degree rotations, only the lowest supported refresh
rate can be entered.  The rest of the refresh rates appear to fail mode 
validation (xrandr does not see them as options, and I can not 
CTL->ALT->+/- through the modes).  This issue does not occur at 0 or 
180 degree rotations.  
Resolution: 
This is an inherent weakness of the X mode switch -- where even a full X R&R 
implementation would not fix this.
Steps to address will need to be:
(1) convert AMD rotation support to X R&R
(2) patch X to better handle X R&R
This may be addressed in a future version.

================================================================================
Copyright
---------
Copyright 2005 Advanced Micro Devices, Inc. All rights reserved.
The contents of this document are provided in connection with Advanced Micro
Devices, Inc. ("AMD") products. AMD makes no representations or warranties
with respect to the accuracy or completeness of the contents of this
publication and reserves the right to make changes to specifications and
product descriptions at any time without notice. No license, whether express,
implied, arising by estoppel or otherwise, to any intellectual property rights
is granted by this publication. Except as set forth in AMD's Standard Terms
and Conditions of Sale, AMD assumes no liability whatsoever, and disclaims any
express or implied warranty, relating to its products including, but not
limited to, the implied warranty of merchantability, fitness for a particular
purpose, or infringement of any intellectual property right. AMD's products
are not designed, intended, authorized or warranted for use as components in
systems intended for surgical implant into the body, or in other applications
intended to support or sustain life, or in any other application in which the
failure of AMD's product could create a situation where personal injury,
death, or severe property or environmental damage may occur. AMD reserves the 
right to discontinue or make changes to its products at any time without notice.


Trademarks
----------
AMD, the AMD Arrow logo, and combinations thereof, and Geode are trademarks 
of Advanced Micro Devices, Inc.

Other product names used in this publication are for identification purposes
only and may be trademarks of their respective companies.
================================================================================
