xorg-server-1.4/afb/Xdaniver.doc

   1
   2 What is it?
   3 -----------
   4
   5 Xdaniver is a fast, colour X11R6 server for the Amiga's custom chip set
   6 under NetBSD 1.0 and NetBSD-current, supporting all the Amiga's display
   7 depths from 1 to 4 (upto 16 colours) on ECS machines and 1 to 8 (upto 256
   8 colours) on AGA machines (though, not all resolutions are available, see
   9 General Information below).
  10
  11 Xdaniver is designed to be a drop-in replacement for the Xmono server provided
  12 with the X11R6 binary distribution supplied by Bernd Ernesti available from
  13 ftp.uni-regensburg.de or one of its mirrors.
  14
  15 Unlike previous colour X servers for the Amiga that emulate a chunky pixel
  16 screen in fast RAM, use the standard frame buffer drivers provided with the
  17 X11R6 source code to draw and then use a chunky to planar conversion routine
  18 to write the results to the screen (all very slow), Xdaniver uses a heavily
  19 modified mono frame buffer driver to draw directly using the Amiga's planar
  20 format. The net result is much faster drawing and support for all the Amiga's
  21 custom display depths but, as usual, the fewer planes used, the faster the
  22 drawing operations of the X server. Even so, on my A1200 with a 33Mhz 68030,
  23 I'm getting reasonable performance when using 8 bit planes in Dbl NTSC mode.
  24
  25 Installation
  26 ------------
  27
  28 You will need to have first obtained and installed the X11R6 binary
  29 distribution available from ftp.uni-regensburg.de in
  30 /pub/NetBSD-Amiga/contrib/X11 or one of its mirrors.  Xdaniver has been
  31 compiled to expect font and configuration files sitting under
  32 /usr/local/X11R6, if your setup is different you will need to provide a
  33 symbolic link from /usr/local/X11R6 to where your tree resides or supply
  34 several command line flags to the server.
  35
  36 To get Xdaniver running as the default X server, copy the uncompressed binary
  37 into /usr/local/X11R6/bin, remove the current X file from that directory
  38 (which is a symbolic link to Xmono) and replace it with a link to Xdaniver:
  39
  40         gzip -d < X11R6.Xdaniver.1.01.tar.gz | tar xvf -
  41         mv Xdaniver /usr/local/X11R6/bin
  42         cd /usr/local/X11R6/bin
  43         rm X
  44         ln -s Xdaniver X
  45
  46 Note that on some setups, the devices /dev/kbd, /dev/mouse and /dev/view??
  47 have been created to be accessable only by superuser; Xdaniver needs to open
  48 these devices. To workaround this problem, log on as superuser and then
  49 either make Xdaniver setuid root:
  50
  51         chown root Xdaniver
  52         chmod 4755 Xdaniver
  53
  54 or give everyone access the devices:
  55
  56         chmod 666 /dev/kbd /dev/mouse /dev/view??
  57
  58 the latter option is a possible cause of a security hole if your machine is
  59 ever used multi-user.
  60
  61 General Information
  62 -------------------
  63
  64 The default resolution of the server is 700x430 and the default depth 4. AGA
  65 users might what to increase the display depth by editing the startx script
  66 and providing a -depth <depth> argument to Xdaniver on the xinit line of the
  67 script. As always, the lower the depth, the faster the drawing and window
  68 manipulation of the server.
  69
  70 The resolution can be altered similarly by suppling -width <width> and
  71 -height <height> arguments to the server.
  72
  73 The NetBSD kernel selects actual screen modes by picking a mode who's
  74 natural, non-overscanned size best-fits the requested resolution.
  75 Unfortunately, for AGA users, the 1.0 kernel only has support for the
  76 Dbl-NTSC AGA display mode and only this mode has support for depths greater
  77 than 4. The NetBSD-current (work-in-progress) kernel also has support for
  78 Dbl-PAL but still no support for the Super72 or other super-hires modes
  79 (perhaps some kind, kernel-hacker could add support for them ?).
  80
  81 If you have a 2 button mouse (like me) you might want to try and use the 3
  82 button mouse emulation. On other systems, it is usual for the left and right
  83 buttons to be provided and emulate the middle button by pressing both
  84 buttons together, however, the middle button is tends to be used more than
  85 the right button so I have provided two options:
  86
  87 -emulateright (or -3), the two physical mouse buttons act as left and middle
  88 and pressing them both together emulates the right button.
  89
  90 -emulatemiddle (or -2), the two physical mouse buttons act as left and right
  91 and pressing them both together emulated the middle button.
  92
  93 When using screen depths of less than 6 (4 is the maximum for ECS machines)
  94 the lack of possible colours on screen at once causes problems for many X
  95 applications.  Specifying -cc 2 as a command line argument to Xdaniver
  96 causes the server to switch the default visual type from PsuedoColor to
  97 StaticColor; to put it simply, the server prefills the colormap with a
  98 selection of 16 colours (depth 4) and when an application asks for a
  99 particular colour, its gets allocated one that is closest to one from the
 100 selection of 16. This removes the 'WARNING: Cannot allocate colormap entry
 101 for "XXX"' errors but at the expense of applications not being able to get
 102 the precise colour they wanted. Also, some badly written X applications fail
 103 altogether when presented with a StaticColor visual.
 104
 105 Bugs/Limitations
 106 ----------------
 107
 108 The limited choice of display resolutions for AGA/ECS machines is a real
 109 pain - requires a kernel change to fix. Worse still, the kernel specifies
 110 the maximum overscan resolution on the Dbl-NTSC to be 724x482 but selecting
 111 anything more than 702x430 on my machine causes the screen either sheer
 112 diagonally (as if the bytes per row calculation in Xdaniver or the kernel is
 113 wrong) or completely loose sync (suggesting a custom chip register sync
 114 calculation bug). As other, non-aga modes aren't affected when selection
 115 overscan both problems seem to point to a kernel driver bug. Also, depths
 116 greater than 4 for AGA users are only supported by the kernel in the Dbl-NTSC
 117 mode (and Dbl-PAL with the current-NetBSD kernel).
 118
 119 I know of one bug so-far (there will be more), The PutImage request of an XY
 120 format image expects the bitplane order to be the reverse of that specified
 121 in the X protocol but since virtually all applications use the Z (chunky)
 122 format, you are unlikely to come across this problem.
 123
 124 The PutImage request of Z format images is a little slow - when I have time
 125 I'll try and add one of the fast assembly chunky-to-planar routines developed
 126 for doom style games/demos. Unfortunately, the current crop all require a
 127 picture size that is a multiple of 32 pixels and so cannot be used out-of-the-
 128 box.
 129
 130 Some extra performance could easily be squeezed out of the terminal font
 131 drawing code (used by xterm) - when I have time I'll add the code.
 132
 133 The Amiga's blitter and sprites are totally unused and will remain so
 134 until/if someone else adds support to the kernel. The blitter would help
 135 speed up screen scrolling and window manipulation and sprite support could
 136 be used for the X pointer shape (if small enough) which would speed up all
 137 drawing operations (no need to remove the software based pointer shape
 138 first, draw, then replace the pointer shape).
 139
 140 I removed the X image extension (XIE) from the X server as it increased the
 141 size of the binary by some 400k. I haven't come across any applications that
 142 need it yet (I haven't been looking!) so if you need the extension for some
 143 reason send me e-mail and I'll build a server with the extension included.
 144
 145 The 3 button mouse emulation is very simple - to emulate the 3rd button you
 146 have to press both button precisely at the same moment - I've got quite good
 147 at it now. When I have some spare time I'll add a timer so you will have a
 148 few milli-seconds between one button being pressed and the next and it still
 149 being registered as the emulated button.
 150
 151 AGA users don't forget to provide the -A flag to loadbsd to enable the one
 152 AGA mode in the 1.0 kernel but only if you have a VGA, multisync or dual-scan
 153 monitor, of course !
 154
 155 Xdaniver has been tested on:
 156
 157 A1200, 33Mhz 68030, 8Mb RAM and NetBSD 1.0 by myself.
 158 A4000/40, 12Mb RAM and NetBSD 1.0 by Andreas Holzhammer.
 159 A3000, 12Mb RAM and NetBSD 1.0 by Charlie Root, Stuart Park and others.
 160 A3000, 25Mhz 68040, 18Mb RAM and NetBSD-current by Michael K. Sanders.
 161 A2000, 8Mb RAM and NetBSD (version unknown) by Hubert Feyrer.
 162
 163 Release and Bug Fix History
 164 ---------------------------
 165
 166 1.0     - First release
 167
 168 1.01    Bugs fixed:
 169         - Narrow (<32 pixels) Z format GetImage requests corrupted the stack
 170           and could cause the server to core dump. (Xpaint caused this problem)
 171         - Drawing dots (PolyPoint request) into a clipped window caused a
 172           c pointer to go out of range, causing a core dump (xv showed this
 173           problem).
 174
 175         New features:
 176         - Simple 3 button mouse emulation using a 2 button mouse; specify
 177          -emulate_middle (or -2) or -emulate_right (or -3) on the server's
 178          command line and press both mouse buttons together emulate the 'missing'
 179          button.
 180         - Basic beep sound support added by sending bell characters to the
 181           console.
 182         - Source code released.
 183
 184 Disclaimer and Copyright Notices
 185 --------------------------------
 186
 187 Multi-depth planar frame buffer code:
 188 Copyright (c) 1995 by Daniver Limited.
 189
 190 Large portions:
 191 Copyright (c) 1994 by Eduardo Horvath.
 192 Copyright (c) 1987-1995 by the Regents of the University of California.
 193 Copyright (c) 1987 by Sun Microsystems, Inc. Mountain View, CA.
 194 Copyright (c) 1987-1995 by X Consortium.
 195 Copyright (c) 1987, 1989 by Digital Equipment Corporation, Maynard, Massachusetts.
 196 Copyright (c) 1989 Network Computing Devices, Inc., Mountain View, California.
 197
 198 Permission to use, copy, modify, and distribute this software and its
 199 documentation for any purpose and without fee is hereby granted, provided
 200 that the above copyright notice appear in all copies.  The Daniver Limited,
 201 the above companies and individuals makes no representations about the
 202 suitability of this software for any purpose.  It is provided "as is" without
 203 express or implied warranty.
 204
 205 Credits
 206 -------
 207
 208 Thanks to Bernd Ernesti for making the operating system server source code
 209 available for others to use and Eduardo Horvath and Andy Heffernan, who (I
 210 think) did the original Xmono server port.
 211
 212 Also, many thanks to the first brave users who tested Xdaniver for me on other
 213 Amiga setups and found a few bugs in the process.
 214
 215 Gary Henderson.
 216
 217 Daytime: garyh@wet.sbi.com
 218 Home: gary@daniver.demon.co.uk