path: root/afb/Xdaniver.doc

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