MIPS64EMUL(1)

NAME
mips64emul - a MIPS machine emulator

SYNOPSIS
mips64emul [machine, other, and general options] [file ...]
mips64emul [general options] [@configfile ...]
mips64emul [userland, other, and general options] file [args ...]

DESCRIPTION
mips64emul is a MIPS machine emulator, which can be used in experiments involving MIPS binary code. Several emulation modes are available. For some emulation modes, processors and surrounding hardware components are emulated well enough to let unmodified operating systems run as if they were running on a real machine.

There are three ways to invoke the emulator. When emulating a complete machine, settings can be entered directly on the command line, or they can be read from a configuration file. When emulating a userland environment (syscall-only emulation, not emulating complete machines), then the program name and its argument should be given on the command line.

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 MIPS binary file (an ELF, a.out, 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.

Apart from the name of a MIPS binary, it is also necessary to select which specific emulation mode to use. For example, a MIPS-based machine from DEC (a DECstation) is very different from a MIPS-based machine from SGI. Use mips64emul -H to get a list of available emulation modes.

(There is an exception to the normal invocation usage mentioned above; if you want to use the DECstation emulation mode, and 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.)

Machine selection options:

-E t
    Try to emulate machine type t. (Use -H to get a list of types.)

-e st
    Try to emulate machine subtype st. Use this together with -E. (This option is not always needed, if a machine type has no subtypes.)

Other options:

-b  Enable dynamic binary translation.

-C x
    Try to emulate a specific CPU type, x. This overrides the default CPU type for the machine being emulated. (Use -H to get a list of available CPU types.)

-d name
    Add name as a disk image. By adding one or more modifier characters and then a colon (":") as a prefix to name, you can modify the disk image's behaviour. Available modifiers are:

    b   Specifies that this is a boot device.

    c   CD-ROM (instead of a normal SCSI DISK).

    d   SCSI DISK (this is the default).

    r   Read-only (don't allow changes to be written to the file).

    t   SCSI tape.

    0-7 Force a specific SCSI ID number.

    Filenames ending with ".iso" are assumed to be CDROM images, all others are assumed to be normal SCSI disks.

-I x
    Emulate clock interrupts at x Hz. (This affects emulated clock devices only, not actual runtime speed. This disables automatic clock adjustments, which is otherwise turned on.) (This option is probably only valid for DECstation emulation.)

-i  Display each instruction as it is being executed.

-J  Disable some speed tricks.

-j n
    Set the name of the kernel to n, for example "bsd" for OpenBSD/pmax, or "vmunix" for Ultrix.

-M m
    Emulate m MBs of physical RAM. This overrides the default amount of RAM for the selected machine type.

-m nr
    Run at most nr instructions (on any cpu).

-N  Display nr of instructions/second average, at regular intervals.

-n nr
    Set nr of CPUs (for SMP experiments).

-O  Force a "netboot" (tftp instead of disk), even when a disk image is present (for DECstation, SGI, and ARC emulation).

-o arg
    Set the boot argument (for DEC, ARC, or SGI emulation). Default arg for DEC is '-a', for ARC '-aN'.

-p pc
    Add a breakpoint (remember to use the '0x' prefix for hex).

-Q  Disable the built-in PROM emulation. This is useful for running raw ROM images from real machines.

-R  Use a random bootstrap cpu, instead of CPU nr 0. (For SMP experiments.)

-r  Dump register contents for every executed instruction.

-S  Initialize the emulated RAM to random data, instead of zeroes.

-T  Enter the single-step debugger on unimplemented memory accesses.

-t  Show a trace tree of all function calls being made.

-U  Enable slow_serial_interrupts_hack_for_linux.

-X  Use X11.

-Y n
    Scale down framebuffer windows by n x n times.

-y x
    Set max_random_cycles_per_chunk to x (experimental).

-Z n
    Set the number of graphics cards, for emulating a dual-head or tripple-head environment. (Only for DECstation emulation so far.)

-z disp
    Add disp as an X11 display to use for framebuffers.

Userland options:

-u emul-mode
    Userland-only (syscall) emulation. (Use -H to get a list of available emulation modes.) Some (but not all) of the options listed under Other options above can also be used with userland emulation.

General options:

-H  Display a list of available CPU types, machine types, and userland emulation modes.

-h  Display a list of all available command line options.

-K  Force the single-step debugger to be entered at the end of a simulation.

-q  Quiet mode; this suppresses startup messages.

-s  Show opcode usage statistics after the simulation.

-V  Start up in the single-step debugger, paused.

-v  Verbose debug messages.

Configuration file startup:

@ configfile
    Start an emulation based on the contents of configfile.

For more information, please read the documentation in the doc/ subdirectory of the mips64emul distribution.

EXAMPLES
The following command will start NetBSD/pmax on an emulated DECstation 5000/200 (3MAX), with dynamic binary translation enabled:

    mips64emul -E dec -e 3max -b -d netbsddisk.img

netbsddisk.img should be a raw disk image containing a NetBSD/pmax filesystem.

The following command will start an emulation session based on settings in the configuration file "mysession". The -v option tells mips64emul to be verbose.

    mips64emul -v @mysession

If you have compiled the small Hello World program mentioned in the mips64emul documentation, the following command will start up an emulated test machine in "paused" mode:

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

Please read the documentation for more details.

AUTHOR
Anders Gavare <anders@gavare.se>

See http://gavare.se/mips64emul/ for more information.