mips64emul



mips64emul User Documentation


Contents:


Overview:

mips64emul is a MIPS machine emulator. The goals are to emulate 64-bit and 32-bit MIPS-like CPUs and enough surrounding hardware to fake real machines, capable of running real (unmodified) operating systems (such as NetBSD, Linux, or OpenBSD), and to assist in experimenting with MIPS in general. This is a spare time hobby project, and many things are not implemented yet.

The emulator could be of interest for academic research and experiments, such as learning how to write an OS for a MIPS-based machine, or profiling SMP, memory usage, or system call patterns.

The emulator is written in C, depends on no external libraries (except X11, which is optional), and should compile and run on any Unix-like system. If it doesn't, that is to be considered a bug. No MIPS compiler toolchain is needed if the program you wish to run in the emulator is already in binary form. No ROM images are needed, the emulator will try to emulate things such as PROM calls by itself. However, if you have a ROM image, it might be possible to run it in the emulator.

(MIPS is a registered trademark of MIPS Technologies. This project is not affiliated with MIPS Technologies in any way whatsoever.)


Is mips64emul free software?

Yes, mips64emul is distributed under a free license. The code I have written is released under a 2-clause BSD-style license (or "revised BSD-style" if one wants to use GNU jargon.)

Apart from the code I have written, some files are copied from other sources such as NetBSD, for example header files containing symbolic names of bitfields in device registers. They are also covered by similar licences, but with some additional clauses. Please check individual files if you plan to reuse code from mips64emul.


Which machines does mips64emul emulate?

A few different machine types are emulated. The machine type that is emulated best so far is:

Some other machine types are also emulated, but the degree to which the emulation works for these is generally not very high.

Some more notes about the list above: The machines above all have 64-bit capable CPUs, except early DECstations models. There were upgrades from R3000 to R4000 available for some DECstations, but I think Ultrix was still running in 32-bit mode. Unfortunately, even if most of these machine types have 64-bit CPUs in them (or even 128-bit, the Playstation 2's R5900 CPU is a bit weird), operating systems often run in 32-bit mode on them.

There are other machines that use/used MIPS cpus, for example the Playstation (1) and the Nintendo 64 game systems, but no free OS is ported to those platforms as far as I know, so they might not be too interesting to emulate.

Playstation 2 is among the emulated machine types, but the emulation done by mips64emul is not suitable for playing games. Running Linux and NetBSD is a lot more fun :-)

In addition to specific machine types, a "bare" machine can be emulated. This mode is used when the emulator is started without specifying which machine type to emulate. A bare machine consists of one or more CPUs and a few experimental devices such as:

This mode is useful if you wish to experiment with software for MIPS-like systems, but do not with to target any specific real-world machine type, for example for educational purposes or generic MIPS related experiments.


How to compile/build the emulator:

Uncompress the .tar.gz file, and run
	$ ./configure
	$ make
This should work on any Unix-like system. (If not, then please mail me a bug report.)

The emulator's performance is highly dependant on both runtime settings and on compiler settings, so you might want to experiment with different CC and CFLAGS environment variable values.

A number of different configure options are available:

    --caches    enable cache emulation
    --delays    enable instruction latency/delay emulation
    --mips16    enable MIPS16 instruction support
    --nox11     configure without x11 support

--caches enables emulation of caches (R3000 only, so far). This causes an overall slowdown, so don't enable it unless you need it. Enabling caches does not by itself mean correct cache miss penalties and such (you need both --caches and --delays for that) but it is needed to fool some operating system kernels (eg Mach/pmax) that the cache works like it should.

--delays simulates instruction latencies. Memory accesses can have penalties. When combined with --caches, cache misses cause penalties as well. This causes an overall slowdown, so don't enable it unless you need it.

--mips16 enables MIPS16 instruction support. This doesn't really work yet, as only very few MIPS16 instructions are translated. This causes an overall slowdown, so don't enable it unless you need it.

--nox11 disables X11 support completely. (If the configure script cannot compile a small X11 test program, it will be disabled anyway.) This might improve performance slightly, but makes it impossible to run certain things in the emulator.

