# GXemul: DECstation emulation

Back to the index.

The DECstation emulation mode is the oldest full machine mode in GXemul, and probably still the most complete one. The specific model being emulated best is the 5000/200. When emulating that model, the following guest operating systems can be installed and run:

- NetBSD/pmax
- OpenBSD/pmax
- Ultrix/RISC
- Sprite
- Debian GNU/Linux

In addition to the working operating systems above, you may also want to read half-finished notes on how to run RedHat Linux/DECstation and Mach/PMAX.

The default processor in the emulated DECstation 5000/200 is a 32-bit MIPS R3000, but many of the guest operating systems are also capable of running with a 64-bit MIPS R4400, by adding `-C R4400` to the command line.

Most of the other models in the DECstation/DECsystem family are not emulated well enough to run anything meaningful. One exception is the 5000/1xx, aka 3MIN. If you are able to make a backup copy of the PROM from your own machine, then you can try to run that in the emulator.

### NetBSD/pmax:

NetBSD/pmax was the first guest OS that could be installed onto a disk image in GXemul.

To install NetBSD/pmax onto a harddisk image in the emulator, follow these instructions:

1. Create an empty harddisk image, which will be the root disk that NetBSD installs itself onto:

       	dd if=/dev/zero of=nbsd_pmax.img bs=1024 count=1 seek=7800000

2. Download a NetBSD CD-ROM iso image:

       	ftp://ftp.netbsd.org/pub/NetBSD/iso/7.1.2/NetBSD-7.1.2-pmax.iso

3. Start the emulator like this:

       	gxemul -X -e 3max -d nbsd_pmax.img -d b:NetBSD-7.1.2-pmax.iso

NetBSD 8.x and 9.x can also be installed, but there is no X server, so 7.1.2 is preferred if you want to use X.

If you do not want to use the graphical framebuffer during the install, you can skip the `-X` command line option. Remember to enter `xterm` instead of `vt100` when asked about your terminal type, if you do this. Or you can add `-Y 2` to the command line options, if you feel that the default framebuffer window is too large.

When the installation has finished, the following command should start NetBSD from the harddisk image:

    	gxemul -X -e 3max -d nbsd_pmax.img

and log in as `root`. Type `startx` to start X windows.

Remove `-X` if you only want a serial console.

If you selected to install xdm, you may not be able to login as root unless you also set a root password.

### OpenBSD/pmax:

Installing OpenBSD/pmax is a bit harder than installing NetBSD/pmax. You should first read the section above on how to install NetBSD/pmax, before continuing here. If you have never installed OpenBSD on any architecture, then you need a great deal of patience to do this. If, on the other hand you are used to installing older versions of OpenBSD, then this should be no problem for you.

OpenBSD/pmax died at release 2.8 of OpenBSD, so you should be aware of the fact that this will not give you an up-to-date OpenBSD system.

Following these instructions might work. If not, then use common sense and imagination to modify them as you see fit.

1. Create an empty harddisk image, which will be the root disk that OpenBSD installs itself onto:

       	dd if=/dev/zero of=obsd_pmax.img bs=1 count=512 seek=900000000

2. Download the entire pmax directory from the ftp server: (approx. 99 MB)

       	wget -r https://ftp.nluug.nl/OpenBSD/2.8/pmax/

3. Execute the following commands:

   ``

       mv ftp.nluug.nl/OpenBSD/2.8/pmax/simpleroot28.fs.gz .
       gunzip simpleroot28.fs.gz
       chmod +w simpleroot28.fs		<--- make sure

