Initial revision

1 files changed, 218 insertions, 0 deletions

diff --git a/afb/Xdaniver.doc b/afb/Xdaniver.doc
new file mode 100644
index 000000000..1c8ad5ad4
--- /dev/null
+++ b/afb/Xdaniver.doc
@@ -0,0 +1,218 @@
+
+What is it?
+-----------
+
+Xdaniver is a fast, colour X11R6 server for the Amiga's custom chip set
+under NetBSD 1.0 and NetBSD-current, supporting all the Amiga's display
+depths from 1 to 4 (upto 16 colours) on ECS machines and 1 to 8 (upto 256
+colours) on AGA machines (though, not all resolutions are available, see
+General Information below).
+
+Xdaniver is designed to be a drop-in replacement for the Xmono server provided
+with the X11R6 binary distribution supplied by Bernd Ernesti available from
+ftp.uni-regensburg.de or one of its mirrors.
+
+Unlike previous colour X servers for the Amiga that emulate a chunky pixel
+screen in fast RAM, use the standard frame buffer drivers provided with the
+X11R6 source code to draw and then use a chunky to planar conversion routine
+to write the results to the screen (all very slow), Xdaniver uses a heavily
+modified mono frame buffer driver to draw directly using the Amiga's planar
+format. The net result is much faster drawing and support for all the Amiga's
+custom display depths but, as usual, the fewer planes used, the faster the
+drawing operations of the X server. Even so, on my A1200 with a 33Mhz 68030,
+I'm getting reasonable performance when using 8 bit planes in Dbl NTSC mode.
+
+Installation
+------------
+
+You will need to have first obtained and installed the X11R6 binary
+distribution available from ftp.uni-regensburg.de in
+/pub/NetBSD-Amiga/contrib/X11 or one of its mirrors.  Xdaniver has been
+compiled to expect font and configuration files sitting under
+/usr/local/X11R6, if your setup is different you will need to provide a
+symbolic link from /usr/local/X11R6 to where your tree resides or supply
+several command line flags to the server.
+
+To get Xdaniver running as the default X server, copy the uncompressed binary
+into /usr/local/X11R6/bin, remove the current X file from that directory
+(which is a symbolic link to Xmono) and replace it with a link to Xdaniver:
+
+	gzip -d < X11R6.Xdaniver.1.01.tar.gz | tar xvf -
+	mv Xdaniver /usr/local/X11R6/bin
+	cd /usr/local/X11R6/bin
+	rm X
+	ln -s Xdaniver X
+
+Note that on some setups, the devices /dev/kbd, /dev/mouse and /dev/view??
+have been created to be accessable only by superuser; Xdaniver needs to open
+these devices. To workaround this problem, log on as superuser and then
+either make Xdaniver setuid root:
+
+	chown root Xdaniver
+	chmod 4755 Xdaniver
+
+or give everyone access the devices:
+
+	chmod 666 /dev/kbd /dev/mouse /dev/view??
+
+the latter option is a possible cause of a security hole if your machine is
+ever used multi-user.
+
+General Information
+-------------------
+
+The default resolution of the server is 700x430 and the default depth 4. AGA
+users might what to increase the display depth by editing the startx script
+and providing a -depth <depth> argument to Xdaniver on the xinit line of the
+script. As always, the lower the depth, the faster the drawing and window
+manipulation of the server.
+
+The resolution can be altered similarly by suppling -width <width> and
+-height <height> arguments to the server.
+
+The NetBSD kernel selects actual screen modes by picking a mode who's
+natural, non-overscanned size best-fits the requested resolution.
+Unfortunately, for AGA users, the 1.0 kernel only has support for the
+Dbl-NTSC AGA display mode and only this mode has support for depths greater
+than 4. The NetBSD-current (work-in-progress) kernel also has support for
+Dbl-PAL but still no support for the Super72 or other super-hires modes
+(perhaps some kind, kernel-hacker could add support for them ?).
+
+If you have a 2 button mouse (like me) you might want to try and use the 3
+button mouse emulation. On other systems, it is usual for the left and right
+buttons to be provided and emulate the middle button by pressing both
+buttons together, however, the middle button is tends to be used more than
+the right button so I have provided two options:
+
+-emulateright (or -3), the two physical mouse buttons act as left and middle
+and pressing them both together emulates the right button.
+
+-emulatemiddle (or -2), the two physical mouse buttons act as left and right
+and pressing them both together emulated the middle button.
+
+When using screen depths of less than 6 (4 is the maximum for ECS machines)
+the lack of possible colours on screen at once causes problems for many X
+applications.  Specifying -cc 2 as a command line argument to Xdaniver
+causes the server to switch the default visual type from PsuedoColor to
+StaticColor; to put it simply, the server prefills the colormap with a
+selection of 16 colours (depth 4) and when an application asks for a
+particular colour, its gets allocated one that is closest to one from the
+selection of 16. This removes the 'WARNING: Cannot allocate colormap entry
+for "XXX"' errors but at the expense of applications not being able to get
+the precise colour they wanted. Also, some badly written X applications fail
+altogether when presented with a StaticColor visual.
+
+Bugs/Limitations
+----------------
+
+The limited choice of display resolutions for AGA/ECS machines is a real
+pain - requires a kernel change to fix. Worse still, the kernel specifies
+the maximum overscan resolution on the Dbl-NTSC to be 724x482 but selecting
+anything more than 702x430 on my machine causes the screen either sheer
+diagonally (as if the bytes per row calculation in Xdaniver or the kernel is
+wrong) or completely loose sync (suggesting a custom chip register sync
+calculation bug). As other, non-aga modes aren't affected when selection
+overscan both problems seem to point to a kernel driver bug. Also, depths
+greater than 4 for AGA users are only supported by the kernel in the Dbl-NTSC
+mode (and Dbl-PAL with the current-NetBSD kernel).
+
+I know of one bug so-far (there will be more), The PutImage request of an XY
+format image expects the bitplane order to be the reverse of that specified
+in the X protocol but since virtually all applications use the Z (chunky)
+format, you are unlikely to come across this problem.
+
+The PutImage request of Z format images is a little slow - when I have time
+I'll try and add one of the fast assembly chunky-to-planar routines developed
+for doom style games/demos. Unfortunately, the current crop all require a
+picture size that is a multiple of 32 pixels and so cannot be used out-of-the-
+box.
+
+Some extra performance could easily be squeezed out of the terminal font
+drawing code (used by xterm) - when I have time I'll add the code.
+
+The Amiga's blitter and sprites are totally unused and will remain so
+until/if someone else adds support to the kernel. The blitter would help
+speed up screen scrolling and window manipulation and sprite support could
+be used for the X pointer shape (if small enough) which would speed up all
+drawing operations (no need to remove the software based pointer shape
+first, draw, then replace the pointer shape).
+
+I removed the X image extension (XIE) from the X server as it increased the
+size of the binary by some 400k. I haven't come across any applications that
+need it yet (I haven't been looking!) so if you need the extension for some
+reason send me e-mail and I'll build a server with the extension included.
+
+The 3 button mouse emulation is very simple - to emulate the 3rd button you
+have to press both button precisely at the same moment - I've got quite good
+at it now. When I have some spare time I'll add a timer so you will have a
+few milli-seconds between one button being pressed and the next and it still
+being registered as the emulated button.
+
+AGA users don't forget to provide the -A flag to loadbsd to enable the one
+AGA mode in the 1.0 kernel but only if you have a VGA, multisync or dual-scan
+monitor, of course !
+
+Xdaniver has been tested on:
+
+A1200, 33Mhz 68030, 8Mb RAM and NetBSD 1.0 by myself.
+A4000/40, 12Mb RAM and NetBSD 1.0 by Andreas Holzhammer.
+A3000, 12Mb RAM and NetBSD 1.0 by Charlie Root, Stuart Park and others.
+A3000, 25Mhz 68040, 18Mb RAM and NetBSD-current by Michael K. Sanders.
+A2000, 8Mb RAM and NetBSD (version unknown) by Hubert Feyrer.
+
+Release and Bug Fix History
+---------------------------
+
+1.0	- First release
+
+1.01	Bugs fixed:
+	- Narrow (<32 pixels) Z format GetImage requests corrupted the stack
+	  and could cause the server to core dump. (Xpaint caused this problem)
+	- Drawing dots (PolyPoint request) into a clipped window caused a
+	  c pointer to go out of range, causing a core dump (xv showed this
+	  problem).
+
+	New features:
+	- Simple 3 button mouse emulation using a 2 button mouse; specify
+	 -emulate_middle (or -2) or -emulate_right (or -3) on the server's
+	 command line and press both mouse buttons together emulate the 'missing'
+	 button.
+	- Basic beep sound support added by sending bell characters to the
+	  console.
+	- Source code released.
+
+Disclaimer and Copyright Notices
+--------------------------------
+
+Multi-depth planar frame buffer code:
+Copyright (c) 1995 by Daniver Limited.
+
+Large portions:
+Copyright (c) 1994 by Eduardo Horvath.
+Copyright (c) 1987-1995 by the Regents of the University of California.
+Copyright (c) 1987 by Sun Microsystems, Inc. Mountain View, CA.
+Copyright (c) 1987-1995 by X Consortium.
+Copyright (c) 1987, 1989 by Digital Equipment Corporation, Maynard, Massachusetts.
+Copyright (c) 1989 Network Computing Devices, Inc., Mountain View, California.
+
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted, provided
+that the above copyright notice appear in all copies.  The Daniver Limited,
+the above companies and individuals makes no representations about the
+suitability of this software for any purpose.  It is provided "as is" without
+express or implied warranty.
+
+Credits
+-------
+
+Thanks to Bernd Ernesti for making the operating system server source code
+available for others to use and Eduardo Horvath and Andy Heffernan, who (I
+think) did the original Xmono server port.
+
+Also, many thanks to the first brave users who tested Xdaniver for me on other
+Amiga setups and found a few bugs in the process.
+
+Gary Henderson.
+
+Daytime: garyh@wet.sbi.com
+Home: gary@daniver.demon.co.uk