DragonFly On-Line Manual Pages

VMIPS(1) VMIPS Programmer's Manual VMIPS(1)

NAME
vmips - VMIPS R3000-based MIPS simulator (running and customizing)

SYNOPSIS
vmips [-n] [-F FILE] [-o option_string] ... rom_file
vmips --help
vmips --version
vmips --print-config

DESCRIPTION
When you invoke vmips, it loads a ROM file specified on the command
line, initializes and resets the MIPS processor, and begins execution
at the first address of the ROM file, which is normally loaded at
address 0xbfc00000.

OPTIONS
This is what the different command line options mean:

-F FILE
Read options from FILE instead of the .vmipsrc in your home
directory.

-n Do not read the system-wide configuration file, usually called
/usr/local/etc/vmipsrc.

--help
Prints a short summary of VMIPS command line options, and exits
successfully.

--version
Prints a short summary of VMIPS version and copyright information,
and exits successfully.

--print-config
Prints a short summary of VMIPS compile-time configuration
information, and exits successfully.

-o something
Set the option "something" as if "something" were in your .vmipsrc
file. See the "VMIPS options" section of the "Customizing" chapter
for more information on what kind of things can go in your .vmipsrc
file. You can use as many -o options on the command line as your
shell will let you.

rom_file
Use the named file as the ROM file VMIPS should boot. This option
is mandatory.

FILES
VMIPS options
The VMIPS simulator gets runtime options from four different sources,
in this order: first, it checks its compile-time defaults, which are
set by the site administrator in the source file optiontbl.h. Then, the
system-wide configuration file is read, unless you specify the -n
option; usually this file is called /usr/local/etc/vmipsrc, but it may
have been moved by the site administrator or by the maintainers of your
distribution. (This is configurable in the source file options.h, and
by specifying the --prefix and --sysconfdir options to the GNU
configure script when building VMIPS.) Next, it checks the user's own
configuration file, usually the file .vmipsrc in your home directory,
or whatever file you specify using the -F option. Last, it reads the
command line, and gets any options listed there.

Format of the configuration file
The configuration file may contain as many options per line as you
want, provided no single line exceeds 1,024 characters in length.
Whitespace separates options from one another. Single quotes and
backslash are valid in the configuration file. Their meanings are
similar to those found in the Bourne shell: any text within paired
single quotes is uninterpreted, as is any character immediately
following a backslash. A comment is any text starting from a hash mark
to the end of the line, inclusive.

A string or number option named NAME can appear as NAME=VALUE, where
VALUE is the string or number in question. If the number begins with
0x, it will be interpreted as a 32-bit hexadecimal number, and if it
begins with 0, it will be interpreted as octal. Otherwise, it will be
interpreted as a decimal number. Numbers are always unsigned. A Boolean
option named NAME can appear as either NAME (to set it to TRUE) or
noNAME (to set it to FALSE).

Summary of configuration options
The following is a list of the configuration options present in this
version of VMIPS.

haltdumpcpu (type: Boolean)

Controls whether the CPU registers and stack will be dumped
on halt. For the output format, please see the description of the
B<dumpcpu> option, below. The default value is FALSE.

haltdumpcp0 (type: Boolean)

Controls whether the system control coprocessor (CP0) registers
and the contents of the translation lookaside buffer (TLB) will be
dumped on halt. For the output format, please see the description
of the B<dumpcp0> option, below. The default value is FALSE.

excpriomsg (type: Boolean)

Controls whether exception prioritizing messages will
be printed. These messages attempt to explain which of
a number of exceptions caused by the same instruction
will be reported. The default value is FALSE.

excmsg (type: Boolean)

Controls whether every exception will cause a message
to be printed. The message gives the exception code, a
short explanation of the exception code, its priority,
the delay slot state of the virtual CPU, and states
what type of memory access the exception was caused by,
if applicable. Interrupt exceptions are only printed if
B<reportirq> is also set; when they occur, they also have Cause
and Status register information printed. TLB misses will have fault
address and user/kernel mode information printed. The default value is FALSE.

bootmsg (type: Boolean)