4. You now need to make an ISO image of the entire directory you downloaded. (I recommend using `mkisofs` for that purpose. If you don't already have `mkisofs` installed on your system, you need to install it in order to do this.)

       	mkisofs -o openbsd_pmax_2.8.iso ftp.nluug.nl/OpenBSD/2.8/pmax
       	rm -rf ftp.nluug.nl      (this directory is not needed anymore)

5. Start the emulator with all three (!) disk images:

       	gxemul -e 3max -d obsd_pmax.img -d b:simpleroot28.fs -j bsd -d c:openbsd_pmax_2.8.iso

   (If you add `-X`, you will run with the graphical framebuffer. This is REALLY slow because the console has to scroll a lot during the install. I don't recommend it.)

6. Go on with the installation as you would do if you were installing on a real machine. If you are not used to the OpenBSD installer, then this will most likely be a very uncomfortable experience. Some important things to keep in mind are:
   - rz0 is the rootdisk you wish to install onto.
   - rz1 is the simpleroot image.
   - rz2 is the CDROM containing the "install sets".
   - When asked for the "root device?", enter rz1.
   - At "Enter pathname of shell or RETURN for sh:", press enter.
   - At the # prompt, do the following:

         	fsck /dev/rz1a        (and mark the filesystem as clean)
         	mount /dev/rz1a /
         	mkdir /kern
         	mkdir /mnt2
         	mount -t kernfs kern kern
         	./install

     and proceed with the install. Good luck. :-)
   - Answer "y" when asked if you wish to configure the network. (See the section about installing NetBSD/pmax for suitable network settings.)
   - Install from "c" (cdrom), choose "rz2" as the cdrom device, and "/" as the directory containing the install sets.

7. For some unknown reason, the install script does not set the root password! The first time you boot up OpenBSD after the install, you need to go into single user mode and run passwd root to set the root password, or you will not be able to log in at all!

       	gxemul -e 3max -d obsd_pmax.img -d 2c:openbsd_pmax_2.8.iso -j bsd -o '-s'

   While you are at it, you might want to extract the X11 install sets as well, as the installer seems to ignore them too. (Perhaps due to a bug in the installer, perhaps because of the way I used mkisofs.)

   Execute the following commands in the emulator:

   ``

       fsck /dev/rz0a
       mount /
       passwd root

       cd /; mount -t cd9660 /dev/rz2c /mnt; sh
       for a in /mnt/[xX]*; do tar zxvf $a; done
       ln -s /usr/X11R6/bin/Xcfbpmax /usr/X11R6/bin/X
       ln -s /dev/fb0 /dev/mouse
       echo /usr/X11R6/lib >> /etc/ld.so.conf
       ldconfig

       sync
       halt

NOTE: It is also possible to install via ftp instead of using a CDROM image. This is not much less awkward, you still need the simpleroot filesystem image, and you still have to manually add the X11 install sets and set the root password, and so on.

Once you have completed the installation procedure, the following command will let you boot from the new rootdisk image:

    	gxemul -e 3max -X -o '-aN' -d obsd_pmax.img -j bsd

(Normally, you would be asked about which root device to use (`rz0`), but using `-o '-aN'` supresses that.)

When asked for which terminal type to use, when logging in as root, enter `rcons` if you are using the graphical framebuffer, `vt100` for text-mode.
Use `startx` to start X windows.

### Ultrix/RISC:

Ultrix/RISC 4.x can run in GXemul on the emulated DECstation 5000/200 machine model. Ultrix was the native OS for these machines.

The following instructions should let you install Ultrix onto a disk image:

1. Create an empty harddisk image, which will be the root disk that Ultrix installs itself onto:

               dd if=/dev/zero of=rootdisk.img bs=1024 count=1 seek=800000

2. Place your Ultrix installation media in your CDROM drive. (On FreeBSD and similar systems, it is called `/dev/cd0c`. Replace that with the name of your CDROM drive, or the name of a .iso image file.) Then, start the emulator like this:

               gxemul -X -e 3max -d rootdisk.img -d bc:/dev/cd0c -j vmunix

3. Once the first stage of the installation is done (restoring the root filesystem), you need to restart the emulator, booting from the new rootdisk, to continue the installation process. This is done by removing the bootflag ('`b`') from the second diskimage argument:

               gxemul -X -e 3max -d rootdisk.img -d c:/dev/cd0c -j vmunix

When the installation is completed, the following command should start Ultrix from the harddisk image:

            gxemul -X -e 3max -j vmunix -d rootdisk.img

If you have a very fast host machine, you might experience a weird timer related bug, which makes it impossible to logon to the system when using the graphical logon. It is triggered when the emulation goes faster than any real DECstation machine was capable of running. The first thing to try is to re-attempt the login a couple of times. The second thing I usually try is to break into the GXemul debugger prompt, turn on `trace` and `continue` running, login, and then break into the debugger again and turn off `trace` and finally `continue`.

If you want TCP/IP IPv4 networking, try executing the following inside ULTRIX as root:

    ifconfig ln0 10.0.0.1
    route add default 10.0.0.254 1

This will allow you to e.g. telnet to numeric IPv4 addresses.

You can experiment with adding `-Z2` (for emulating a dual-headed workstation) or even `-Z3` (tripple-headed), and also the `-Y2` option for scaling down the framebuffer windows by a factor 2x2. There is also a `-z` option for supplying names of X11 displays to use. The following example starts Ultrix on an emulated tripple-headed workstation, on three different displays (`remote1:0.0`, `localhost:0.0`, and `remote2:0.0`), using no scaledown:

            gxemul -N -e 3max -jgenvmunix -d rootdisk.img -X -Z3 -z remote1:0.0 -z localhost:0.0 -z remote2:0.0

The photo below shows a single Ultrix session running tripple-headed in GXemul on an Alpha 21164PC, with displays on a Sun Ultra1 (to the left), on the Alpha itself (in the middle), and on an HP700/RX X-terminal (8-bit color depth, running off the Alpha) to the right.

The X11 displays may differ in bit depth and endianness. Unfortunately, there is no way yet to set the scaledown factor on a per-window basis, so the scaledown factor affects all windows.

(If you didn't use `-Zn` during the installation, and compiled your own `/vmunix`, then it will not contain support for multiple graphics cards. To overcome this problem, use the generic kernel, `-j genvmunix`, whenever you are running the emulator with a different setup than the one you used when Ultrix was installed.)

A note for the historically interested: OSF/1 for MIPS was quite similar to Ultrix, so that is possible to run as well. If you are unsuccessful in installing Ultrix or OSF/1 directly in the emulator, you can always install it on your real machine onto a real SCSI disk, and then copy the contents of that SCSI disk into a file (using `dd(1)`), and use that file as a disk image file in the emulator.

### Sprite for DECstation:

Sprite was a research operating system at the University of Berkeley. A copy of a Sprite harddisk image for a DECstation 5000/200 is still available. If you want to find out more about Sprite in general, read https://web.stanford.edu/~ouster/cgi-bin/spriteRetrospective.php.

The following instructions should let you run Sprite in the emulator:

1. Download the Sprite harddisk image:

       https://github.com/OSPreservProject/sprite/raw/master/ds5000.bt

       (83973120 bytes, MD5 = ec84eeeb20fe77b758370d5e312e4a5e)

2. Start the emulator with the following command line:

       	gxemul -X -e 3max -M128 -d ds5000.bt -j vmsprite -o ''

The first time you boot up with the disk image, you will be asked a number of questions regarding network settings. If you feel like entering correct values, then you should use the following:

        Your machine's Ethernet address:    10:20:30:00:00:10
        Your machine's IP:                  10.0.0.1
        Subnet mask:                        0xff000000
        Gateway's Ethernet address:         60:50:40:30:20:10
        Gateway's IP:                       10.0.0.254

Unfortunately, at the end of https://raw.githubusercontent.com/OSPreservProject/sprite/master/boot.txt, the following sad statement can be found:

        The bootable Sprite image is meant to be a demonstration of Sprite, not
        a robust Sprite system.  There are several missing things, such as
        floating point and network support.

Once you are logged in as root, running `xinit` will start the X11 environment.

### Debian GNU/Linux for DECstation:

It is possible to run Debian GNU/Linux for DECstation in the emulator, on an emulated 5000/200 ("3max"). However, just choosing any Linux/DECstation kernel at random for the installation will not work.

- Linux 2.4/DECstation DZ serial console output doesn't work too well in GXemul. Linux oopses randomly, which may be due to bugs in GXemul, but may also be due to bugs in the serial controller code in Linux. (The speed at which serial interrupts are generated can be lowered with the `-U` command line option, but it only reduces the risk, it doesn't take away the oopses completely.)
- The Linux 2.6/DECstation DZ serial console driver doesn't work at all in the emulator, and I'm not really sure it would work on a real 5000/200 either. Hopefully this will be fixed in Linux in the future.
- To get around the serial console problem, the obvious solution is to use a graphical framebuffer instead. Old Debian install kernels supported the graphical framebuffer on the 3max, but not the keyboard. (This has been fixed now, it seems.)
- For quite some time, the MIPS linux cvs tree has had support for the framebuffer and keyboard, but it did not include Debian's patches for networking, which made it unusable for network installs. (Possibly fixed now.)
- The kernel has to be for 5000/200. This rules out using the default kernel on netinst ISO images provided by Debian. These ISO images boot directly into a kernel which is meant for a different DECstation model.
- The kernel has to have an initrd which more or less matches the version of Debian that will be installed.

Luckily, a precompiled install kernel has been made available by David Muse, for Debian for R3000 DECstations, which has support for framebuffer, keyboard, and networking, which works pretty well. Thanks David. :-)

