GXEMUL(1) | General Commands Manual | GXEMUL(1) |
gxemul
— an
experimental framework for full-system machine emulation
gxemul |
[machine, other, and general options] [file ...] |
gxemul |
[general options] @configfile |
gxemul |
-H |
gxemul
is a framework for full-system
computer architecture emulation. Several processor architectures and machine
types have been implemented. It is working well enough to allow unmodified
"guest" operating systems (e.g. NetBSD) to run inside the
emulator, as if they were running on real hardware.
The emulator emulates (networks of) real machines. The machines may consist of ARM, MIPS, Motorola 88K, PowerPC, and SuperH processors, and various surrounding hardware components such as framebuffers, busses, interrupt controllers, ethernet controllers, disk controllers, and serial port controllers.
Please read the HTML documentation for more details on how to run specific guest operating systems in the emulator.
The emulator can be invoked in the following ways:
1. When emulating a complete machine, configuration options can be supplied directly on the command line.
2. Options can be read from a configuration file.
The easiest way to use the emulator is to supply settings directly on the command line.
The most important thing you need to supply is the file argument. This is the name of a binary file (an ELF, a.out, COFF/ECOFF, SREC, or a raw binary image) which you wish to run in the emulator. This file might be an operating system kernel, or perhaps a ROM image file. If more than one filename is supplied, all files are loaded into memory, and the entry point (if available) is taken from the last file.
Apart from the name of a binary file, you must also use the
-E
and/or -e
options to
select which emulation mode to use. This is necessary because the emulator
cannot in general deduce this from the file being executed. For example, a
MIPS-based machine from DEC (a DECstation) is very different from a
MIPS-based machine from SGI. Use gxemul
-H
to get a list of available emulation modes.
There are three exceptions to the normal invocation usage mentioned above.
1. For DECstation emulation, if you have a bootable DECstation
harddisk or CDROM image, then just supplying the diskimage via the
-d
option is sufficient. The filename of the kernel
can then be skipped, as the emulator runs the bootblocks from the diskimage
directly and doesn't need the kernel as a separate file.
2. If you supply an ISO9660 CDROM disk image, then using the
-j
option to indicate a file on the CDROM filesystem
to load is sufficient; no additional kernel filename needs to be supplied on
the command line.
3. For Dreamcast emulation, when booting e.g. a NetBSD/dreamcast CDROM image, it is enough to supply the disk image (with the correct ISO partition start offset). Bootblocks will be read directly from the CDROM image, and there is no need to supply the name of an external kernel on the command line.
Gzipped kernels are automatically unzipped, by calling the
external gunzip program, both when specifying a gzipped file directly on the
command line and when loading such a file using the
-j
option.
Machine selection options:
-E
t-e
option uniquely selects a
machine. (Use -H
to get a list of types.)-e
st-E
. (This option is not always needed, if a
machine type has no subtypes.)Other options:
-C
x-H
to get a list of available CPU types.)-d
[modifiers:]filenameFor SCSI devices, the ID number is the SCSI ID. For IDE harddisks, the ID number has the following meaning:
Unless otherwise specified, filenames ending with ".iso" or ".cdr" are assumed to be CDROM images. Most others are assumed to be disks. Depending on which machine is being emulated, the default for disks can be either SCSI or IDE. Some disk images that are very small are assumed to be floppy disks. (If you are not happy with the way a disk image is detected, then you need to use explicit prefixes to force a specific type.)
For floppies, the gH;S; prefix is ignored. Instead, the number of heads and cylinders are assumed to be 2 and 80, respectively, and the number of sectors per track is calculated automatically. (This works for 720KB, 1.2MB, 1.44MB, and 2.88MB floppies.)
-I
hzSetting the frequency to zero disables automatic synchronization of emulated time vs real world time, and the count/compare system runs at a fixed rate.
-i
-J
-j
n-L
tapdev-M
m-N
-n
nrNote 1: The emulator allocates quite a lot of virtual memory for per-CPU translation tables. On 64-bit hosts, this is normally not a problem. On 32-bit hosts, this can use up all available virtual userspace memory. The solution is to either run the emulator on a 64-bit host, or limit the number of emulated CPUs to a reasonably low number.
Note 2: SMP simulation is not working very well yet; multiple processors are simulated, but synchronization between the processors does not map very well to how real-world SMP systems work.
-O
-o
arg-p
pc-Q
-R
-n
option.)-r
-S
-s
flags:filenameThe flags should include one or more of the following type specifiers:
The flags may also include the following optional modifiers:
Statistics gathering can be enabled/disabled at runtime by using the "statistics_enabled = yes" and "statistics_enabled = no" debugger commands.
When gathering instruction statistics using the
-s
option, instruction combinations are always
disabled (i.e. an implicit -J
flag is added to
the command line).
-T
-t
-X
-Y
n-Z
n-z
dispGeneral options:
-A
-c
cmd-V
option, and entering the commands
manually.-D
-G
-H
gxemul
distribution for details on which modes
that actually work.)-h
-k
n-K
-q
-V
-q
is ignored. This option also sets
-K.
-v
-x
-X
nor -x
is used,
then all output is confined to the terminal that
gxemul
started in. The default terminal to use is
'xterm', but this can be overriden by the XTERM environment variable.Configuration file startup:
The following command will start NetBSD/pmax on an emulated DECstation 5000/200 (3MAX):
gxemul -e 3max -d
nbsd_pmax.img
nbsd_pmax.img should be a raw disk image containing a bootable NetBSD/pmax filesystem.
The following command will start an emulation session based on settings in the configuration file "mysession". The -v option tells gxemul to be verbose.
gxemul -v @mysession
If you have compiled the small Hello World program mentioned in
the gxemul
documentation, the following command will
start up an emulated test machine in "paused" mode:
gxemul -E testmips -V
hello_mips
Paused mode means that you enter the interactive single-step debugger directly at startup, instead of launching the Hello World program.
The paused mode is also what should be used when running "unknown" files for the first time in the emulator. E.g. if you have a binary which you think is some kind of MIPS ROM image, then you can try the following:
gxemul -vv -E baremips -V
0xbfc00000:image.raw
You can then use the single-stepping functionality of the built-in debugger to run the code in the ROM image, to see how it behaves. Based on that, you can deduce what machine type it was actually from (the baremips machine is not a real machine), and perhaps try again with another emulation mode.
In general, however, real ROM images require much more emulation detail than GXemul provides, so they can usually not run.
There are many bugs. Some of the known bugs are mentioned in the
TODO file in the gxemul
source distribution, some
are marked as TODO in the source code itself.
gxemul
is in general not cycle-accurate;
it does not simulate individual pipe-line stages or penalties caused by
branch-prediction misses or cache misses, so it cannot be used for accurate
simulation of any actual real-world processor.
gxemul
is in general not timing-accurate.
Many emulation modes try to make the guest operating system's clock run at
the same speed as the host clock. However, the number of instructions
executed per clock tick can obviously vary, depending on the current CPU
load on the host.
gxemul
is in general not guaranteed to be
secure; when used as a virtual machine to run untrusted code in the form of
a guest OS, the untrusted code may be able to crash the emulator, or due to
bugs, take over the host.
GXemul is Copyright (C) 2003-2021 Anders Gavare <gavare@gmail.com>
See http://gavare.se/gxemul/ for more information. For other Copyright messages, see the corresponding parts of the source code and/or documentation.
MARCH 2021 | Debian |