(The possible configure options might differ between different releases and snapshots, so this list may be incomplete.)


Which guest OSes are possible to run?

This table sums up the guest OSes that run well enough to be considered "working" in the emulator, that is, they can be installed onto some kind of harddisk image and be interacted with similar to a real machine:

Guest OS:   Emulation mode:
NetBSD/pmax DECstation
OpenBSD/pmax DECstation
Ultrix/RISC DECstation
Sprite DECstation
 
NetBSD 1.6.2/pmax OpenBSD 2.8/pmax
 
Ultrix 4.5 Sprite

It is non-trivial to get a specific operating system or OS kernel to run in the emulator, so don't expect the list above to grow very quickly. Some other emulation modes, most notably SGI emulation modes, work relatively well with NetBSD, but not well enough to support SCSI disk images, and definitely not well enough to run Irix.

There is no guarantee that anything specific will run in the emulator, but NetBSD (or possibly Linux) is a good starting point for someone who wants to experiment. Linux kernels don't usually have ramdisks in them, so until some disk controller device has been implemented, NetBSD is the way to go if you want to reach userland.


How to install NetBSD/pmax in the emulator

To run NetBSD/pmax in the emulator (on an emulated DECstation machine), you first need to install NetBSD onto a disk image. To NetBSD, the disk image looks and acts like a real SCSI disk, but it is just a normal file in the host's filesystem.

You need to do the following:

  1. Compile mips64emul:
    	$ ./configure; make
    
    
  2. Create an empty harddisk image, which will be the root disk that NetBSD installs itself onto:
    	$ dd if=/dev/zero of=netbsddisk.img bs=1 count=512 seek=1900000000
    
    

From this point, there are two separate ways to continue the installation. You can either download a CD-ROM iso image (and let the installation program copy files from the CD-ROM image to the harddisk image), or you can install via ftp. For an installation from a CD-ROM image, follow these steps:

  1. Download a NetBSD CD-ROM iso image: (approx. 75 MB)
    	ftp://ftp.netbsd.org/pub/NetBSD/iso/1.6.2/pmaxcd.iso
    
    
  2. Start the emulator like this:
    	$ ./mips64emul -X -D2 -d netbsddisk.img -d bc:pmaxcd.iso -j netbsd.pmax
    

For an ftp install, substitute steps 3 and 4 above with these:

  1. Download a NetBSD pmax INSTALL kernel (1.3 MB), and gunzip it:
    	ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-1.6.2/pmax/binary/kernel/netbsd-INSTALL.gz
    	MD5 (netbsd-INSTALL.gz) = 14254f73996e8c1abccdcf5e0a0b6521
    
    	$ gunzip netbsd-INSTALL.gz
    
    
  2. Start the emulator like this:
    	$ ./mips64emul -X -D2 -d netbsddisk.img netbsd-INSTALL
    