Controls whether boot-time and halt-time messages will be printed.
These include ROM image size, self test messages, reset and halt
announcements, and possibly other messages. The default value is TRUE.

instdump (type: Boolean)

Controls whether every instruction executed will be disassembled
and printed. The default value is FALSE. The output is in the following format:

PC=0xbfc00000 [1fc00000] 24000000 li $zero,0

The first column contains the PC (program counter), followed by the
physical translation of that address in brackets. The third column
contains the machine instruction word at that address, followed by the
assembly language corresponding to that word. All of the constants
except for the assembly language are in hexadecimal.

dumpcpu (type: Boolean)

Controls whether the CPU registers and stack will be dumped after every
instruction. The default value is FALSE. The output is in the following format:

Reg Dump: [ PC=bfc00180 LastInstr=0000000d HI=00000000 LO=00000000
DelayState=NORMAL DelayPC=bfc00308 NextEPC=bfc00308
R00=00000000 R01=00000000 R02=00000000 R03=a00c000e R04=0000000a
...
R30=00000000 R31=bfc00308 ]
Stack: 00000000 00000000 00000000 00000000 a2000008 a2000008 ...

(Some values have been omitted for brevity.) Here, PC is the program
counter, LastInstr is the last instruction executed, HI and LO are the
multiplication/division result registers, DelayState and DelayPC are
used in delay slot processing, NextEPC is what the Exception PC would
be if an exception were to occur, and R00 ... R31 are the CPU general
purpose registers. Stack represents the top few words on the stack.
All values are in hexadecimal.

dumpcp0 (type: Boolean)

Controls whether the system control coprocessor (CP0)
registers and the contents of the translation lookaside buffer
(TLB) will be dumped after every instruction. The default value is FALSE.
The output is in the following format:

CP0 Dump Registers: [ R00=00000000 R01=00003200
R02=00000000 R03=00000000 R04=001fca10 R05=00000000
R06=00000000 R07=00000000 R08=7fb7e0aa R09=00000000
R10=00000000 R11=00000000 R12=00485e60 R13=f0002124
R14=bfc00308 R15=0000703b ]
Dump TLB: [
Entry 00: (00000fc000000000) V=00000 A=3f P=00000 ndvg
Entry 01: (00000fc000000000) V=00000 A=3f P=00000 ndvg
Entry 02: (00000fc000000000) V=00000 A=3f P=00000 ndvg
Entry 03: (00000fc000000000) V=00000 A=3f P=00000 ndvg
Entry 04: (00000fc000000000) V=00000 A=3f P=00000 ndvg
Entry 05: (00000fc000000000) V=00000 A=3f P=00000 ndvg
...
Entry 63: (00000fc000000000) V=00000 A=3f P=00000 ndvg
]

Each of the R00 .. R15 are coprocessor zero registers, in hexadecimal.
The Entry 00 .. 63 lines are TLB entries. The 64-bit number in
parentheses is the hexadecimal raw value of the entry. V is the virtual
page number. A is the ASID. P is the physical page number. NDVG are the
Non-cacheable, Dirty, Valid, and Global bits, uppercase if on,
lowercase if off.

haltibe (type: Boolean)

If B<haltibe> is set to TRUE, the virtual machine will halt
after an instruction fetch causes a bus error (exception
code 6, Instruction bus error). This is useful if you
are expecting execution to jump to nonexistent addresses in
memory, and you want it to stop instead of calling the
exception handler. It is important to note that the machine
halts after the exception is processed. The default value is TRUE.

haltbreak (type: Boolean)

If B<haltbreak> is set to TRUE, the virtual machine will halt
when a breakpoint exception is encountered (exception
code 9). This is equivalent to halting when a C<break>
instruction is encountered. It is important to note that the
machine halts after the breakpoint exception is processed. The default value is TRUE.

haltdevice (type: Boolean)

If B<haltdevice> is set to TRUE, the halt device is mapped into
physical memory, otherwise it is not. The default value is TRUE.

instcounts (type: Boolean)

Set B<instcounts> to TRUE if you want to see instruction
counts, a rough estimate of total runtime, and execution
speed in instructions per second when the virtual
machine halts. The default value is FALSE. The output is printed
at the end of the run, and is in the following format:

7337 instructions in 0.0581 seconds (126282.271 instructions per second)

romfile (type: string)

This is the name of the file which will be initially
loaded into memory (at the address given in B<loadaddr>,
typically 0xbfc00000) and executed when the virtual
machine is reset. The default value is "romfile.rom".

loadaddr (type: number)

This is the virtual address where the ROM will be loaded.
Note that the MIPS reset exception vector is always 0xbfc00000
so unless you're doing something incredibly clever you should
plan to have some executable code at that address. Since the
caches and TLB are in an indeterminate state at the time of
reset, the load address must be in uncacheable memory which
is not mapped through the TLB (kernel segment "kseg1"). This
effectively constrains the valid range of load addresses to
between 0xa0000000 and 0xc0000000. The default value is 0xbfc00000.

memsize (type: number)

This variable controls the size of the virtual CPU's "physical"
memory in bytes. The default value is 0x100000.

memdump (type: Boolean)

If B<memdump> is set, then the virtual machine will dump its RAM
into a file, whose name is given by the B<memdumpfile> option,
at the end of the simulation run. The default value is FALSE.

memdumpfile (type: string)

This is the name of the file to which a RAM dump will be
written at the end of the simulation run. The default value is "memdump.bin".

reportirq (type: Boolean)

If B<reportirq> is set, then any change in the interrupt
inputs from a device will be reported on stderr. Also, any
Interrupt exception will be reported, if B<excmsg> is also
set. The default value is FALSE.

spimconsole (type: Boolean)

When set, configure the SPIM-compatible console device.
This is incompatible with B<decserial>. The default value is TRUE.

ttydev (type: string)

This pathname will be used as the device from which reads from the
SPIM-compatible console device's Keyboard 1 will take their data, and
to which writes to Display 1 will send their data. If the OS supports
ttyname(3), that call will be used to guess the default pathname.
If the pathname is the single word B<off>, then the device will be
disconnected.
If the pathname is the single word B<stdout>, then the device
will be connected to standard output, and input will be disabled. The default value is "/dev/tty".

ttydev2 (type: string)

See B<ttydev> option; this one is just like it, but pertains
to Keyboard 2 and Display 2. The default value is "off".

debug (type: Boolean)

If debug is set, then the gdb remote serial protocol backend will
be enabled in the virtual machine. This will cause the machine to
wait for gdb to attach and B<continue> before booting the ROM file.
If debug is not set, then the machine will boot the ROM file
without pausing. The default value is FALSE.

debugport (type: number)

If debugport is set to something nonzero, then the gdb remote
serial protocol backend will use the specified TCP port. The default value is 0.

realtime (type: Boolean)

If B<realtime> is set, then the clock device will cause simulated
time to run at some fraction of real time, determined by the
B<timeratio> option. If realtime is not set, then simulated time
will run at the speed given by the B<clockspeed> option. The default value is FALSE.

timeratio (type: number)

If the B<realtime> option is set, this option gives the
number of times slower than real time at which simulated time will
run. It has no effect if B<realtime> is not set. The default value is 1.

clockspeed (type: number)

If the B<realtime> option is not set, you should set this
option to the average speed in MIPS instructions per second at which
your system runs VMIPS. You can get suitable values from turning
on the B<instcounts> option and running some of your favorite
programs. If you increase the value of B<clockspeed>, time will
appear to pass more slowly for the simulated machine; if you decrease
it, time will pass more quickly. (To be precise, one instruction is
assumed to take 1.0e9/B<clockspeed> nanoseconds.) This option
has no effect if B<realtime> is set. The default value is 250000.

clockintr (type: number)

This option gives the frequency of clock interrupts, in nanoseconds
of simulated time, for the clock device. It does not affect the
DECstation-compatible realtime clock. The default value is 200000000.

clockdeviceirq (type: number)

This option gives the interrupt line to which the clock device is
connected. Values must be a number 2-7 corresponding to an interrupt
line reserved for use by hardware. The default value is 7.

clockdevice (type: Boolean)

If this option is set, then the clock device is enabled. This will
allow MIPS programs to take advantage of a high precision clock. The default value is TRUE.

