//bugs.freedesktop.org/show_bug.cgi?id=2485) attachment #1855XORG-6_8_2XORG-6_8-branch

    (https://bugs.freedesktop.org/attachment.cgi?id=1855): Update release
    notes for SiS driver. Patch by Thomas Winischhofer
    <thomas@winischhofer.net>.

1 files changed, 133 insertions, 115 deletions

diff --git a/README.sgml b/README.sgml
index e911c8c..ca365e5 100644
--- a/README.sgml
+++ b/README.sgml
@@ -17,136 +17,152 @@
 
 <sect> Introduction <p>
 
-This driver is written by Thomas Winischhofer and is a (nearly) complete re-write
-of a driver written for the SiS6326 and SiS530 by Alan Hourihane and others.
+This driver is written by Thomas Winischhofer and is a (nearly) complete
+re-write of a driver written for the SiS6326 and SiS530 by Alan Hourihane
+and others.
 
 It currently supports the following chipsets:
 <itemize>
    <item>old series: 5597/5598, 6236/AGP/DVD, 530/620
    <item>300 series: 300/305, 540, 630/730
-   <item>315 series: 315, 550, 650, 651, M650, 740
-   <item>330 series: 330 ("Xabre"), 661FX, M661FX, 741, 760
+   <item>315 series: 315/E/PRO, 550/551/552, 650, 651, M650, 740
+   <item>330 series: 330 ("Xabre"), [M]661[F/M]X, [M]741[GX], [M]760[GX]
 </itemize>
 
-The driver supports:
+Among other features, the driver supports
 <itemize>
-  <item>8/16/24 bits color depth; old series also 15;
-  <item>XAA 
-  <item>XVideo (Xv)
-  <item>Render (XRAND)
-  <item>Hardware cursor; 315/330 series: Color HW cursor;
+  <item>8/16/24 bits color depth; old series also 15
+  <item>Hardware cursor; 315/330 series: Color HW cursor
+  <item>XAA; XVideo (Xv); RENDER (XRAND) and other extensions
   <item>6326: TV output
   <item>300/315/330 series: TV output via Chrontel TV encoders or SiS video bridges
   <item>300/315/330 series: LCD output via LVDS transmitters or SiS video bridges
-  <item>300/315/330 series: Dual head mode; Xinerama; Merged framebuffer mode;
+  <item>300/315/330 series: Dual head mode; Xinerama; Merged framebuffer mode
 </itemize>
 
-This document gives an overview over the driver's features and configuration options.
-Please see http://www.winischhofer.net/linuxsisvga.shtml for detailed documentation
-and updates.
+This document provides a brief overview over the driver's features and
+configuration options. Please see http://www.winischhofer.at/linuxsisvga.shtml
+for detailed documentation and updates.
 
 <sect> xorg.conf Options <p>
 
-The following options are of particular interest for the SiS
-driver. Each of them must be specified in the Device section of the
-xorg.conf file for this card.
+The following options are of particular interest for the SiS driver. Each of them
+must be specified in the Device section of the xorg.conf file for this card.
 
-<sect1>For all chipsets<p>
+In the list below, the options' arguments are described by type. For "boolean",
+the keywords "on", "true" and "yes", as well as "off", "false" and "no" respectively
+have the same meaning.
+
+<sect1> For all chipsets<p>
 
 <descrip>
-<tag>Option "SWCursor", "HWCursor"</tag>
+<tag>Option "SWCursor" [boolean]</tag>
+<tag>Option "HWCursor" [boolean]</tag>
 	These options select whether the software (SW) or hardware (HW) cursor should
 	be used. The default is using the hardware cursor.
-<tag>Option "NoAccel"</tag>
-        Disables 2D acceleration. Default: 2D acceleration is enabled.
-<tag>Option "Turboqueue"</tag>
-	SiS chipsets have the option to extend the engine command queue on
-	VRAM. This concept is called "TurboQueue" and gives some performance improvement.
-	Due to hardware bugs, the TurboQueue is disabled on the 530/620, otherwise
-	enabled by default.
-<tag>Option "Rotate"</tag>
-        This option enables clockwise ("CW") or counter-clockwise ("CCW") rotation of
+<tag>Option "NoAccel" [boolean]</tag>
+	Disables 2D acceleration. By default, 2D acceleration is enabled.
+<tag>Option "Rotate" [string]</tag>
+	This option enables clockwise ("CW") or counter-clockwise ("CCW") rotation of
 	the display. Enabling either CW or CCW rotation disables the RandR extension.
 	Default: no rotation.
-<tag>Option "ShadowFB"</tag>
-        This option enables the shadow framebuffer layer. By default, it is disabled.
-<tag>Option "NoXVideo"</tag>
-        Disables the XVideo support. Default: XVideo support is enabled.
-<tag>Option "CRT1Gamma"</tag>
-        Enables or disables gamma correction. Default: gamma correction is enabled.
+<tag>Option "ShadowFB" [boolean]</tag>
+	This option enables the shadow framebuffer layer. By default, it is disabled.
+<tag>Option "NoXVideo" [boolean]</tag>
+	Disables the XVideo (Xv) support. By default, XVideo support is enabled.
+<tag>Option "CRT1Gamma" [boolean]</tag>
+	Enables or disables gamma correction. Default: gamma correction is enabled.
 </descrip>
 
-<sect1>old series specific options <p>
+<sect1> old series specific options <p>
 
 <descrip>
-<tag>Option "FastVram"</tag>
-        Enables 1 cycle memory access for read and write operations. The default
+<tag>Option "FastVram" [boolean]</tag>
+	Enables 1 cycle memory access for read and write operations. The default
 	depends on the chipset used.
-<tag>Option "NoHostBus"</tag>
-        For 5597/5598 only. This option, if set, disables the CPU to VGA host bus.
+<tag>Option "Turboqueue" [boolean]</tag>
+	SiS chipsets have the ability to extend the engine command queue in
+	video RAM. This concept is called "TurboQueue" and gives some performance
+	improvement. Due to hardware bugs, the TurboQueue is disabled on the 530/620,
+	otherwise enabled by default.
+<tag>Option "NoHostBus" [boolean]</tag>
+	For 5597/5598 only. This option, if set, disables the CPU to VGA host bus.
 	Disabling the host bus will result in a severe performance regression.
-<tag>VideoRAM size</tag> The SiS 6326 can only directly address 4096K
-        bytes of video RAM. However, there are some cards out there featuring
-	8192K (8MB) of video RAM. This RAM is not addressable by the engines.
-	Therefore, by default, the driver will only use 4096K. This behavior
-	can be overridden by specifying the amount of video RAM using the
-	VideoRAM keyword. If more than 4096K is specified, the driver will
-	disable 2D acceleration, Xv and the HW cursor. On all other chipsets,
-	this keyword is ignored.
-<tag>Option "NoYV12"</tag>
-        Due to hardware bugs, XVideo may display a corrupt image when using
+<tag>VideoRAM [size]</tag>
+	The SiS 6326 can only directly address 4096K bytes of video RAM. However,
+	there are some cards out there featuring 8192K (8MB) of video RAM. This RAM
+	is not addressable by the engines. Therefore, by default, the driver will
+	only use 4096K. This behavior can be overridden by specifying the amount of
+	video RAM using the VideoRAM keyword. If more than 4096K is specified, the
+	driver will disable 2D acceleration, Xv and the HW cursor. On all other
+	chipsets, this keyword is ignored. The size argument is expected in KB, but
+	without "KB".
+<tag>Option "NoYV12" [boolean]</tag>
+	Due to hardware bugs, XVideo may display a corrupt image when using
 	YV12 encoded material. This option, if set, disables support for YV12
 	and hence forces the Xv-aware application to use either YUV2 or XShm
 	for video output.
-<tag>Option "TVStandard"</tag>
+<tag>Option "TVStandard" [string]</tag>
 	(6326 only) Selects the TV output standard. May be PAL or NTSC. By default,
 	this is selected by a jumper on the card.
 </descrip>
 
-<sect1>300/315/330 series specific options<p>
+<sect1> 300/315/330 series specific options<p>
 
 <descrip>
-<tag>Option "ForceCRT1"</tag>
-        Enables or disables CRT1 (= the external VGA monitor). By default,
+<tag>Option "EnableSiSCtrl" [boolean]</tag>
+	This option enables/disables the driver's interface for the SiSCtrl
+	utility. Please see http://www.winischhofer.at/linuxsisvga.shtml
+	for more information.
+<tag>Option "Turboqueue" [boolean]</tag>
+	(300 series only) SiS chipsets have the ability to extend the engine
+	command queue in video RAM. This concept is called "TurboQueue" and gives
+	some performance improvement. The TurboQueue is enabled by default.
+<tag>Option "ForceCRT1" [boolean]</tag>
+	Enables or disables CRT1 (= the external VGA monitor). By default,
 	the driver will use CRT1 if a monitor is detected during server
 	start. Some older monitors can't be detected, so they may require
 	setting this option to true. To disable CRT1 output, set this option
 	to false.
-<tag>Option "ForceCRT1Type"</tag>
- 	SiS 650, M650 and 651 with either 301LV or 302LV video bridge only.
-	May be VGA or LCD. Specifying LCD will force the driver to use the
-	VGA controller's CRT1 channel for driving the LCD, while CRT2 is
-	free for TV usage. Default is VGA.
-<tag>Option "ForceCRT2Type"</tag>
-    Selects the CRT2 output device type. Valid parameters are LCD, TV,
-	SVIDEO, COMPOSITE, SCART, VGA, NONE. NONE disables CRT2. SVIDEO and
-	COMPOSITE are only for systems with a SiS video bridge and select the
-	desired plug type. For Chrontel systems, TV should be used instead.
-	VGA means secondary VGA and is only available on some SiS video bridges
+<tag>Option "ForceCRT1Type" [string]</tag>
+	(For SiS 650, M650, 651, 661, 741, 760 with either SiS 301LV, 302LV or
+	SiS 301C video bridge only) The argument may be "VGA" or "LCD". Specifying
+	LCD will force the driver to use the VGA controller's CRT1 channel for
+	driving	the LCD while CRT2 is free for TV usage. Default is VGA.
+<tag>Option "ForceCRT2Type" [string]</tag>
+	Selects the CRT2 output device type. Valid parameters are "LCD", "TV",
+	"SVIDEO", "COMPOSITE", "SVIDEO+COMPOSITE", "SCART", "VGA", "YPBPR480I",
+	"YPBPR480P", "YPBPR720P", "YPBPR1080I" or "NONE". NONE disables CRT2.
+	SVIDEO, COMPOSITE, SVIDEO+COMPOSITE, SCART and all the YPBPR alternatives
+	are only for systems with a SiS video bridge and select the desired plug
+	or tv standard type. For Chrontel systems, TV should be used instead. VGA
+	means secondary VGA and is only available on some SiS video bridges
 	(301, 301B, 301C).
-<tag>Option "CRT2Gamma"</tag>
-    Enables or disables gamma correction for CRT2. This is only supported
-	for SiS video bridges. Default: gamma correction for CRT2 is enabled.
-<tag>Option "DRI"</tag>
+<tag>Option "CRT2Gamma" [boolean]</tag>
+	(For SiS video bridges only) This option enables or disables gamma
+	correction for CRT2. Default: gamma correction for CRT2 is enabled.
+<tag>Option "DRI" [boolean]</tag>
 	Although this option is accepted for all chipsets, it currently only
 	makes sense on the 300 series; DRI is only supported on these chipsets.
 	This option enables/disables DRI.
-<tag>Option "TVStandard"</tag>
+<tag>Option "TVStandard" [string]</tag>
 	Selects the TV output standard. May be PAL or NTSC, on some machines
 	(depending on the hardware) also PALM and PALN. Default: BIOS setting.
-<tag>Option "TVXPosOffset", "TVYPosOffset"</tag>
+<tag>Option "TVXPosOffset" [integer]</tag>
+<tag>Option "TVYPosOffset" [integer]</tag>
 	These options allow relocating the image on your TV. Both options take
 	an integer within the range of -16 to 16. Default: 0. Not supported for
 	Chrontel 7019.
-<tag>Option "CHTVOverscan"</tag>
-	For Chrontel TV encoders only. Selects whether TV output should be
+<tag>Option "CHTVOverscan" [boolean]</tag>
+	(For Chrontel TV encoders only) Selects whether TV output should be
 	overscan or underscan.
-<tag>Option "CHTVSuperOverscan"</tag>
-	For Chrontel 7005 TV encoders in PAL mode only. Selects whether TV output
+<tag>Option "CHTVSuperOverscan" [boolean]</tag>
+	(For Chrontel 7005 TV encoders in PAL mode only) Selects whether TV output
 	should be super-overscan (slightly larger than the viewable area) or
 	not.
-<tag> Option "SISTVXScale", "SISTVYScale"</tag>
-	For SiS video bridges only. These options allow zooming the image on
+<tag>Option "SISTVXScale" [integer]</tag>
+<tag>Option "SISTVYScale" [integer]</tag>
+	(For SiS video bridges only) These options allow zooming the image on
 	your TV. SISTVXScale takes an integer within the range of -16 to 16.
 	SISTVYScale accepts -4 to 3. Default: 0. Not all modes can be scaled.
 </descrip>
@@ -154,50 +170,52 @@ xorg.conf file for this card.
 <sect1> 300 series specific options<p>
 
 <descrip>
-<tag>Option "MaxXFBMem"</tag>
-	DRI requires the linux kernel's SiS framebuffer driver "sisfb" and some
-	other modules which come with either the linux kernel or X11R&relvers;. (On *BSD,
-	the DRI driver does not require any framebuffer driver.)
-  	Sisfb takes care of memory management for texture data. In order to prevent
-	the X driver and sisfb from overwriting each others video memory, sisfb
-	reserves an amount of video memory for the X driver. This amount can either
-	be selected using sisfb's mem parameter, or auto-selected depending on the
-	amount of total video RAM available. However, the X driver needs to know about
-	the amount of RAM sisfb reserved. For this purpose, the Option "MaxXFBMem" exists.
-
-	XFree 4.3.0 disabled SiS DRI support due to a lack of maintenance of the SiS DRI
-	driver. X11R&relvers; and X11R&relvers; and XFree86 4.4 contains a newly written 
-        SiS DRI driver by Eric Anholt.
-
-	If you intend to use DRI, I recommend setting the total video memory in the BIOS
-	to 64MB in order to at least overcome the lack of memory swap functions.
-
-	Sisfb can be used for memory management only, or as a complete framebuffer driver.
-	If you start sisfb with a valid mode (ie you gain a graphical console), the X driver
-	can communicate with sisfb and doesn't require setting the MaxXFBMem option at all.
-	The X driver will receive enough information from sisfb in this case.
-
-	However, if you use sisfb for memory management only, ie you started sisfb with
-	mode=none and still have a text mode console, there is no communication between sisfb
-	and the X driver. In this case, you need to set MaxXFBMem to the same value as you
-	gave sisfb with its mem parameter. If you didn't specify any mem parameter, sisfb
-	will reserve 12288KB if more than 16MB of total video RAM is available, 8192KB if
-	between 12 and 16MB of video RAM is available, 4096KB in all other cases.
-
-	Then you need to specify any of these amounts as the parameter for the MaxXFBMem
-	option. The value is to be given without 'KB'.
+<tag>Option "MaxXFBMem" [size]</tag>
+	This option might only be needed if you are running X on a Linux 2.4 series
+	kernel. This option is not needed and should be omitted on Linux 2.6 and *BSD.
+
+	The Linux kernel features a framebuffer driver named "sisfb" which takes care
+	of memory management for DRI/DRM (such as for 3D texture data). In order to
+	keep the X driver and sisfb from overwriting each other's video memory, sisfb
+	reserves a certain amount of video memory for the X driver. Reserved memory
+	is for X 2D, pixmap cache and video data only. Sisfb will not present this
+	memory to the DRI. The amount of reserved memory can either be selected using
+	sisfb's mem parameter or auto-selected depending on the total amount of video
+	RAM available.
+
+	Fact of the matter is, the X driver needs to know about the amount of RAM
+	sisfb reserved. For this purpose, the Option "MaxXFBMem" exists.
+
+	If you start sisfb with a valid mode (ie you run a graphical console), the
+	X driver can communicate with sisfb and doesn't require setting the MaxXFBMem
+	option at all. The X driver will receive enough information from sisfb in
+	this case.
+
+	If you, on the other hand, use sisfb for memory management only, ie you started
+	sisfb with mode=none and still have a text mode console, there is no communication
+	between	sisfb and the X driver. In this - and ONLY this - case, you need to set
+	MaxXFBMem to the same value as you gave sisfb with its mem parameter. If you
+	didn't specify any mem parameter, sisfb will reserve (and you will have to
+	specify by MaxXFBMem) 12288KB if more than 16MB of total video RAM is available,
+	8192KB if between 12 and 16MB of video RAM is available, 4096KB in all other
+	cases. The size is expected in KB, without the "KB".
+
+	Final word of advice: If you intend to use DRI on an integrated chipset (such
+	as the 630/730), it is recommended to set the total video memory in the BIOS to
+	64MB in order to at least overcome the DRI driver's lack of memory swap functions.
 </descrip>
 
 <sect1> 315/330 series specific options<p>
 
 <descrip>
-<tag>Option "RenderAcceleration"</tag>
-	Enables or disables RENDER acceleration. By default, RENDER acceleration
-	is enabled.
-<tag>Option "XvOnCRT2"</tag>
-	315, 650, 740, 330 only. This option selects whether the XVideo (Xv)
-	overlay should be displayed on CRT1 or CRT2. Setting this options
-	means CRT2. The other CRT will only display the (blue) color key.
+<tag>Option "RenderAcceleration" [boolean]</tag>
+	Enables or disables RENDER acceleration. This feature, for instance, accelerates
+	output of anti-aliased text. By default, RENDER acceleration is enabled.
+<tag>Option "XvOnCRT2" [boolean]</tag>
+	(For 315, 650, 740, 330 only) This option selects whether the XVideo (Xv)
+	overlay should be displayed on CRT1 or CRT2. Setting this option means CRT2.
+	The other CRT will only display the (by default: blue) color key or a black/red
+	pattern.
 </descrip>
 
 Document based on 4.1 version written by Joanjo Santamarta and 3.3 version