Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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.

COPYRIGHT
       Copyright (c) 2001, 2002, 2004, 2009, 2014 Brian	R. 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.1			  2018-08-20			      VMIPS(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | FILES | BUGS | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=vmips&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help