dbemsg (type: Boolean)

If this option is set, then the physical addresses of accesses
that cause data bus errors (DBE exceptions) will be printed. The default value is FALSE.

decrtc (type: Boolean)

If this option is set, then the DEC RTC device will be
configured. The default value is FALSE.

deccsr (type: Boolean)

If this option is set, then the DEC CSR (Control/Status Register)
will be configured. The default value is FALSE.

decstat (type: Boolean)

If this option is set, then the DEC CHKSYN and ERRADR registers
will be configured. The default value is FALSE.

decserial (type: Boolean)

If this option is set, then the DEC DZ11 serial device
will be configured. This is incompatible with B<spimconsole>. The default value is FALSE.

tracing (type: Boolean)

If this option is set, VMIPS will keep a trace of the last few
instructions executed in memory, and write it out when the machine
halts. This incurs a substantial performance penalty. Use the
B<tracesize> option to set the size of the trace you want. The default value is FALSE.

tracesize (type: number)

Set this option to the maximum number of instructions to keep in the
dynamic instruction trace. This has no effect if B<tracing> is
not set. The default value is 100000.

bigendian (type: Boolean)

If this option is set, then the emulated MIPS CPU will be in
Big-Endian mode. Otherwise, it will be in Little-Endian mode. You
must set it to correspond to the type of binaries that your
assembler and compiler are configured to produce, which is not
necessarily the same as the endianness of the CPU on which you
are running VMIPS. (The default may not be meaningful for your
setup!) The default value is FALSE.

tracestartpc (type: number)

If the tracing option is set, then this is the PC value which will
trigger the start of tracing. Otherwise it has no effect. The default value is 0.

traceendpc (type: number)

If the tracing option is set, then this is the PC value which will
trigger the end of tracing. Otherwise it has no effect. The default value is 0.

mipstoolprefix (type: string)

vmipstool uses this option to locate your MIPS-targetted cross
compilation tools, if you have them installed. If your MIPS GCC
is installed as /opt/mips/bin/mips-elf-gcc, then you should set
this option to "/opt/mips/bin/mips-elf-". vmipstool looks for
the "gcc", "ld", "objcopy" and "objdump" programs starting with
this prefix. This option should be set in your installed
system-wide VMIPS configuration file (vmipsrc) by the "configure"
script; the compiled-in default is designed to cause an error. The default value is "/nonexistent/mips/bin/mipsel-ecoff-".

execname (type: string)

Name of executable to be loaded by automatic kernel loader. This
is an experimental, unfinished feature. The option value
must be the name of a MIPS ECOFF executable file, or 'none'
to disable the option. The executable's headers must specify
load addresses in KSEG0 or KSEG1 (0x80000000 through
0xbfffffff). The default value is "none".

fpu (type: Boolean)

True to enable hooks in the CPU to communicate with a
floating-point unit as coprocessor 1. The floating-point unit
is not implemented; only the hooks in the CPU are. This is an
experimental, unfinished feature. The default value is FALSE.

testdev (type: Boolean)

True to enable a memory-mapped device that is used to test
the memory-mapped device interface. The VMIPS test suite turns
this device on as necessary; you should not normally need
to enable it. The default value is FALSE.

BUGS
For instructions on reporting bugs, see the "Reporting Bugs" appendix
of the Info manual.

SEE ALSO
as(1), ld(1), gdb(1), and the Info entries for vmips, gcc, as, ld,
binutils and gdb.

Important: The information in this man page is an extract from the full
documentation of the VMIPS simulator, and is limited to the meaning of
the command-line options. If you didn't find what you were looking for
here, or you want more information, please refer to the Info file vmips
or the VMIPS Programmer's Manual. Both are made from the Texinfo
source file vmips.texi.

AUTHOR
VMIPS was written by Brian Gaeke.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this document (the "Document"), to deal in the Document without
restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies of
the Document, and to permit persons to whom the Document is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Document.

THE DOCUMENT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
DOCUMENT OR THE USE OR OTHER DEALINGS IN THE DOCUMENT.

vmips 1.5 2014-11-17 VMIPS(1)