(If you don't want to use a graphical framebuffer during the install, you can remove -X from the command line, but then make sure you choose 'vt100' when prompted with which terminal type to use, and not 'rcons'.)

Then proceed like you would do if you were installing NetBSD on a real DECstation. Even if the emulator is running on a very fast host system, you should expect the installation to take quite some time. If you are installing from the network, then suitable networking parameters are as follows:

	Which device shall I use? [le0]: le0
	..
	Your DNS domain: mydomain.com
	Your host name: foo
	Your IPv4 number: 10.0.0.1
	IPv4 Netmask [0xff000000]: 0xff000000
	IPv4 gateway: 10.0.0.254
	IPv4 name server: 129.16.1.3       <--- replace this with your actual real-world nameserver

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

	$ ./mips64emul -X -M64 -D2 -d netbsddisk.img

Use startx to start X windows.

If you want to run without the X framebuffer, use this instead:

	$ ./mips64emul -D2 -d netbsddisk.img


How to install OpenBSD/pmax in the emulator

Installing OpenBSD/pmax is a bit harder than installing NetBSD/pmax. You should first read the section above on how to install NetBSD, 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 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. The files are available at this URL:

	ftp://ftp.openbsd.org/pub/OpenBSD/2.8/pmax/

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

  1. Compile mips64emul:
    	$ ./configure; make
    
    
  2. Create an empty harddisk image, which will be the root disk that OpenBSD installs itself onto:
    	$ dd if=/dev/zero of=openbsddisk.img bs=1 count=512 seek=900000000
    
    
  3. Download the entire pmax directory from the ftp server: (approx. 99 MB)
    	$ wget -r ftp://ftp.openbsd.org/pub/OpenBSD/2.8/pmax/
    
    
  4. Execute the following commands:
    	$ mv ftp.openbsd.org/pub/OpenBSD/2.8/pmax/simpleroot28.fs.gz .
    	$ gunzip simpleroot28.fs.gz
    	$ chmod +w simpleroot28.fs		<--- make sure
    
    
  5. 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 that in order to do this.
    	$ mkisofs -o openbsd_pmax_2.8.iso ftp.openbsd.org/pub/OpenBSD/2.8/pmax
    
    
  6. Start the emulator with all three (!) disk images:
    	$ ./mips64emul -D2 -d openbsddisk.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.)

  7. 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:

  8. 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!
    	$ ./mips64emul -D2 -d openbsddisk.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
    

The time required to do a full install (including X11) is about an hour and a half on a 2.8GHz Xeon PC.

NOTE: It is also possible to install via ftp instead of using a CDROM image. This is not much less akward, 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:

	$ ./mips64emul -D2 -X -M64 -d openbsddisk.img -j bsd
When asked for which root device to use, enter rz0.
When asked for which terminal type to use, when logging in as root, enter rcons.
Use startx to start X windows.


How to install Ultrix/RISC in the emulator