The following steps should let you install Debian GNU/Linux for DECstation onto a harddisk image in the emulator:

1. Create an empty harddisk image, which will be the root disk that Debian installs itself onto:

       	dd if=/dev/zero of=debian_pmax.img bs=1024 count=1 seek=6000000

2. Download David Muse' install kernel, and a Debian Netinstall CD-ROM:

       	http://www.firstworks.com/mips-linux-2.4.31/vmlinux-2.4.31
       	http://cdimage.debian.org/cdimage/archive/3.1_r6a/mipsel/iso-cd/debian-31r6a-mipsel-netinst.iso

       	MD5 (vmlinux-2.4.31) = c88dc0a26b91e3646698179c18e8169b
       	MD5 (debian-31r6a-mipsel-netinst.iso) = db1bf2f8e5b24f820f37034ec1d20bdc

3. Start the installation like this:

       	gxemul -X -e3max -d debian_pmax.img -d debian-31r6a-mipsel-netinst.iso vmlinux-2.4.31

   If everything goes well, you will see Linux' boot messages, and then arrive at the language chooser.

   There will be a warning about the keyboard layout. Don't mind this. Continue, and then select Detect and mount CD-ROM in the next menu.

   There will also be a warning about lack of loadable modules. Don't mind this either, continue anyway by choosing Yes.

   When you reach the network configuration part of the install, choose Configure network manually and enter the following values:

       	IP address:                 10.0.0.1
       	Netmask:                    255.0.0.0
       	Gateway:                    10.0.0.254
       	Name server addresses:      10.0.0.254

   Choose Erase entire disk in the partitioner.

   Wait for the base system to be installed. This takes almost forever, so you can go fetch several Jolts or cups of coffee in the meanwhile.

   Congratulations! The first phase of the installation is now completed. Reboot using the following command line:

       	gxemul -X -e3max -o 'root=/dev/sda1' -d debian_pmax.img vmlinux-2.4.31

   The post-install step takes quite some time as well. A perfect opportunity for more coffee.

   When asked about whether the hardware clock is set to GMT or not, answer Yes.

   When asked about "Apt configuration", choose http as the method to use for accessing the Debian archive.

   Downloading the packages takes almost forever. Be patient.

   Congratulations (again)! You are now fully done with the installation.

