# GXemul: Miscellaneous

Back to the index.

- Emulation accuracy
- Writing operating system code, or developing firmware, using GXemul
- Using GXemul in compiler contruction courses
- How to start the emulator with a disk image
- How to start the emulator with tape images
- How to use disk image overlays
- Transfering files to/from the guest OS
- How to extract large gzipped disk images
- Using a PROM dump from a real machine

### Emulation accuracy:

GXemul is an instruction-level emulator; things that would happen in several steps within a real CPU are not taken into account (e.g. pipe-line stalls or out-of-order execution). Still, instruction-level accuracy seems to be enough to be able to run complete guest operating systems inside the emulator.

The existance of instruction and data caches is "faked" to let operating systems think that they are there, but for all practical purposes, these caches are non-working.

The emulator is in general not timing-accurate, neither at the instruction level nor on any higher level. An attempt is made to let emulated clocks run at the same speed as the host (i.e. an emulated timer running at 100 Hz will interrupt around 100 times per real second), but since the host speed may vary, e.g. because of other running processes, there is no guarantee as to how many instructions will be executed in each of these 100 Hz cycles.

If the host is very slow, the emulated clocks might even lag behind the real-world clock.

### Writing operating system code, or developing firmware, using GXemul:

Is this a good idea? The answer is yes and no, depending on the level of detail you need in your simulations. Important things to keep in mind are:

- Porting code to a specific machine mode, e.g. a Silicon Graphics machine, using GXemul, will not "magically" cause the code to work on a real machine. You still need to test it on real hardware. Sometimes code works in GXemul which doesn't work on real hardware, sometimes it's the other way around.

- GXemul contains bugs, and many things are not yet implemented.

- Very important! I have only implemented devices in GXemul to the degree that NetBSD, OpenBSD, Linux, etc don't complain too much.

  If you are developing a driver for a device which is emulated by GXemul, and your driver does not seem to be working, it could just as well be that the fault is in GXemul's implementation of the device, and not a bug in your driver.

  The device implementations in GXemul are mostly based on the assumption that the emulated OS is already developed and bug-free. They are not primarily intended to be used for development of new device driver code in operating systems, so if you do that, then be prepared for bugs and inconsitencies, and (as mentioned before) make sure to also run your code or real hardware.

- CPU details in GXemul are sometimes wrong. If your code depends on specific details of a particular CPU implementation, chances area that GXemul will not be sufficient. One example is different revisions of ISAs: some instructions which should trigger an exception on a real MIPS processor may execute anyway in GXemul.

- Caches. There is no cache emulation in GXemul right now. Caches for R2000/R3000 are faked well enough to run NetBSD, Ultrix, etc in the DECstation emulation mode, but other than that, cache operations are treated as nops. So for example after you have loaded machine code into RAM in order to execute it, you probably need to flush/clear the instruction cache before branching to the code. A failure to flush the instruction cache would likely result in buggy/random behavior on real hardware whereas the code would still run in GXemul.

The bottom line is that GXemul can be useful as a complement to testing your code on real hardware, but it should not be fully relied on.

### Using GXemul in compiler contruction courses:

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

