mips64emul documentation: Misc.

Back to the index

## Misc.

- Configuration file syntax
- Networking
- Porting operating systems to MIPS using mips64emul
- Using mips64emul in compiler contruction courses
- How to start the emulator with a disk image
- How to extract large gzipped disk images
- Running userland binaries
- Using a PROM dump from a real machine

### Configuration file syntax:

Configuration files are simple text files. I don't have time to write down a formal syntax right now, so I hope that conveying the syntax through an example is good enough:

    !!mips64emul     <-- configuration files must start like this
    !
    !  This is an example configuration file for mips64emul.
    !  Anything following an exclamation mark (and also the exclamation
    !  mark itself) is ignored.
    !
    !  Each configuration file should contain one emul entry. Almost
    !  everything else is optional.

    emul(
        name("my test emul")	 !  Optional name of this emulation

        !  This creates a network (ethernet):
        net(
    	ipv4net("10.2.0.0")  !  The default is 10.0.0.0/8, but
    	ipv4len(16)          !  it can be overridden like this.
        )

        !  This creates a machine:
        machine(
    	name("My test machine")
    	type("dec")		!  This is actually not optional
    	subtype("5000/200")

    	cpu(R3000)      !  Normally set implicitly to a reasonable
    			!  value, depending on type and subtype

    	! ncpus(4)
    	! use_random_bootstrap_cpu(yes)

    	memory(128)	!  128 MB memory. This overrides
    			!  the default amount of memory for
    			!  this machine type.

    	! random_mem_contents(yes)

    	! prom_emulation(no)

    	! byte_order(big)    !  Normally set implicitly (because
    			     !  of type and subtype, or decided
    			     !  from the file loaded with load

    	load("netbsd-INSTALL")
    	bootname("netbsd")
    	bootarg("-a")

    	! n_gfx_cards(2)         !  for DECstation dual/tripple-head
    	! emulated_hz(10000000)  !  for fixing the emulated clock speed

    	! add_x11_display("otherbox:0")  !  for dual/tripple-head etc
    	! add_x11_display("thisbox:0")

    	! force_netboot(yes)
    	! start_paused(yes)

    	disk("nbsd.img")
    	disk("6c:cdrom.iso")

    	use_x11(yes)
    	x11_scaledown(2)

    	bintrans(enable)
    	! bintrans_size(24)

    	! slow_serial_interrupts_hack_for_linux(yes)

    	! debugger_on_badaddr(yes)

    	{
    	    Long comments spanning multiple lines should be surrounded
    	    with tuborg parentheses.

    	    {  Long comments can be nested.  }

    	... TODO ...
    	  -i        display each instruction as it is executed
    	  -J        disable some speed tricks
    	  -m nr     run at most nr instructions (on any cpu)
    	  -N        display nr of instructions/second average, at regular intervals
    	  -p pc     add a breakpoint (remember to use the '0x' prefix for hex!)
    	  -r        register dumps before every instruction
    	  -t        show function trace tree
    	  -y x      set max_random_cycles_per_chunk to x (experimental)
    	  -u ...    userland

    	}

        )

        !  Multiple machine are allowed.
        machine(
    	name("another machine")
    	type("hpcmips")
    	subtype("be300")

    	...
        )
    )

Starting the emulator with a configuration file is as simple as

    	$ ./mips64emul @myconfig

if myconfig is the name of the configuration file.

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

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

### Using mips64emul in compiler contruction courses:

If you are learning how to write a compiler, and wish to target a realistic target platform, then MIPS (as emulated by mips64emul) might be a suitable choice.

- (+) Your compiler needs to output real assembly language code, which the assembler (eg gas, the GNU assembler) can then compile into object format, and then you need to link this into an executable image. This is much closer to how things work in real life than running assembly language listings in a simulator (eg SPIM).

- (-) mips64emul does not simulate out-of-order execution, penalties related to instruction scheduling, or load-delays, so it cannot be used to create optimizing compilers that take advantage of such processor features.

### 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 necessary 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. Right now, this is just a proof-of-concept, to show that it would work; there's lots of work left to do to make it actually run useful programs (for example dynamically linked programs).

- NetBSD/pmax:
  Running /bin/hostname or /bin/date and similarly trivial programs from the NetBSD/pmax distribution works:

      	$ ./mips64emul -q -u netbsd/pmax pmax_bin_hostname
      	tab.csbnet.se
      	$ ./mips64emul -q -u netbsd/pmax pmax_bin_date
      	Sun Jan 25 02:26:14 GMT 2004
      	$ ./mips64emul -q -u netbsd/pmax pmax_bin_sleep
      	usage: pmax_bin_sleep seconds
      	$ ./mips64emul -q -u netbsd/pmax pmax_bin_sleep 5
      	$ ./mips64emul -q -u netbsd/pmax pmax_bin_sync

- Ultrix:
  At least /bin/date and /bin/hostname work:

      	$ ./mips64emul -q -u ultrix ultrix4_bin_date
      	UNIMPLEMENTED ultrix syscall 54
      	UNIMPLEMENTED ultrix syscall 62
      	Mon Feb  9 12:50:59 WET 2004
      	$ ./mips64emul -q -u ultrix ultrix4_bin_hostname
      	tab.csbnet.se

- NetBSD/powerpc:
  /bin/sync from NetBSD/macppc works, but probably not much else.

      	$ ./mips64emul -v -u netbsd/powerpc netbsd-1.6.2-macppc-bin-sync
      	...
      	[ sync() ]
      	[ exit(0) ]
      	cpu_run_deinit(): All CPUs halted.

- Linux/PPC64:
  The 64-bit Hello World assembly language example on IBM's developerWorks pages runs:

      	$ ppc64-unknown-linux-as hello-ppc64.s -o hello-ppc64.o
      	$ ppc64-unknown-linux-ld hello-ppc64.o -o hello-ppc64
      	$ ./mips64emul -q -u linux/ppc64 hello-ppc64
      	Hello, world!

### Using a PROM dump from a real machine:

Raw PROM images from real machines can, in a few cases, be used in the emulator. ROM code is usually much more sensitive to correctness of the emulator than operating system kernels or userland programs are, so don't expect any PROM image to just magically work.

#### Dumping the PROM on a DECstation 5000/125:

The image first needs to be extracted from the machine. There are several ways to do this.

- Use hardware to read the PROM chip(s) directly. Not easy if you don't have such a hardware reader.
- Copy the PROM memory range into a file, from a running operating system. You need a running OS, and it must have access to the PROM memory range. NetBSD, for example, doesn't allow that from userland.
- Hook up a serial console and dump using the PROM's own dump command.

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/1xx), -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.

#### Dumping the PROM on a SGI O2:

The general ideas in this section applies to using ROM images from other machines as well. Besides DECstation, I've also tried this on an SGI IP32 ("O2").

For the O2, a suitable command to dump the prom memory range is

    	>> dump -b 0xBFC00000:0xBFC80000

Make sure you capture all the output (via serial console) into a file, and then run experiments/sgiprom_to_bin on the captured file.

(2005-01-16: The emulator doesn't really emulate the IP32 well enough to actually run the PROM image without using special hacks, but it might do so some time in the future.)