DinX Windowing System - Getting Started
---------------------------------------

Commands next to a '%' prompt can be run as a mortal user.
Commands next to a '#' prompt should be run as root.

1.  Read /usr/src/linux/Documentation/fb/*.txt to learn how to use
    the framebuffer driver.  To try it out in a hurry: reboot.  At
    the LILO prompt, type:

	LILO boot: linux vga=ask

    Press return at the next prompt and then enter a mode number:

	      |  640x480  800x600 1024x768 1280x1024
	------+-------------------------------------
	 8bpp |    301      303      305      307   
	16bpp |    311      314      317      31a   
	24bpp |    312      315      318      31b   

    For this example, let's use 1280x1024x24bpp: enter 31b
	
    You can also configure LILO to do this for you automatically.
    Example from my /etc/lilo.conf:

	image=/boot/vmlinuz-2.2.5-15
	        label=linux
	        root=/dev/hda2
	        read-only
	        vga=0x31b	<-- this selects VESA 1280x1024x24bpp

2.  DinX currently understands the 5-byte PS/2 mouse protocol, which can be
    produced by gpm on /dev/gpmdata from any other mouse type.  I have a
    PS/2 mouse, so I run:

	gpm -R ps2 -t ps2

    You can also configure X to use gpm, to avoid mouse conflicts. 
    My XF86Config contains:

	Protocol        "PS/2"
	Device          "/dev/gpmdata"

    If this causes problems, try Protocol "MouseSystems" instead.  
    I have no idea why, but it works for me.  :)

3.  Build DinX:

	% ./configure
	% make

4.  Become root, create device nodes:

	% su
	# doc/dinx-devices.sh

    Note that DinX doesn't have an official major number yet.  Currently it
    uses device major number 60, which is allocated for local/experimental
    use.  Please read /usr/src/linux/Documentation/devices.txt for more
    information.  If something else on your system uses character major 60,
    edit include/linux/dinx.h and change DINX_MAJOR.

6.  Add the modules to your kernel:

	# /sbin/insmod modules/dinx.o
	# /sbin/insmod modules/dinx-l8.o
	# /sbin/insmod modules/dinx-l16.o
	# /sbin/insmod modules/dinx-l24.o
	# /sbin/insmod modules/dinx-l32.o
	# cat /proc/dinx
	registered blitters: linear-32bpp linear-24bpp linear-16bpp linear-8bpp

    Support for 8bpp, 16bpp, 24bpp and 32bpp framebuffers is in dinx-l8.o,
    dinx-l16.o, dinx-l24.o and dinx-l32.o respectively.  You only have to
    insmod the one you need.  When the server opens /dev/dinxsvr (below)
    dinx.o will look for a blitter that matches the framebuffer.  If there
    is none, it will fail with ENOSYS or "Function not implemented."

7.  Read all of this step 7.  Then start the server and a mouse pointer:

	# server/dinxd &  sleep 3 ; tests/cursor &
	
    The display will blank and switch to a new virtual console.  A white
    square will appear, which you should be able to move with the mouse.

    Chances are you can switch back to the X console with LeftAlt-F7.

8.  Start a test window program or two:

	% tests/test &
	% tests/ppm --bpp 24 tests/tux.ppm &

    Press Control-LeftAlt-F8 to get back to the DinX console.  Now you
    should have two different windows - one with coloured squares and
    another with an image of our beloved mascot.  You can drag these
    windows around by holding down a button.  You can also raise with the
    left button and lower with the right button.

9.  Start a torture test program:

	% tests/torture

    You will get lots of warnings: "Resource temporarily unavailable". 
    That's normal; torture fills up event queues rather quickly.

    This program creates a window that jumps around the screen and performs
    drawing operations as fast as it can.  Running a few of these at once
    will load up the system a bit, and make the other windows really slow
    to move around when you drag them.  Not only is torture busy-looping
    sending drawing commands, but the other tests are kept busy redrawing
    as torture obscures and then exposes them.

    You can look at the state of the windows with:
    
        % cat /proc/dinx	

	registered blitters: linear-24bpp linear-16bpp linear-8bpp 
	dinx tree 0: linear-24bpp
	0xc1cbd420: {     417,      569,      787,      662} mapped
	0xc371a180: {     671,      613,      681,      623} mapped
	0xc371a000: {     287,      318,      559,      626} mapped
	0xc1cbd480: {     607,      295,      905,      648} mapped

    Kill torture by returning to your terminal and pressing Ctrl-C.
	
10. Kill the server:

	# killall dinxd
	
    When the server closes /dev/dinxsvr, all the window processes attached
    to /dev/dinxwin will receive a SIGPIPE.