Your compiler needs to output real assembly language code, which the assembler (e.g. 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 (e.g. SPIM).

However, GXemul does not simulate out-of-order execution, penalties related to instruction scheduling, or load-delays, so it cannot be used to evaluate optimizing compilers that take advantage of such processor features. GXemul keeps track of the number of instructions executed, but that's it.

### 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 `gxemul -h` 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:

    	$ gxemul -e 3max -d pmax_diskimage.fs netbsd-pmax-INSTALL

NOTE: For some emulation modes, such as the DECstation mode, you do not actually have to specify the name of the kernel, if the disk image is bootable! Bootblocks are then read from the disk and executed, as on a real machine.

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

    	$ gxemul -e 3max -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.

(*) = One exception is that in the LUNA88K machine, if no id is specified, the first disk image gets id 6, the second id 5 and so on.

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:

    	$ gxemul -e 3max -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:

    	$ gxemul -e 3max -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:

    	$ gxemul -e 3max -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.

### How to start the emulator with tape images:

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.

Note: Tape support is most likely very buggy, because it has not been tested much, and has probably also suffered from bit-rot by now.

### How to use disk image overlays:

This is most likely best understood by an example:

- Install e.g. NetBSD/cats. You will end up with a disk image called `nbsd_cats.img`.

- Running the following command will boot straight from the disk image, with no overlay images:

      	gxemul -XEcats -d nbsd_cats.img netbsd.aout-GENERIC.gz

- You may now create an overlay file, a corresponding map file, and start the emulator with the overlay image connected to the same (explicit) ID as the base disk image:

      	touch overlay.img overlay.img.map
      	gxemul -XEcats -d 0:nbsd_cats.img -d V0:overlay.img netbsd.aout-GENERIC.gz

- Any changes to the filesystem you perform when using the overlay will only be written to that overlay. For example, to perform a "roll back", you can do the following:

      	rm -f overlay.img overlay.img.map
      	touch overlay.img overlay.img.map

  and then simply start the emulator again, with the newly created overlay image.

It is also possible to add multiple overlays. In that case, writes always go the the last added overlay.

GXemul uses Unix' way of supporting files with "holes", so even if `ls -l overlay.img` says that the overlay is several gigabytes large, `du overlay.img` should reveal that only the blocks that have actually been written to have been stored in the overlay, e.g.:

    	$ ls -l
    	..
    	-rw-r--r--  1 debug  wheel  3072319488 Mar 24 11:59 nbsd_cats.img
    	-rw-r--r--  1 debug  wheel     2465354 Mar 24 11:44 netbsd.aout-GENERIC.gz
    	-rw-r--r--  1 debug  wheel  2930841600 Mar 24 14:02 overlay.img
    	-rw-r--r--  1 debug  wheel      715538 Mar 24 14:02 overlay.img.map
    	$ du overlay.img
    	864     overlay.img

The .map file is simply a raw bitmap telling which blocks of the overlay file that are in use.

As a short-hand for creating overlay files, running the emulator once with those overlay files, and then immediately removing the overlay files, the disk image prefix R (uppercase) can be used instead. In other words, instead of typing something like:

    touch overlay.img overlay.img.map
    gxemul -e ..... -d disk.img -d V0:overlay.img
    rm overlay.img overlay.img.map

one would type:

    gxemul -e ..... -d R:disk.img

### Transfering files to/from the guest OS:

If the emulated machine supports networking (see this section for more info), then the easiest way to transfer files is probably to use FTP or similar methods.

There is another way of transfering files which works for any kind of emulated machine which supports disks (either SCSI or IDE). Any file can be supplied as a disk image. For example, consider the following:

    	$ gxemul -XEcats -d nbsd_cats.img -d archive.tar.gz netbsd-GENERIC

This will start NetBSD/cats with `nbsd_cats.img` as IDE master on controller 0 (wd0), and `archive.tar.gz` as IDE slave on controller 0 (wd1). From inside NetBSD, it is now possible to extract the files using the following command:

    	(inside emulated NetBSD/cats)
    	# tar zxvf /dev/wd1c

Don't worry if NetBSD complains about lack of disklabel; it doesn't matter. On some machines, NetBSD uses `wd1d` instead of `wd1c` for the entire disk. There is also a minor problem: reading the end of the disk image. If you experience problems untaring archives like this, then pad out the archive first with some zeroes.

Transfering files out from the emulated operating system to the host can be done the same way. First, prepare an empty archive file:

    	$ dd if=/dev/zero of=newarchive.tar bs=1024 count=1 seek=10000

This example created a 10 MB empty file. Then, start the emulator like this:

    	$ gxemul -XEcats -d nbsd_cats.img -d archive.tar netbsd-GENERIC

and transfer files by creating an archive directly onto the disk image:

    	(inside emulated NetBSD/cats)
    	# tar cvf /dev/wd1c filenames

where filenames are the files or directories to transfer.

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

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

In GXemul, a simple PROM/BIOS implementation is usually faked, so that guest operating systems can start up. For example, if the PROM has services which the guest OS can call, which tell how much memory there is in a machine, or to print simple characters to a terminal, those can be implemented in software without having to run the original PROM image from a physical machine.

Raw PROM images from real machines can, in a few cases, be used in the emulator. A few things are worth keeping in mind, though:

1. 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.
   - In particular, for proprietary hardware, a guest OS such as NetBSD or Linux may only use the parts of the hardware that have been reverse-engineered, whereas PROM firmware code will access other devices, or more device registers, and assume that the hardware works to a larger degree than NetBSD or Linux needs.
2. If you are running a modified ROM/firmware image in GXemul, in order to see that it boots up and works, it will not automatically mean that it will behave the same way when you put it back in real hardware again.
3. Most of the emulation modes of GXemul have been designed to run without the need for a PROM image, for example the load order (or mechanism) used to boot from a CDROM or SCSI disk, so running with actual machine firmware might not really be supported, more than for simple experiments.

Useful command line options:

- `-Q` disables the software/builtin PROM emulation in GXemul.
- `-T` stops the emulation in case the PROM tries to access a memory range which does not exist. (Default behavior is to ignore writes and return 0 on reads.)
- `-K` attempts to drop you into the debugger prompt, instead of quitting, on some errors.
- `-v` enables verbose output. In particular, it shows the output of any `debug()` calls in the code.

#### Preparation:

The ROM image first needs to be extracted from your real machine. There are several ways to do this, and it depends on your available hardware, the specifics of the machine in question, and how much time you have.

- Hook up a serial console and dump using the PROM's own dump command. On machines for which you need to use a serial console to access anyway, this is probably the easiest. The syntax for the dump commands vary between machines, and you often need to do some kind of post-processing to convert the dumped data (e.g. in some kind of hex dump text format) to a raw binary. Alternatively, you may be able to run a small program on the machine, which dumps suitable memory ranges to a serial port. There are some examples in the `experiments/` subdirectory which may help with these tasks.
- 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, as far as I have understood, but a modified NetBSD kernel could probably allow this.
- Dump the ROM contents "visually", by showing the individual bits on a display. Then use e.g. a webcam to record the images, and write a program which decodes them into plain data. This can be used for example on the Dreamcast, if you do not want to build a serial cable, and do not have a PROM chip reader.