The instructions for installing NetBSD/pmax can be used to install Ultrix as well, with a slight modification (the -j argument differs).
  1. Compile mips64emul:
    	$ ./configure; make
    
    
  2. Create an empty harddisk image, which will be the root disk that Ultrix installs itself onto:
    	$ dd if=/dev/zero of=rootdisk.img bs=1 count=512 seek=900000000
    
    
  3. Place your Ultrix installation media in your CDROM drive. (I'm assuming it is called /dev/cd0c here, replace that with the name of your CDROM drive, or the name of a .iso image file.)

  4. Start the emulator like this:
    	$ ./mips64emul -X -D2 -d rootdisk.img -d bc:/dev/cd0c -j vmunix
    
    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 'b' bootflag from the second diskimage argument:
    	$ ./mips64emul -X -D2 -d rootdisk.img -d c:/dev/cd0c -j vmunix
    
    

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

	$ ./mips64emul -X -M64 -D2 -j vmunix -d rootdisk.img

A note for the historically interested out there: OSF/1 for MIPS is 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.


How to run Sprite for DECstation in the emulator

Sprite was a research operating system at the University of Berkeley. Read this if you want to find out more about it: http://www.cs.berkeley.edu/projects/sprite/retrospective.html

The Unix Heritage Society (TUHS, www.tuhs.org) has a copy of a Sprite harddisk image for a DECstation 5000/200:

	ftp://ftp.es.embnet.org/misc/TUHS/sprite/ds5000.bt
	MD5 = ec84eeeb20fe77b758370d5e312e4a5e

Once you have compiled the emulator (./configure; make) and downloaded the harddisk image, you can start the emulator with the following command:

	$ ./mips64emul -X -D2 -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:40:50:60
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

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


How to run Linux (Debian) for DECstation in the emulator

NOTE: This is experimental, and does not really work yet!

Debian has made Linux installation boot kernels for DECstation available for download, containing ramdisks. For a 5000/200 R3000 KN02 (the -D2 model in mips64emul), try this kernel:

	http://http.us.debian.org/debian/dists/testing/main/
	installer-mipsel/current/images/r3k-kn02/boot.img
	MD5 as of 2004-07-14: 9395428ac82fbf7c94f15a1312caaa9a

It is a Linux 2.4.26 kernel which will attempt to install Debian Linux from the network onto a harddisk image.

Once you have compiled mips64emul (./configure; make), you could try running the kernel with graphical framebuffer.

	$ ./mips64emul -X -D2 boot.img

If everything works as it should, you will see the penguin up in the left corner, and some boot messages. The RAMDISK will decompress itself (this takes a while), and then the installation program will start running. A language choice dialog box appears.

This is where the fun ends. This specific Linux kernel has no support for the keyboard controller. :-(

It is possible to get further into the installation, by booting in serial console mode. This is of course not very good looking, but this is the way things are until Linux gets support for the keyboard controller.

	$ ./mips64emul -D2 -o 'console=ttyS03' boot.img

NOTE: As of 2004-07-21, the installation dies with some kind of panic or exception while trying to download/run "parted_devices".


Experiments with other kernels and guest OSes:

The emulator contains code which tries to emulate the workings of MIPS-like CPUs and surrounding hardware found in real machines, but no actual MIPS ROM code or MIPS program code. You will need some form of program to run in the emulator.

You can use pre-compiled kernels (for example NetBSD or Linux), ROM images, or other programs that are in MIPS binary format. A couple of different file formats are supported (ELF, a.out, ECOFF, SREC, raw binaries).

As an example, let's say you want to emulate a Silicon Graphics O2 machine. This machine type is also known as IP32, in the SGI namespace. Let's also say that you want to run NetBSD on this emulated machine. A pre-compiled kernel for NetBSD/sgimips can be found here: http://ftp.sunet.se/pub/NetBSD/NetBSD-1.6.2/sgimips/binary/kernel/netbsd-INSTALL.gz

Once you have downloaded the kernel and gunzip'd it, you can try it out in the emulator like this:

	$ ./mips64emul -G32 -CR5000 -q netbsd-INSTALL
-G signifies that we want SGI emulation, and 32 is the SGI-specific machine type. -q supresses debug messages. If everything works like it should, you should see NetBSD's boot messages...
	$ ./mips64emul -G32 -CR5000 -q netbsd-INSTALL
	zs channel 0 had address 0xbfbd9830
	 [ no symbols available ]
	CPU clock speed = 3.00Mhz
	Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
	    The NetBSD Foundation, Inc.  All rights reserved.
	Copyright (c) 1982, 1986, 1989, 1991, 1993
	    The Regents of the University of California.  All rights reserved.
	
	NetBSD 1.6.2 (RAMDISK) #0: Wed Feb 11 06:38:58 UTC 2004
	    autobuild@tgm.netbsd.org:/autobuild/netbsd-1-6-PATCH002/sgimips/OBJ/autobuild/
	netbsd-1-6-PATCH002/src/sys/arch/sgimips/compile/RAMDISK
	32768 KB memory, 29988 KB free, 0 for ARCS, 1740 KB in 435 buffers
	mainbus0 (root): SGI-IP32 [SGI, 8], 1 processor
	cpu0 at mainbus0: MIPS R5000 CPU (0x2321) Rev. 2.1 with built-in FPU Rev. 1.0
	cpu0: 32KB/32B 2-way set-associative L1 Instruction cache, 48 TLB entries
	cpu0: 32KB/32B 2-way set-associative write-back L1 Data cache
	cpu0: 1024KB/16B direct-mapped write-back L2 Data cache
	crime0 at mainbus0 addr 0x14000000: rev 1.1
	mace0 at mainbus0 addr 0x1f000000
	mace0: isa sts 0
	mace0: isa msk 0
	com0 at mace0 offset 0x390000 intr 4: ns16550a, working fifo
	com0: console
	com1 at mace0 offset 0x398000 intr 4: ns16550a, working fifo
	pckbc0 at mace0 offset 0x320000 intr 5: stub
	lpt0 at mace0 offset 0x380000 intr 4: stub
	mcclock0 at mace0 offset 0x3a0000
	mec0 at mace0 offset 0x280000 intr 3: MAC-110 Ethernet, rev 0
	mec0: station address 00:00:00:00:00:00
	mec0: sorry, this is not a real driver
	macepci0 at mace0 offset 0x80000 intr 7: rev 1
	macepci0: ctrl 0
	pci0 at macepci0 bus 0
	pci0: i/o space, memory space enabled, rd/line, rd/mult, wr/inv ok
	biomask 7f netmask 7f ttymask 7f clockmask ff
	md0: internal 3072 KB image area
	boot device: 
	root on md0a dumps on md0b
	WARNING: clock gained 28 days -- CHECK AND RESET THE DATE!
	root file system type: ffs
	Terminal type? [vt100] _
and after typing vt100 (or just pressing enter), you'll reach NetBSD's install program. You will not be able to install anything though, as the AHC disk controller isn't emulated yet.

To exit the emulator, type CTRL-C. By typing CTRL-B instead, a CTRL-C is sent to the emulated program.

Other operating system kernels can be downloaded from various places. Here are links to some of the kernels that I usually experiment with. (The degree to which these work in the emulator varies a lot.)


Changing the framebuffer resolution

Running the emulator with the -X option turns on the X11 framebuffer. If the framebuffer device for the specific machine mode you are running is implemented well enough, then the framebuffer window will look exactly like the real machine's screen, pixel by pixel.

For many emulated graphics cards in the emulator (or emulation modes), the resolution is fixed. It is possible in some emulation modes, however, to change cards completely. The TURBOchannel cards on some of the emulated DECstation models support this. (The -D2 model is luckily one of these models.) This is not implemented as a command-line option yet, so you have to modify the source code to do this.

The turbochannel_default_gfx_card string defines the name of the graphics card. Look in src/machine.c for this line:

	char *turbochannel_default_gfx_card = "PMAG-BA";

Different cards have different resolution.

Card name: Resolution: Color depth: Comments:
PMAG-AA 1280 x 1024 B/W (perhaps problems with the cursor?)
PMAG-BA 1024 x 864 8-bit color Works fine in OpenBSD, NetBSD, Ultrix, Linux, Sprite
PMAGB-BA 1280 x 1024 8-bit color Works fine in OpenBSD, NetBSD, Linux, Sprite
PMAG-FA 1280 x 1024 8/24-bit Works fine in text-mode only with NetBSD and Ultrix,
(3D acceleration is not emulated)

If the framebuffer window is too large, is is possible to scale it down by adding -Y2 to the command line.


Networking

It is possible to let the guest OS running inside the emulator get access to the Internet. If you are interested in the technical details, and the reasons why networking is implemented in the emulator the way it currently is implemented, you might want to read the networking section in the technical documentation.

The guest OS running inside the emulator uses a private IPv4 address, such as 10.0.0.1, and the emulator acts as a NAT-like gateway/firewall at IPv4 address 10.0.0.254. To the outside world it will seem like it is the host's OS that connects to other machines on the internet, not the guest OS.

NOTE: This is still experimental! As of 2004-07-21, ARP + ICMP + UDP + TCP are emulated well enough to let NetBSD and OpenBSD install via ftp, and use the network for many normal activities, but not everything works yet.


Hello world:

You might want to use the emulator to develop programs on your own, not just run precompiled kernels such as NetBSD. To get started, I'd recommend you do two things:

If the emulator is launched without specifying which machine to emulate, it will emulate only a CPU and very few devices. One of those devices is a console putchar() device, at a fixed address.

	/*  Hello world for mips64emul  */

	#define	PUTCHAR_ADDRESS		0xb0000000

	void printchar(char ch)
	{
		*((volatile unsigned char *) PUTCHAR_ADDRESS) = ch;
	}

	void printstr(char *s)
	{
		while (*s)
			printchar(*s++);
	}

	void f(void)
	{
		printstr("Hello world\n");
		for (;;)
			;
	}
This hello world program is available here as well: hello.c

I'd recommend you build a GCC cross compiler for the mips64-unknown-elf target, and install it. Other compilers might work too, but GCC is good because of its portability. Then try to compile the hello world program:

	$ mips64-unknown-elf-gcc hello.c -mips4 -mabi=64 -c
	$ mips64-unknown-elf-ld -Ttext 0x80030000 -e f hello.o -o hello --oformat=elf64-bigmips
	$ file hello
	hello: ELF 64-bit MSB mips-4 executable, MIPS R3000_BE, version 1 (SYSV), statically linked, not stripped
	$ ./mips64emul -q hello
	Hello world

	$ mips64-unknown-elf-gcc hello.c -c
	$ mips64-unknown-elf-ld -Ttext 0x80030000 -e f hello.o -o hello
	$ file hello
	hello: ELF 32-bit MSB mips-3 executable, MIPS R3000_BE, version 1 (SYSV), statically linked, not stripped
	$ ./mips64emul -q hello
	Hello world
As you can see above, a GCC configured for mips64-unknown-elf can produce both 64-bit and 32-bit binaries.

Hopefully this is enough to get you inspired. :-)


Porting operating systems to MIPS using mips64emul:

Is this a good idea? The answer is yes and no, depending on what you are trying to port to. If you are developing an operating system or operating system kernel of your own, and wish to target MIPS-like systems in general, then the answer might be yes, for experimental purposes.

However, if you think that you can port an operating system to, say, the Silicon Graphics machine mode of mips64emul and hope that your operating system will run on a real SGI machine, then you will most likely fail. mips64emul simply does not emulate things well enough for that to work. Another example would be specific CPU details; if your code depends on, say, R10000 specifics, chances are that mips64emul will not be sufficient.

In many cases, hardware devices in mips64emul are only implemented well enough to fool for example NetBSD that they are working correctly, while in fact they don't work very much at all. Please keep this in mind, if you plan to use mips64emul when porting your code to MIPS.


How to start the emulator with a disk image:

Add -d [prefixes:]diskimagefilename to the command line, where prefixes are one or more single-character options. Run mips64emul with no command line arguments to get a list of possible options.

Here are some examples. If you want to run a NetBSD/pmax kernel on an emulated DECstation machine, you would use a command line such as this:

	$ ./mips64emul -D2 -d pmax_diskimage.fs netbsd-pmax-INSTALL

NOTE: For some emulation modes, such as the DECstation mode, you do not have to specify the name of the kernel, if the disk image is bootable!

It is possible to have more than one disk. For each -d argument, a disk image is added; the first will be SCSI target 0, the second will be target 1, and so on, unless you specify explicitly which ID number the devices should have.

	$ ./mips64emul -D2 -d disk0.raw -d disk1.raw -d 5:disk2.raw netbsd-pmax-INSTALL
Note: In the example above, disk2.raw will get scsi id 5.

If a filename has a 'c' prefix, or ends with ".iso", then it is assumed to be a CDROM device (this can be overridden with a 'd' prefix, to force a read/write disk). For example, the following command would start the emulator with two CDROM images, and one harddisk image:

	$ ./mips64emul -D2 -d image.iso -d disk0.img -d C:second_cdrom.img netbsd-pmax-INSTALL
Usually, the device with the lowest id becomes the boot device. To override this, add a 'b' prefix to one of the devices:
	$ ./mips64emul -D2 -d rootdisk.img -d bc:install-cd.iso name_of_kernel
If you have a physical CD-ROM drive on the host machine, say /dev/cd0c, you can use it as a CD-ROM directly accessible from within the emulator:
	$ ./mips64emul -D2 -d rootdisk.img -d bc:/dev/cd0c name_of_kernel
It is probably possible to use harddisks as well this way, but I would not recommend it.

Using emulated tape drives is a bit more complicated than disks, because a tape can be made up of several "files" with space in between. The solution I have choosen is to have one file in the host's file system space for each tape file. The prefix for using tapes is 't', and the filename given is for the first file on that tape (number zero, implicitly). For files following file nr 0, a dot and the filenumber is appended to the filename.

As an example, starting the emulator with

	-d t4:mytape.img
will cause SCSI id 4 to be a tape device, using the following file number to name translation scheme:

File number: File name in the host's filesystem:
0 mytape.img
1 mytape.img.1
2 mytape.img.2
.. ..

If you already have a number of tape files, which should be placed on the same emulated tape, then you might not want to rename all those files. Use symbolic links instead (ln -s).

There is another advantage to using symbolic links for tape filenames: every time a tape is rewound, it is reopened using the filename given on the command line. By changing what the symbolic name points to, you can "switch tapes" without quiting and restarting the emulator.


How to extract large gzipped disk images:

Unix filesystems usually support large files with "holes". Holes are zero-filled blocks that don't actually exist on disk. This is very practical for emulated disk images, as it is possible to create a very large disk image without using up much space at all.

Using gzip and gunzip on disk images can be very slow, as these files can be multiple gigabytes large, but this is usually neccessary for transfering disk images over the internet. If you receive a gzipped disk image, say disk.img.gz, and run a naive

	$ gunzip disk.img.gz

on it, you will not end up with an optimized file unless gunzip supports that. (In my experiments, it doesn't.) In plain English, if you type ls -l and the filesize is 9 GB, it will actually occupy 9 GB of disk space! This is often unacceptable.

Using a simple tool which only writes blocks that are non-zero, a lot of space can be saved. Compile the program cp_removeblocks in the experiments/ directory, and type:

	$ gunzip -c disk.img.gz | ./cp_removeblocks /dev/stdin disk.img

This will give you a disk.img which looks like it is 9 GB, and works like the real file, but the holes are not written out to the disk. (You can see this by running for example du disk.img to see the physical block count.)


Running userland binaries:

You can run (some) userland programs as well. This will not emulate any particular machine, but instead try to translate syscalls from for example NetBSD/pmax into the host's OS' syscalls. For example, running /bin/hostname or /bin/date and similarly trivial programs from the NetBSD/pmax distribution works:
	$ ./mips64emul -qu1 pmax_bin_hostname
	tab.csbnet.se
	$ ./mips64emul -qu1 pmax_bin_date
	Sun Jan 25 02:26:14 GMT 2004
	$ ./mips64emul -qu1 pmax_bin_sleep
	usage: pmax_bin_sleep seconds
	$ ./mips64emul -qu1 pmax_bin_sleep 5
	$ ./mips64emul -qu1 pmax_bin_sync
There's also an Ultrix4 emulation mode:
	$ ./mips64emul -qu2 ultrix4_bin_date
	UNIMPLEMENTED ultrix syscall 54
	UNIMPLEMENTED ultrix syscall 62
	Mon Feb  9 12:50:59 WET 2004
	$ ./mips64emul -qu2 ultrix4_bin_hostname
	tab.csbnet.se
Userland syscall emulation is still in its beginning stages, so almost nothing works.

Irix userland emulation might also be possible to add.


Using a PROM image from a DECstation:

(The general ideas in this section applies to using ROM images from other machines as well.)

Raw PROM images from real machines can, in a few cases, be used. One case which I've tried is to use a DECstation 5000/125 PROM image. ROM images from other machines might work as well, but ROM code is usually much more sensitive to correctness of the emulator than operating system kernels or userland programs are.

The image first needs to be extracted from the machine. I presume that these PROMs are not legal to redistribute, so you really need to extract the PROM from a physical machine that you own. There are several ways to do this.

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:
	$ ./mips64emul -D3 -Q -M128 -q 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
	>>
(Note: at the moment, this doesn't work. I must have broken something when fixing something else, but this is what it looked like at the time.)

During bootup, the PROM complains a lot about hardware failures. That's because the emulator doesn't emulate the hardware well enough yet.

The command line options used are: -D3 for DECstation model 3 (5000/xxx), -Q to supress the emulator's own PROM call emulation, -M128 for 128MB RAM (because mips64emul doesn't correctly emulate memory detection well enough for the PROM to accept, so it will always believe there is 128MB ram anyway), and -q to supress debug messages. The 0xbfc00000 in front of the filename tells mips64emul that it is a raw binary file which should be loaded at a specific virtual address.


Feedback:

If you have comments, don't hesitate to mail me at md1gavan @mdstud.chalmers.se.