|
Important things to keep in mind:
If you are developing a driver for a device which is emulated by GXemul, and your driver does not seem to be working, then the probability of a bug in GXemul's implementation of the device is very much higher than that of a bug in your driver.
The device implementations in GXemul are 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.
The bottom line is that GXemul can be useful as yet another way to test your code during development, but it should not be fully relied on.
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!
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.
$ gxemul -e 3max -d disk0.raw -d disk1.raw -d 5:disk2.raw netbsd-pmax-INSTALLNote: 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:
$ gxemul -e 3max -d image.iso -d disk0.img -d c:second_cdrom.img netbsd-pmax-INSTALLUsually, 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_kernelIf 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_kernelIt is probably possible to use harddisks as well this way, but I would not recommend it.
As an example, starting the emulator with
-d t4:mytape.imgwill 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.
gxemul -XEcats -d nbsd_cats.img netbsd.aout-GENERIC.gz
touch overlay.img overlay.img.map gxemul -XEcats -d 0:nbsd_cats.img -d V0:overlay.img netbsd.aout-GENERIC.gz
rm -f overlay.img overlay.img.map touch overlay.img overlay.img.mapand 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.
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-GENERICThis 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/wd1cDon'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=10000This example created a 10 MB empty file. Then, start the emulator like this:
$ gxemul -XEcats -d nbsd_cats.img -d archive.tar netbsd-GENERICand transfer files by creating an archive directly onto the disk image:
(inside emulated NetBSD/cats) # tar cvf /dev/wd1c filenameswhere filenames are the files or directories to transfer.
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.)
There is some skeleton code for running userland programs as well. This will not emulate any particular machine, but instead try to translate syscalls from e.g. NetBSD/pmax into the host's OS' syscalls. Right now, this is just a proof-of-concept, to show that it could work; there's lots of work left to do to make it actually run useful programs.
$ gxemul -q -u netbsd/pmax pmax_bin_hostname tab.csbnet.se $ gxemul -q -u netbsd/pmax pmax_bin_date Sun Jan 25 02:26:14 GMT 2004 $ gxemul -q -u netbsd/pmax pmax_bin_sleep usage: pmax_bin_sleep seconds $ gxemul -q -u netbsd/pmax pmax_bin_sleep 5 $ gxemul -q -u netbsd/pmax pmax_bin_sync
$ gxemul -q -u ultrix ultrix4_bin_date UNIMPLEMENTED ultrix syscall 54 UNIMPLEMENTED ultrix syscall 62 Mon Feb 9 12:50:59 WET 2004 $ gxemul -q -u ultrix ultrix4_bin_hostname tab.csbnet.se
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: 0x0bf0007ethen 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.binThis binary image can now be used in the emulator:
$ gxemul -e 3min -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: -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 -q to supress debug messages. 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.
Dumping the PROM on a SGI O2:
The general ideas in this section applies to using ROM images from other
machines as well. I have also tried this on an SGI IP32 ("O2"), in addition
to the DECstation.
For the O2, a suitable command to dump the prom memory range is
>> dump -b 0xBFC00000:0xBFC80000Make sure you capture all the output (via serial console) into a file, and then run experiments/sgiprom_to_bin on the captured file.
The photo on the left is from the real machine. The other two are screenshots of the PROM running experimentally in GXemul, using -Y2 framebuffer scaledown.
Note 2007-10-18: Running the O2 PROM image broke somewhere between release 0.3.8 and 0.4.0. (Running with graphics broke between 0.3.7 and 0.3.8.)
Normally during bootup, the IP32 PROM does a Power-On test which makes sure that the caches and other things are working properly. GXemul doesn't emulate all those things well enough for the tests to pass. The experimental screenshots above were taken with cache detection skipped manually.
In other words: don't expect this to work out-of-the-box with GXemul right now. It might work once I've added correct cache emulation.
The command line used to start the emulator, once correct cache emulation has been implemented, would be something like gxemul -XQeo2 0xbfc00000:prom.bin.
The same caution applies when dealing with SGI PROMs as with DECstation PROMs: GXemul doesn't really emulate the hardware, it only "fakes" devices well enough to fool some things, primarily NetBSD, that it is emulating a real machine. ROM code is usually a lot more picky about the details.
The graphics used in the O2 is (as far as I know) undocumented. Combining some traces of info from how Linux/O2 draws to the screen with some reverse-engineering of my own, I've implemented enough of the controller to let the PROM draw rectangles and bitmaps, but not much more. The SCSI controller is not implemented yet either.