Debian GNU/Linux for DECstation is now installed and ready to be used. Use this command to boot from the installed disk image:

    	gxemul -X -e3max -o 'root=/dev/sda1' -d debian_pmax.img vmlinux-2.4.31

### Redhat Linux for DECstation:

The following steps should let you run Redhat Linux for DECstation in GXemul:

1. Download a kernel. David Muse' Debian-install kernel works fine:

       	http://www.firstworks.com/mips-linux-2.4.31/vmlinux-2.4.31

2. Download a root filesystem tree:

       	ftp://ftp.linux-mips.org/pub/linux/mips/mipsel-linux/root/mipsel-root-20011216.tgz
       	19486676 bytes, md5 = 5bcb725c90209479cd7ead8ad0c4a414

3. Create a disk image which will contain the Redhat filesystem:

       	dd if=/dev/zero of=redhat_mips.img bs=1024 count=1 seek=2000000

4. This is the tricky part: on redhat_mips.img, you need to create an MS-DOS (!) partition table, and then an ext2 partition. This is what Linux will then see as /dev/sda1.

   I recommend you run fdisk and mke2fs and untar the archive from within Debian/DECstation or Debian/CATS running inside the emulator. (Alternatively, if you are on a Linux host, you could use a loopback mount, or similar. This might require root access. See e.g. http://www.mega-tokyo.com/osfaq2/index.php/Disk%20Images%20Under%20Linux.)

   In order to actually boot the system you need to modify /etc/fstab. Change

       	/dev/root               /               nfs     defaults        1 1
       	#/dev/sdc1              /               ext2    defaults        1 1
       	none                    /proc           proc    defaults        0 0
       	none                    /dev/pts        devpts  mode=0622       0 0

   to

       	#/dev/root              /               nfs     defaults        1 1
       	/dev/sda1               /               ext2    defaults        1 1
       	none                    /proc           proc    defaults        0 0
       	none                    /dev/pts        devpts  mode=0622       0 0

   (Note sda1 instead of sdc1.)

To boot Redhat linux from the disk image, use the following command line:

    	gxemul -X -e3max -o "root=/dev/sda1 ro" -d redhat_mips.img vmlinux-2.4.31

If you need to boot into single user mode, change options to `-o "root=/dev/sda1 rw init=/bin/sh"`.

### Mach/PMAX:

Read the following link if you want to know more about Mach in general: http://www-2.cs.cmu.edu/afs/cs/project/mach/public/www/mach.html

NOTE: Mach for DECstation requires some files (called 'startup' and 'emulator') which I haven't been able to find on the web. Without these, Mach will not get very far. These installation instructions are preliminary.

The following steps should let you experiment with running Mach for DECstation in the emulator:

1. Download the pmax binary distribution for Mach 3.0:

       	http://lost-contact.mit.edu/afs/athena/user/d/a/
       	    daveg/Info/Links/Mach/src/release/pmax.tar.Z
       	7263343 bytes, md5 = f9d76c240a6e169921a1df99ad560cc0

2. Extract the Mach kernel:

               tar xfvz pmax.tar.Z pmax_mach/special/mach.boot.MK83.STD+ANY

3. Create an empty disk image:

       	dd if=/dev/zero of=disk.img bs=1 count=512 seek=400000000

4. Load the contents of pmax.tar.Z onto the disk image. This is complicated, and should be described in more detail some time. For now, use your imagination, for example using OpenBSD/pmax:

       	disklabel -E rz1; newfs -O /dev/rz1a;
       	mount /dev/rz1a /mnt; cd /mnt; download pmax.tar.Z using ftp;
       	tar xzvf pmax.tar.Z; mv pmax_mach/* .; rmdir pmax_mach;
       	mkdir mach_servers;
       	cd mach_servers;
       	cp ../etc/mach_init .;
       	cp ../tests/test_service startup;
       	dd if=/dev/zero of=paging_file bs=65536 count=400;
       	cd /; sync; umount /mnt

5. Start the emulator with the following command:

       	gxemul -c 'put w 0x800990e0, 0' -c 'put w 0x80099144, 0' \
       	    -c 'put w 0x8004aae8, 0' -e 3max -X -d disk.img \
       	    pmax_mach/special/mach.boot.MK83.STD+ANY

Earlier versions of GXemul had a configure option to enable better R3000 cache emulation, but since Mach was more or less the only thing that used it, I removed it. Today's version of GXemul can thus not boot mach.boot.MK83.STD+ANY straight off, it has to be patched to skip the cache detection.

The -c commands above patch the kernel to get past the cache detection. Thanks to Artur Bujdoso for these values.

TODO: Better instructions on how to create the old-style UFS disk image.

### DECstation 5000/1xx with raw PROM image:

First, make a dump of the PROM from your own 5000/1xx. The easiest way is to hook up a serial console. The terminal must be able to capture output to a file.

These are approximately the commands that I used:

            >>cnfg                             Show machine configuration

            >>printenv                         Show environment variables

            >>setenv more 0                    This turns off the More messages

            >>e -x 0xbfc00000:0xbfffffff       Dump the PROM data

Remember that DECstations are little endian, so if the dump data looks like this:

            bfc00000:  0x0bf0007e

then the bytes in memory are actually 0x7e, 0x00, 0xf0, and 0x0b.

At 9600 bps, about 10KB can be dumped per minute, so it takes a while. Once enough of the PROM has been dumped, you can press CTRL-C to break out. Then, restore the more environment variable:

            >>setenv more 24

Now, convert the data you just saved (little-endian words -> bytes), and store in a file. Let's call this file DECstation5000_125_promdump.bin.

            $ decprom_dump_txt_to_bin DECstation5000_125_promdump.txt DECstation5000_125_promdump.bin

This binary image can now be used in the emulator:

    	$ gxemul -e 3min -Qx -M128 0xbfc00000:DECstation5000_125_promdump.bin

    	KN02-BA V5.7e
    	?TFL:  3/scc/access (1:Ln1 reg-12: actual=0x00 xpctd=0x01) [KN02-BA]
    	?TFL:  3/scc/io (1:Ln0 tx bfr not empty. status=0X 0) [KN02-BA]
    	...
    	--More--?TFL: 3/scsi/cntl (CUX, cause= 1000002C)
    	>>?
    	 ? [cmd]
    	 boot [[-z #] [-n] #/path [ARG...]]
    	 cat SCRPT
    	 cnfg [#]
    	 d [-bhw] [-S #] RNG VAL
    	 e [-bhwcdoux] [-S #] RNG
    	 erl [-c]
    	 go [ADR]
    	 init [#] [-m] [ARG...]
    	 ls [#]
    	 passwd [-c] [-s]
    	 printenv [EVN]
    	 restart
    	 script SCRPT
    	 setenv EVN STR
    	 sh [-belvS] [SCRPT] [ARG..]
    	 t [-l] #/STR [ARG..]
    	 unsetenv EVN
    	>>cnfg
    	 3: KN02-BA  DEC      V5.7e    TCF0  (128 MB)
    	                                     (enet: 00-00-00-00-00-00)
    	                                     (SCSI = 7)
    	 0: PMAG-BA  DEC      V5.3a    TCF0
    	>>printenv
    	 boot=
    	 testaction=q
    	 haltaction=h
    	 more=24
    	 #=3
    	 console=*
    	 osconsole=3
    	>>

(The goal is to get rid of the test failures indicated by the PROM's tests, but it will take quite some time as there are other things to work on in the emulator as well. Also, making the PROM accept the graphics card and keyboard so that it boots with console on framebuffer would be nice.)

The command line options used are: `-e 3min` for "DECstation 3min" (5000/1xx), `-Q` to supress the emulator's own PROM call emulation, `-M128` for 128MB RAM (because GXemul doesn't correctly emulate memory detection well enough for the PROM to accept, so it will always believe there is 128MB ram anyway), and `-x` is used to launch one xterm per serial port. The `0xbfc00000` in front of the filename tells GXemul that it is a raw binary file which should be loaded at a specific virtual address.