The purpose of this document is to provide a comprehensive reference manual for MSIM version 1.3.8.5.
© 2007 Viliam Holub (holub
© 2010 Martin Decky (decky
2016-02-29
addquitmdidddmbdbreakbdbrstatechocontinuestepsetunsethelpDTRCDTRODINTDRVDHLTDVALMSIM is a light-weight computer simulator based on MIPS R4000. It is used for education and research purposes, mainly to teach the construction and implementation of operating systems. MSIM is distributed with source code under the GNU GPL license to make possible modifications for users and works on most POSIX-compliance environments (mainly GNU/Linux, Mac OS X, but can be also compiled in Cygwin or MinGW in Windows).
MSIM provides following features (along others):
MSIM does not aim to be a speed-optimized real hardware simulator, but rather a fully deterministic simulator useful for kernel debugging. There are several other projects which aim speed-optimized simulation (e.g. GXemul), but they are more complex to use.
Other hardware devices are designed in a very straightforward way to emphatize basic principles of operation, but do not confuse the programmers with historical heritage and complex issues.
There are several modes the MSIM runs in. Typically, the user will
simply configure the system and execute the code. For debugging purposes,
the simulation can be switched into
MSIM is programmed in the C programming language. It is not specifically
designed to run on any architecture of the host computer and is thus very portable.
The design of the simulator is also modular and extensible. A simulator core
provides a common clock for all modules. The modules (or
We use these typographic conventions throughout the text:
| Type | Example |
|---|---|
| Shell command line | $ command |
| MSIM command line | [msim] command |
| Source code |
1 /* This is just a comment. */ 2 3 #define MACRO something 4 5 int fnc(int variable) 6 { 7 if (variable > 0) 8 return 1; 9 10 return fnc2(MACRO); 11 } |
| Inline code | An example of code inside the text. |
| Emphasized inline code | An example of an emphasized code inside the text. |
| Keyboard keys | When you should press the Enter key, Enter is used. |
A POSIX compliant environment is required for MSIM to be compiled and executed. It has been succesfully tested on GNU/Linux in various distributions (Debian, Feroda, Gentoo) and platforms (x86, AMD64, UltraSPARC, PowerPC). MSIM also runs in Solaris, OpenSolaris, FreeBSD and Mac OS X.
Under Windows MSIM can be compiled and executed in Cygwin or using MinGW/MSYS as a natine Win32 console application (although the functionality might be somehow limited).
A standard toolchain of consisting of a C compiler (preferably GCC) and usual utilities (Bash, GNU Make) are the prerequisites for building MSIM. The GNU Readline library is also required.
The current version of MSIM can be downloaded from the
project site. It is
distributed via a source tarball. Untar the distribution package
and change your current directory to the directory containing a script
called configure.
A usual way of downloading and extracting the source package package is:
$ wget http://d3s.mff.cuni.cz/~holub/sw/msim/msim-1.3.8.5.tar.bz2Enter ... $ tar -xjf msim-1.3.8.5.tar.bz2Enter $ cd msim-1.3.8.5Enter
To configure the package for compilation use the configure
scripts. The script should detect all important compilation options
and check for prerequisites.
Specific options to the configure script can be used,
e.g. --prefix= to set the installation prefix.
$ ./configure --prefix=/opt
After a succesful execution of configure just run
make to compile the sources. No special arguments
are usually necessary.
$ make
If the compilation is succesful, you can use the following command to install the binary and sumplementary files into the installation prefix. You will probably need root privileges to install MSIM into system-wide prefix.
# make install
This section briefly describes the command line parameters of MSIM. Most
of the parameters can be combined. For example a typical usage is to use
the combination -i -t to enter both interactive and trace
mode on startup.
-V, --versionDisplay MSIM version information and quit.
$ msim -VEnter
MSIM version 1.3.8.5
copyright (c) 2000-2016 Viliam Holub, Martin Decky
-c, --configSpecify the configuration file name which overrides the default searching rules.
-c|--config[=]filename$ msim -c my.conf
-i, --interactiveThe simulator enters the interactive mode immediately after the configuration file has been processed.
$ msim -iEnter
[msim]
-t, --traceEnter the trace mode, but does not enable the interactive mode.
$ msim -tEnter
1 BFC00000 lui a0, 0x8000 # 0x8000=32768, a0: 0x0->0x80000000
0 BFC00000 lui a0, 0x8000 # 0x8000=32768, a0: 0x0->0x80000000
1 BFC00004 ori a0, a0, 0x1000 # 0x1000h=4096, a0: 0x80000000->0x80001000
0 BFC00004 ori a0, a0, 0x1000 # 0x1000h=4096, a0: 0x80000000->0x80001000
1 BFC00008 sw 0, (a0)
0 BFC00008 sw 0, (a0)
...
-g, --remote-gdbEnter the GDB mode which allows a MIPS GDB to be connected to the running MSIM for remote debugging. The GDB mode is rather experimental in version 1.3.8.5.
-g|--remote-gdb[=]port_number-h, --helpPrint command line help and quit.
When no configuration file msim.conf exists in the current
directory (and no other configuration file is specified via the -c
command line parameter), the simulator represents and "empty computer"
after startup. In this case MSIM will go into interactive mode.
By default, there are no hardware devices configured, there is no physical memory, there is not even a CPU for running code. Just the MSIM command line prompt can be seen:
[msim]
You have to use the system commands to configure the environment. Here is a reasonable minimal set of commands which are required to execute some MIPS code:
[msim] add dcpu cpu0Enter [msim] add rwm memory 0x00000000Enter [msim] memory generic 16MEnter [msim] add rom firmware 0x1fc00000Enter [msim] firmware generic 4096kEnter [msim] firmware load "firmware.img"Enter [msim]
This will configure the environment with the following devices:
cpu0)memory)firmware)
firmware.img (this file must exist it the current
directory of the host computer)After this basic configuration the simulator is ready to execute the
code (sequence of MIPS instructions) loaded from the file firmware.img
and stored in the firmware read-only memory. The single CPU configured
in the system (cpu0) will start the execution at the virtual address
0xbfc00000, which exactly corresponds to the physical address 0x1fc00000 (i.e.
the start of firmware memory).
The executed code will be able to use the read/write memory memory
located at the physical address 0x00000000. The execution environment is modeled
strictly according to the specification of MIPS R4000 CPU (please refer to
Please refer also to further sections of this text for details about the commands used in our brief example.
The configuration file of MSIM (usually called msim.conf)
contains any system commands which would be otherwise typed in interactive
mode in MSIM prompt. This allows for maximum flexibility and ease of use
as you don't have to learn to use the set of commands for the interactive
mode and another set of commands for the use in the configuration file.
A typical msim.conf might look like this:
1 # 2 # MSIM configuration script 3 # 4 5 add dcpu cpu0 6 add dcpu cpu1 7 8 add rwm mainmem 0x00000000 9 mainmem generic 16M 10 mainmem load "/dev/zero" 11 12 add rom bootmem 0x1fc00000 13 bootmem generic 4096k 14 bootmem load "image.boot" 15 16 add dprinter printer 0x10000000 17 add dkeyboard keyboard 0x10000000 2 18 add dorder order 0x10000004 5
Similarily to shell scripts empty lines are ignored. Also any text beginning
with the # character to the end of the line is considered a comment
and is ignored.
MSIM defines several internal variables which control its behaviour during execution. The variables can be set via the set and unset via the unset commands. Following internal variables are available:
The following table and examples demonstrate how the various variables affect the fields which are printed in disassembler.
| Address | Opcode | Instruction | Conversion | Changes | |
|---|---|---|---|---|---|
| Variable | iaddr |
iopc |
ireg |
icmt |
iregch |
| Sample output | 80000F04 |
24840100 |
addiu a0, a0, 0x100 |
# 0x100=256 |
, a0: 0x4->0x104 |
Addresses in disassebler:
[msim] unset iaddrEnter [msim] id 0x0040121c 1Enter lw a0, 0x1694(gp) # 0x1694=5780 [msim] set iaddrEnter [msim] id 0x0040121c 1Enter 0040121C lw a0, 0x1694(gp) # 0x1694=5780 [msim]
Opcodes in disassembler:
[msim] unset iopcEnter [msim] id 0x0040121c 1Enter 0040121C lw a0, 0x1694(gp) # 0x1694=5780 [msim] set iopcEnter [msim] id 0x0040121c 1Enter 0040121C 8F841694 lw a0, 0x1694(gp) # 0x1694=5780 [msim]
Additional disassembler information (e.g. hex to decimal number conversions):
[msim] unset icmtEnter [msim] id 0x00400ef8 1Enter 00400EF8 sw a0, 0x1694(gp) [msim] set icmtEnter [msim] id 0x00400ef8 1Enter 00400EF8 sw a0, 0x1694(gp) # 0x1694=5780 [msim]
Register changes in disassembler:
[msim] unset iregchEnter [msim] s 5Enter 0 80400ECC addu v0, v0, a1 0 80400ED0 sll v0, v0, 0x06 0 80400ED4 subu v0, v0, a1 0 80400ED8 sll v1, v0, 0x02 0 80400EDC addu v0, v0, v1 [msim] set iregchEnter [msim] s 5Enter 0 80400EE0 sll v0, v0, 0x04 # v0: 0xe12018d9->0xe83550, # v1: 0xe03fd900->0xb9c44, # a0: 0x6d9b->0xe9e3a6c0, # a1: 0xa9->0xaf, a2: 0xda->0xdb, # loreg: 0x394745fa->0x7844ddc0, # hireg: 0x7116dba5->0x7544c9eb 0 80400EE4 addu v0, v0, a1 # v0: 0xe83550->0xe835ff 0 80400EE8 sll v1, v0, 0x08 # v1: 0xb9c44->0xe835ff00 0 80400EEC addu v0, v0, v1 # v0: 0xe835ff->0xe91e34ff 0 80400EF0 subu a0, a0, v0 # a0: 0xe9e3a6c0->0xc571c1 [msim]
The ireg selects the scheme for register names used by the
disassembler:
ireg
| Description | List of register names |
|---|---|---|
| 0 | Processor-oriented | r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15 r16 r17 r18 r19 r20 r21 r22 r23 r24 r25 r26 r27 r28 r29 r30 r31 |
| 1 | AT&T assembler | $0 $1 $2 $3 $4 $5 $6 $7 $8 $9 $10 $11 $12 $13 $14 $15 $16 $17 $18 $19 $20 $21 $22 $23 $24 $25 $26 $27 $28 $29 $30 $31 |
| 2 | Compiler convention | 0 at v0 v1 a0 a1 a2 a3 t0 t1 t2 t3 t4 t5 t6 t7 s0 s1 s2 s3 s4 s5 s6 s7 t8 t9 k0 k1 gp sp fp ra |
ireg
| Description | List of register names |
|---|---|---|
| 0 | Processor-oriented | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
| 1 | AT&T assembler | $0 $1 $2 $3 $4 $5 $6 $7 $8 $9 $10 $11 $12 $13 $14 $15 $16 $17 $18 $19 $20 $21 $22 $23 $24 $25 $26 $27 $28 $29 $30 $31 |
| 2 | Compiler convention | index random entrylo0 entrylo1 context pagemask wired res_7 badvaddr count entryhi compare status cause epc prid config lladdr watchlo watchhi xcontext res_21 res_22 res_23 res_24 res_25 res_26 res_27 res_28 res_29 errorepc res_31 |
Sample of usage:
[msim] set ireg=0Enter [msim] id 0x00400efc 4Enter 00400EFC srl r4, r4, 0x08 00400F00 andi r4, r4, 0x000f # 0xfh=15 00400F04 addiu r4, r4, 0x100 # 0x100=256 00400F08 sltu r4, r6, r4 [msim] set ireg=1Enter [msim] id 0x00400efc 4Enter 00400EFC srl $4, $4, 0x08 00400F00 andi $4, $4, 0x000f # 0xfh=15 00400F04 addiu $4, $4, 0x100 # 0x100=256 00400F08 sltu $4, $6, $4 [msim] set ireg=2Enter [msim] id 0x00400efc 4Enter 00400EFC srl a0, a0, 0x08 00400F00 andi a0, a0, 0x000f # 0xfh=15 00400F04 addiu a0, a0, 0x100 # 0x100=256 00400F08 sltu a0, a2, a0 [msim]
The trace variable switches the simulator into the trace mode.
In trace mode, all the executed instructions are disassembled and immediately
displayed on the screen.
[msim] unset traceEnter [msim] sEnter [msim] sEnter [msim] sEnter [msim] set traceEnter [msim] sEnter 0 80400EC8 sll v0, a1, 0x04 # v0: 0x1fcec0c2->0x2f0, # a1: 0x1ffc0227->0x2f [msim] sEnter 0 80400ECC addu v0, v0, a1 # v0: 0x2f0->0x31f [msim] sEnter 0 80400ED0 sll v0, v0, 0x06 # v0: 0x31f->0xc7c0 [msim]
The command line support various nice features like command history, tab completion for completing the commands and arguments while typing, etc.
A very brief overview of the input command line properties:
0x representing hexadecimal
notation.k and K
(representing multiplication by 1024 or 1000) and M (representing
multiplication by 1048576)."abcd").This section describes the commands of MSIM. These commands can be used either in the interactive mode or in a configuration file.
addAdd a new device into the system under a specified name.
add device_type device_name [device_parameters...]where
device_typedevice_namedevice_parametersThe first example adds a new printer p0 to the system. The printer register is located at physical address 0x0001000.
[msim] add dprinter p0 0x1000Enter
[msim]
The second example adds a read-only memory m0 mapped at physical address 0x00010000. The size of the memory is 16 KB.
[msim] add rom m0 0x10000 16kEnter
[msim]
quitQuit the simulator immediately.
mdPrint a part of a memory from an unmapped address.
md address countwhere
addresscountThe following example prints 10 words from the physical address 0x00001240.
[msim] md 0x1240 10Enter
00001240 265a45cd 2fefe111 11deadee 30957311
00001250 7b218f9f ffff2345 baba5555 deadbeaf
00001260 29dc9aff 1298aa23
[msim]
idPrint disassembled instructions from the specified unmapped address.
id address countwhere
addresscountThe following example prints 10 instructions from the address 0x000012a8.
[msim] id 0x12a8 10Enter
000012A8 ori s0, s0, 0x5427 # 0x5427h=21543
000012AC sw s2, 0x18(sp) # 0x18=24
000012B0 lui s2, 0x805a # 0x805a=32858
000012B4 ori s2, s2, 0xce55
000012B8 sw s1, 0x14(sp) # 0x14=20
000012BC lui s1, 0x8100 # 0x8100=33024
000012C0 sw ra, 0x1c(sp) # 0x1c=28
000012C4 lw a0, 0x1640(gp) # 0x1640=5696
000012C8 jal +0x4009d4 # 0x4009d4=4196820
000012CC nop
[msim]
ddPrint a list of devices with parameters configured in the environment.
The following example prints all devices in the system.
[msim] ddEnter
[ name ] [ type ] [ parameters...
printer dprinter address:0x01000000
startmem rom start:0x1fc00000 size:1k type:mem
xxx rwm start:0x00400000 size:256k type:mem
mainmem rwm start:0x00000000 size:256k type:mem
mips1 dcpu type:R4000.32
[msim]
mbdPrint all configured memory blocks.
The following example prints all installed memory blocks.
[msim] mbdEnter
[ name ] [ type ] [ parameters...
startmem rom start:0x1fc00000 size:1k type:mem
xxx rwm start:0x00400000 size:256k type:mem
mainmem rwm start:0x00000000 size:256k type:mem
[msim]
breakAdd memory access breakpoint. If a read or write access on the the physical address of the breakpoint occurs, the simulator is immediately switched to interactive mode.
break address typewhere
addresscountr), write accesses (w) or both (rw).bdPrint all configured memory access breakpoints.
brRemove previously configured memory breakpoint.
break addresswhere
addressstatPrint statistics of installed devices.
The following example prints the statistics of all the installed devices.
[msim] statEnter
[ name ] [ type ] [ statistics...
printer dprinter count:42248
startmem rom no statistics
xxx rwm no statistics
mainmem rwm no statistics
mips1 dcpu cycles total:1373061 in kernel:1373061 in user:0
in stdby:0 tlb refill:0 invalid: 0 modified:0
interrupts 0:0 1:0 2:0 3:0 4:0 5:0 6:0 7:0
[msim]
echoPrint user message. The echo command is usually used for debugging purposes, mainly in the configuration file.
echo messagewhere
messageThe following example prints the message "The point A has been reached".
[msim] echo "The point A has been reached"Enter
The point A has been reached
[msim]
continueContinue in the simulation. The interactive mode is leaved.
In the following example, the execution is terminated by pressing
Ctrl+C and later restarted by the continue
command. The trace mode in still on:
... 0 80400ED4 subu v0, v0, a1 # v0: 0x24640->0x245b7 0 80400ED8 sll v1, v0, 0x02 # v1: 0xb71d6a00->0x916dcCtrl+C [msim] continueEnter 0 80400EDC addu v0, v0, v1 # v0: 0x245b7->0xb5c93 0 80400EE0 sll v0, v0, 0x04 # v0: 0xb5c93->0xb5c930 0 80400EE4 addu v0, v0, a1 # v0: 0xb5c930->0xb5c9b9 ...
stepExecute one or a specified number of cycles. The step command is default
(it is executed if a blank command line entered).
step [count]where
countIn the following example, the user executes 3 steps on a 2-processor machine:
[msim] s 3Enter
1 80400ACC mfc0 v0, status # v0: 0x0->0x8001
0 80400EC4 srl a1, a1, 0x18 # 0x18=24, a1: 0x6538b04f->0x65
1 80400AD0 addiu v1, 0, 0xfffe # v1: 0x0->0xfffffffe
0 80400EC8 sll v0, a1, 0x04 # v0: 0x219dad69->0x650
1 80400AD4 and v0, v0, v1 # v0: 0x8001->0x8000
0 80400ECC addu v0, v0, a1 # v0: 0x650->0x6b5
[msim]
setSet an internal variable on or to a specified value or print a list of all variables.
set [variable [= value]]where
variablevaluetrue is assumed).Refer to the Internal variables section for
a list and a description of available variables. If value is not
specified, the variable is set to the logical true. Note that
not all variables can hold a logical values.
For boolean variables, there are several synonyms for true:
true, on, yes. Similarly the
synonyms for false are: false, off,
no and their prefixes.
In the first example, we list all the variables:
[msim] setEnter
Group Variable Value
---------------------- ---------- ----------
Disassembling features
iaddr on
iopc off
icmt on
iregch on
ireg 2
Debugging features
trace off
[msim]
In the second example, we switch to trace mode:
[msim] sEnter [msim] set traceEnter [msim] sEnter 0 80401378 addiu a0, a0, 0x40 # 0x40=64, a0: 0xb7b8->0xf8 [msim]
And in the third example, we set the type of register names:
[msim] set ireg = 2Enter [msim] id 0x00401330 1Enter 00401330 srl v0, v0, 0x01 [msim] set ireg = 0Enter [msim] id 0x00401330 1Enter 00401330 srl r2, r2, 0x01 [msim]
unsetUnset a logical internal variable.
unset variablewhere
variableSpecified variable must hold a logical value. Refer to the
Internal variables section for the list
and description of available variables.
In the following example, the trace mode is switched off:
[msim] sEnter 0 80401334 addu r5, r5, r2 # r5: 0x6512c4be->0x9754a5b8 [msim] unset traceEnter [msim] sEnter [msim]
helpShow the help for the specified system command or print the list of available system commands.
help [command]where
commandMSIM can be configured with any number of device instances. Every device instance has a given type. This section describes the available types of devices and their properties.
dcpuThe dcpu device encapsulates a processor.
help [cmd]infostatcp0d [rn]tlbdmd saddr sizeid sa cntrdgoto addrbreak addrbdbr addrExample of the help command:
[msim] add dcpu mips1Enter [msim] mips1 helpEnter Command & arguments Description -------------------- --------------------> help [cmd] Display this help text info Display configuration information stat Display processor statistics cp0d [rn] Dump contents of the coprocessor 0 register(s) tlbd Dump content of TLB md saddr size Dump specified TLB mapped memory block id saddr cnt Dump instructions from specified TLB mapped memory rd Dump contents of CPU general registers goto addr Go to address break addr Add code breakpoint bd Dump code breakpoints br addr Remove code breakpoint [msim]
Example of the info command:
[msim] mips1 infoEnter
type:R4000.32
[msim]
Example of the stat command:
[msim] mips1 statEnter
cycles total:853037 in kernel:853037 in user:0 in stdby:0 tlb refill:0
invalid: 0 modified:0
interrupts 0:0 1:0 2:0 3:0 4:0 5:0 6:0 7:0
[msim]
Example of the cp0d command:
[msim] mips1 cp0dEnter
no name hex dump readable dump
00 Index 0000002F index: 2F res: 0 p: 0
01 Random 00000003 random: 03, res: 0000000
02 EntryLo0 00000006 g: 0 v: 1 d: 1 c: 0 pfn: 000000 res: 0
03 EntryLo1 00000000 g: 0 v: 0 d: 0 c: 0 pfn: 000000 res: 0
04 Context 00000000 res: 0 badvpn2: 00000 ptebase: 000
05 PageMask 001FE000 res1: 0000 mask: 0FF (1M) res2: 00
06 Wired 00000001 wired: 1 res: 0000000
08 BadVAddr 00000000 badvaddr: 00000000
09 Count 0005A993 count: 5a993
0a EntryHi 00000000 asid: 00 res: 0 vpn2: 00000
0b Compare 0005ACDC compare: 5acdc
0c Status 00008001 ie: 1 exl: 0 erl: 0 ksu: 0 ux: 0 sx: 0 kx: 0
im: 80 de: 0 ce: 0 ch: 0 res1: 0 sr: 0 ts: 0
bev: 0 res2: 0 re: 0 fr: 0 rp: 0 cu: 0
0d Cause 00000000 res1: 0 exccode: 00 res2: 0 ip: 00 res3: 00
ce: 0 res4: 0 bd: 0
0e EPC 80401344 epc: 80401344
0f PRId 00000200 rev: 00 imp: 02 res: 0000
10 Config 00000000 k0: 0 cu: 0 db: 0 b: 0 dc: 0 ic: 0 res: 0 eb: 0
em: 0 be: 0 sm: 0 sc: 0 ew: 0 sw: 0 ss: 0 sb: 0
ep: 0 ec: 0 cm: 0
11 LLAddr 00000000 lladdr: 00000000
12 WatchLo 00000000 w: 0 r: 0 res: 0 paddr0: 00000000
13 WatchHi 00000000 res: 00000000 paddr1: 0
14 XContext
1e ErrorEPC 00000000 errorepc: 00000000
[msim]
Example of the tlbd command:
[msim] mips1 tlbdEnter
[ general ][ subp 0 ][ subp 1 ]
no vpn mask g asid v d pfn c v d pfn c
00 00000000 FFE00000:1M 0 00 1 1 00000000 0 0 0 00000000 0
01 00000000 FFE00000:1M 0 ff 1 1 00000000 0 0 0 00000000 0
[msim]
Example of the rd command:
[msim] mips1 rdEnter
processor p0
0 00000000 at 81000000 v0 62935B2A v1 62312A00 a0 00000001
a1 0000004A a2 0000002E a3 0000002D t0 00000000 t1 00000000
t2 00000000 t3 00000000 t4 00000000 t5 00000000 t6 00000000
t7 00000000 s0 000D5427 s1 81000000 s2 805ACE55 s3 00000000
s4 00000000 s5 00000000 s6 00000000 s7 00000000 t8 00000000
t9 00000000 k0 00000000 k1 00000000 gp 00000000 sp 00013050
fp 00000000 ra 80401308 pc 80401310 lo 40689065 hi 320BBCB7
[msim]
rwmThe rwm device represents a read/write random
access memory region. The memory block could be a general memory
or mapped from a file.
addresswhere
addresshelp [cmd]infostatgeneric sizefmap filenamefill [value]load filenamesave filenameExample of the info command.
[msim] startmem infoEnter
start:0x1fc00000 size:1k type:mem
[msim]
In the following example, the add command creates
a read/write memory region mx starting at the physical
address 0x00001000. The size of the region is set to 256 KB
via the generic command.
[msim] add rwm mx 0x1000Enter [msim] mx generic 256kEnter [msim]
The content of the read-write memory can be changed as expected from the code running in the simulator:
1 volatile char *p = (char * ) 0x1000; /* assume 1:1 identity memory mapping */ 2 char c = *p; /* c contains a byte value read from the address 0x00001000 */ 3 *p += 1; 4 char d = *p; /* d contains a byte value read from the address 0x00001001 */
romThe rom device represents a read-only random access memory region.
addresswhere
addresshelp [cmd]infostatgeneric sizefmap filenamefill [value]load filenamesave filenameIn the following example, the add command creates
a read-only memory region mx starting at the physical
address 0x00001000. The size of the region is set to 256 KB
via the generic command.
[msim] add rom mx 0x1000Enter [msim] mx generic 256kEnter [msim]
All attempts to write into read-only memory are silently ignored.
1 volatile char *p = (char * ) 0x1000; /* assume 1:1 identity memory mapping */ 2 char c = *p; /* c contains a byte value read from the address 0x00001000 */ 3 *p = ~c; /* write access is ignored */ 4 char d = *p; /* c == d */
dprinterThe character output device simulates a simple character printer or a serial console.
addresswhere
address| Offset | Name | Operation | Description |
|---|---|---|---|
| +0 | character | read | (ignored) |
| write | character to be printed on the standard output of MSIM |
help [cmd]infostatredir filenamestdoutExample of the info command:
[msim] add dprinter printer 0x10000000Enter [msim] printer infoEnter address:0x01000000 [msim]
Example of the stat command:
[msim] printer statEnter
count:11385
[msim]
Example of a simple output implementation in the MIPS code:
1 /* VIDEOADDR is the address of the memory-mapped register of dprinter. 2 * It has to correspond with the definition in the configuration file. */ 3 #define VIDEOADDR 0x10000000 4 5 / * Write one character on the screen. */ 6 void putchar(char c) 7 { 8 *((volatile char *) VIDEOADDR) = c; 9 } 10 11 /* Write a NULL-terminated string on the screen. */ 12 void putstring(char* c) 13 { 14 while (*c) 15 *((volatile char *) VIDEOADDR) = *c++; 16 }
dkeyboardThe character input device simulates a keyboard connected to the machine. When a key is pressed, the keyboard asserts an interrupt and the ASCII key code can be read from the memory-mapped register. Any read operation on the register automatically deasserts the pending interrupt.
address intnowhere
addressintno| Offset | Name | Operation | Description |
|---|---|---|---|
| +0 | keycode | read | key code of the pressed key (any read operation deasserts the pending interrupt) |
| write | (ignored) |
help [cmd]infostatgen keycodeThe following command adds a keyboard kb to the machine. The keyboard register is
mapped physical address 0x10000000.
[msim]add dkeyboard kb 0x1000000Enter
[msim]
Example of the info command:
[msim] kb infoEnter
address:0x10000000 intno:3 regs(key:0x00 ig:0)
[msim]
Example of the stat command.
[msim] kb statEnter
intrc:11 keycount:11 overrun:0
[msim]
ddiskThe block device simulates a simple hard disk with DMA capabilities. The device can be accesses by linearly ordered 512 B-sized sectors. The device allows to access the contents of a file from the host system running MSIM.
address intnowhere
addressintno| Offset | Name | Operation | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| +0 | DMA buffer address | read | get the current physical address of the DMA buffer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| write | set the physical address of the DMA buffer
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| +4 | sector number | read | get the current sector number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| write | set the sector number which be used by the next |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| +8 | status/command | read | get a bitfield representing the current status of the device:
where the meaning of the fields read is
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| write | set a bitfield representing requested operation:
where the meaning of the fields read is
(initiating both read and write operation at the same time results with an error) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| +12 | disk size | read | get the size of the block device in bytes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| write | (ignored) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
help [cmd]infostatgeneric sizefmap namefill [value]load fnamesave fnamedorderThis device allows to obtain a processor serial number in a multiprocessor configuration and asserting an interprocessor interrupt on a specified processor.
address intnowhere
addressintno| Offset | Name | Operation | Description |
|---|---|---|---|
| +0 | processor number | read | get the unique number of the processor performing the read operation |
| interrupt up | write | setting any bit causes an interrupt pending on the processor specified by the bit index | |
| +4 | interrupt down | read | (ignored) |
| write | setting any bit acknowledges an interrupt pending on the processor specified by the bit index (the interrupt is deasserted) |
help [cmd]infostatsynch maskThe following example adds a new dorder device named order and maps its register
on the physical address 0x10000000.
[msim]add dorder order 0x1000000Enter
[msim]
Simple usage in MIPS code:
1 /* ORDER is the address of the memory-mapped register of dorder. 2 * It has to correspond with the definition in the configuration file. */ 3 #define ORDER 0x10000000 4 5 /* Get current CPU identification. */ 6 unsigned int cpu_id(void) 7 { 8 return *((volatile unsigned int *) ORDER); 9 } 10 11 /* Send interprocessor interrupt to the given CPU */ 12 void cpu_send_ipi(unsigned int id) 13 { 14 *((volatile unsigned int *) ORDER) = (1 << id); 15 } 16 17 /* Send interprocessor interrupt to all CPUs */ 18 void cpu_send_ipi_all(void) 19 { 20 *((volatile unsigned int *) ORDER) = 0xffffffff; 21 } 22 23 /* Deassert interprocessor interrupt for the given CPU */ 24 void cpu_ack_ipi(unsigned int id) 25 { 26 *((volatile unsigned int *) (ORDER + 4)) = (1 << id); 27 }
dtimeThis device passes the system time of the host machine to the simulated environment.
addresswhere
address| Offset | Name | Operation | Description |
|---|---|---|---|
| +0 | time | read | number of seconds since the epoch, i.e. 00:00:00 January 1st 1970 UTC (equivalent to the POSIX time() function) |
| write | (ignored) |
help [cmd]infostatTo further improve the ease of debugging the code running in MSIM, there are several non-standard MIPS instructions available. This allows to change the behaviour of the simulator exactly at the place of code required, with only a minimal influence to the debugged code.
a0 general register to the screen.The following example shows an implementation in GCC:
1 #define ___trace_on() asm volatile ( ".word 0x39\n"); 2 #define ___trace_off() asm volatile ( ".word 0x3d\n"); 3 #define ___reg_dump() asm volatile ( ".word 0x37\n"); 4 #define ___halt() asm volatile ( ".word 0x28\n"); 5 #define ___val(i) asm volatile ( ".word 0x35\n" :: "r" (i));
DTRCEnable the trace mode. Together with DTRO instruction, DTRC is useful to show a part of executed code.
0x39DTRODisable the trace mode. Together with DTRC instruction, DTRO is useful to show a part of executed code.
0x3dDINTEnable the interactive mode. The command line is activated immediately.
0x29DRVThe instruction dumps the content of all the general registers to the screen.
0x37DHLTHalt the machine as well as the simulation immediately. Useful also as the power off feature.
0x28DVALPrint the content of the a0 (r4) register.
The instruction can be used to instantly print a value of a variable.
0x35The GDB support is experimental in version 1.3. The feature will be described in more detail after it will be matured.