MSIM Version 1.3.8.4 Reference Manual

Abstract

The purpose of this document is to provide a comprehensive reference manual for MSIM version 1.3.8.4.

© 2007 Viliam Holub (holub+DELETE@d3s.mff.cuni.cz)
© 2010 Martin Decky (decky+DELETE@d3s.mff.cuni.cz)

Last change

2010-10-05

Table of contents

1. Introduction

MSIM 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 trace mode, where all executed instructions are displayed together with system events. In interactive mode the user communicates with the simulator via a command line interface and can modify the environment of the running system.

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 devices in the MSIM terminology) implement a specific functionality such as the CPU, keyboard input, character output, etc.

1.1. Conventions

We use these typographic conventions throughout the text:

TypeExample
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 codeAn example of code inside the text.
Emphasized inline codeAn example of an emphasized code inside the text.
Keyboard keysWhen you should press the Enter key, Enter is used.

2. Deployment

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.

2.1. Download

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.4.tar.bz2Enter
...
$ tar -xjf msim-1.3.8.4.tar.bz2Enter
$ cd msim-1.3.8.4Enter

2.2. Configuration

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

2.3. Compilation

After a succesful execution of configure just run make to compile the sources. No special arguments are usually necessary.

$ make

2.4. Installation

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

3. Command line parameters

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.

3.1. Version -V, --version

Synopsis

Display MSIM version information and quit.

Example

$ msim -VEnter
MSIM version 1.3.8.4
copyright (c) 2000-2010 Viliam Holub, Martin Decky

3.2. Configuration file -c, --config

Synopsis

Specify the configuration file name which overrides the default searching rules.

Syntax -c|--config[=]filename

Example

$ msim -c my.conf

3.3. Interactive mode -i, --interactive

Synopsis

The simulator enters the interactive mode immediately after the configuration file has been processed.

Example

$ msim -iEnter
[msim] 

3.4. Trace mode -t, --trace

Synopsis

Enter the trace mode, but does not enable the interactive mode.

Example

$ 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)

...

3.5. GDB mode -g, --remote-gdb

Synopsis

Enter 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.4.

Syntax: -g|--remote-gdb[=]port_number

3.6. Help -h, --help

Synopsis

Print command line help and quit.

4. System environment

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:

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 MIPS R4000 Microprocessor User's Manual).

Please refer also to further sections of this text for details about the commands used in our brief example.

5. Configuration file

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.

6. Internal variables

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:

trace
Enable trace mode
iaddr
Enable addresses in disassembler
iopc
Enable opcodes in disassembler
icmt
Enable additional comments (such as number conversions) in disassembler
iregch
Show register changes in disassembler
ireg
Set type of register names

The following table and examples demonstrate how the various variables affect the fields which are printed in disassembler.

Instruction disassembling overview
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:

Basic processor registers
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
CP0 registers
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] 

7. Input command line

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:

8. System commands

This section describes the commands of MSIM. These commands can be used either in the interactive mode or in a configuration file.

8.1. List of system commands

add
Add a new device into the system.
quit
Exit MSIM.
md
Dump words from unmapped memory.
id
Dump instructions from unmapped memory.
dd
Dump all installed devices.
mbd
Dump all installed memory blocks.
break
Add memory breakpoint.
bd
Dump memory breakpoints.
br
Remove memory breakpoint.
stat
Dump available statistic information.
echo
Print user message.
Continue
Continue simulaton.
step
Simulate one or a specified number of instructions.
set
Set environment variable.
unset
Unset environment variable.
help
Display a help text.

8.2. Add add

Synopsis

Add a new device into the system under a specified name.

Syntax add device_type device_name [device_parameters...]

where

device_type
Specifies a device type. The list of available device types is in the Devices section.
device_name
An identifier of the newly created device. The name must not be equal to a system command and must be unique among already added devices.
device_parameters
Initial device parameters. The actual parameters depends on the device type.

Example

The 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] 

8.3. Quit quit

Synopsis

Quit the simulator immediately.

8.4. Memory dump md

Synopsis

Print a part of a memory from an unmapped address.

Syntax md address count

where

address
Starting address of the memory block.
count
Number of words to print.

Example

The 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] 

8.5. Instruction dump id

Synopsis

Print disassembled instructions from the specified unmapped address.

Syntax id address count

where

address
Starting address of the memory block.
count
Number of instructions to print.

Example

The 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] 

8.6. Device dump dd

Synopsis

Print a list of devices with parameters configured in the environment.

Example

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] 

8.7. Memory block dump mbd

Synopsis

Print all configured memory blocks.

Example

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] 

8.8. Add memory breakpoint break

Synopsis

Add 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.

Syntax break address type

where

address
Address of the breakpoint.
count
Consider read accesses (r), write accesses (w) or both (rw).

8.9. Dump memory breakpoints bd

Synopsis

Print all configured memory access breakpoints.

8.10. Remove memory breakpoint br

Synopsis

Remove previously configured memory breakpoint.

Syntax break address

where

address
Address of the previously configured breakpoint.

8.11. Statistics stat

Synopsis

Print statistics of installed devices.

Example

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] 

8.12. Print echo

Synopsis

Print user message. The echo command is usually used for debugging purposes, mainly in the configuration file.

Syntax echo message

where

message
String which will be printed.

Example

The 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]

8.13. Continue continue

Synopsis

Continue in the simulation. The interactive mode is leaved.

Example

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

...

8.14. Step step

Synopsis

Execute one or a specified number of cycles. The step command is default (it is executed if a blank command line entered).

Snytax step [count]

where

count
Optional number of cycles to execute.

Example

In 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] 

8.15. Set set

Synopsis

Set an internal variable on or to a specified value or print a list of all variables.

Syntax set [variable [= value]]

where

variable
Name of the internal variable name to be set (if not specified, list of all variables is printed).
value
Value to be assigned to the variable (if not specified, logical true 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.

Example

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] 

8.16. Unset unset

Synopsis

Unset a logical internal variable.

Syntax unset variable

where

variable
Internal variable name to be unset.

Specified variable must hold a logical value. Refer to the Internal variables section for the list and description of available variables.

Example

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] 

8.17. Help help

Synopsis

Show the help for the specified system command or print the list of available system commands.

Syntax help [command]

where

command
Command name (if omited, the list of available system commands is printed).

9. Devices

MSIM 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.

9.1. List of devices

dcpu
Processor (CPU)
rwm
Read/write memory
rom
Read-only memory
dprinter
Character output device (printer)
dkeyboard
Character input device (keyboard)
ddisk
Block device (hard disk)
dorder
Interprocessor communication device
dtime
Real-time clock

9.2. Processor dcpu

The dcpu device encapsulates a processor.

Initialization parameters: none

Commands

help [cmd]
Display a help text for the specified command or a list of available commands.
info
Display the processor configuration
stat
Display processor statistics
cp0d [rn]
Dump contents of CP0 register(s)
tlbd
Dump the content of TLB
md saddr size
Dump specified TLB mapped memory block
id sa 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 configured code breakpoints
br addr
Remove configured code breakpoint

Examples

Example 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] 

9.3. Read/write memory rwm

The rwm device represents a read/write random access memory region. The memory block could be a general memory or mapped from a file.

Initialization parameters: address

where

address
Starting physical address of the memory block.

Commands

help [cmd]
Print a help on the command specified of a list of available commands.
info
Print the device information (block address, size and type)
stat
Print device statistics (none).
generic size
Set the size of the memory block.
fmap filename
Map the contents of the memory block from a file specified.
fill [value]
Fill the memory block with zeros or the specified word value.
load filename
Load the contents of the memory block from a file specified.
save filename
Save the contents of the memory block to a file specified.

Examples

Example 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 */

9.4. Read-only memory rom

The rom device represents a read-only random access memory region.

Initialization parameters: address

where

address
Starting physical address of the memory block.

Commands

help [cmd]
Print a help on the command specified or a list of available commands.
info
Print the device information (block address, size and type)
stat
Print device statistics (none).
generic size
Set the size of the memory block.
fmap filename
Map the contents of the memory block from a file specified.
fill [value]
Fill the memory block with zeros or the specified word value.
load filename
Load the contents of the memory block from a file specified.
save filename
Save the contents of the memory block to a file specified.

Examples

In 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 */

9.5. Character output device dprinter

The character output device simulates a simple character printer or a serial console.

Initialization parameters: address

where

address
Physical address of the printer register

Registers

dprinter programming registers
OffsetNameOperationDescription
+0 character read (ignored)
write character to be printed on the standard output of MSIM

Commands

help [cmd]
Print a help text to the specified command or a list of allowed commands.
info
Print basic configuration information (register address).
stat
Print printer statistics (number of characters printed).
redir filename
Redirect the output to the file specified.
stdout
Redirect the output to the standard output.

Example

Example 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 }

9.6. Character input device dkeyboard

The 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.

Initialization parameters: address intno

where

address
Physical address of the keyboard register.
intno
Interrupt number which will be asserted on keypress.

Registers

dkeyboard programming registers
Offset Name Operation Description
+0 keycode read key code of the pressed key (any read operation deasserts the pending interrupt)
write (ignored)

Commands

help [cmd]
Print a help on the command specified or a list of available commands.
info
Print configuration information (register address, interrupt number and a keycode pending).
stat
Print device statistics (number of interrupts, pressed keys and overrun keys).
gen keycode
Synthetically generates a key press event.

Examples

The 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] 

9.7. Block device ddisk

The 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.

Initialization parameters: address intno

where

address
Physical address of the hard disk register.
intno
DMA Interrupt number.

Registers

ddisk programming registers
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
  • performing a read operation will store the data read from the block device to this buffer
  • performing a write operation will fetch the data to be written to the block device from this buffer
+4 sector number read get the current sector number
write set the sector number which be used by the next read or write operation
+8 status/command read

get a bitfield representing the current status of the device:

31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
r1 e i r0

where the meaning of the fields read is

r1
(reserved)
e
0: no error
1: the previous operation caused an error
i
0: no DMA interrupt pending
1: DMA interrupt pending
r0
(reserved)
write

set a bitfield representing requested operation:

31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
r0 i w r

where the meaning of the fields read is

r0
(reserved)
i
if set to 1 then the DMA interrupt is deasserted
w
if set to 1 then a write operation is initiated (fetching the data from the DMA buffer and writing it to the sector set)
r
if set to 1 then a read operation is initiated (reading the data from the sector set and storing it to the DMA buffer)

(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)

Commands

help [cmd]
Print a help on the command specified or a list of available commands.
info
Print the device information.
stat
Print device statistics.
generic size
Allocate a block device of the given size from host memory.
fmap name
Map the block device to a file specified.
fill [value]
Fill the block device with zeros or the specified word value.
load fname
Load the contents of the block device from a file specified.
save fname
Save the contents of the block device to a file specified.

9.8. Interprocessor communication device dorder

This device allows to obtain a processor serial number in a multiprocessor configuration and asserting an interprocessor interrupt on a specified processor.

Initialization parameters: address intno

where

address
Physical address of the device register.
intno
Interprocessor communication interrupt number.

Registers

dorder programming registers
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)

Commands

help [cmd]
Print a help on the command specified or a list of available commands.
info
Print configuration information (register address and interrupt number).
stat
Print device statistics (number of interrupts).
synch mask
Simulate a write operation on the "interrupt up" register.

Examples

The 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 }

9.9. Real-time clock dtime

This device passes the system time of the host machine to the simulated environment.

Initialization parameters: address

where

address
Physical address of the device register.

Registers

dtime programming registers
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)

Commands

help [cmd]
Print a help on the command specified or a list of available commands.
info
Print configuration information (assigned register address).
stat
Print device statistics (none).

10. Special instructions

To 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.

DTRC
Enable the trace mode.
DTRO
Disable the trace mode.
DINT
Enable the interactive mode.
DRV
Dump the content of all general registers to the screen.
DHLT
Halt the simulation.
DVAL
Dump the a0 general register to the screen.

Example

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));

10.1. Trace on DTRC

Enable the trace mode. Together with DTRO instruction, DTRC is useful to show a part of executed code.

Opcode: 0x39

10.2. Trace off DTRO

Disable the trace mode. Together with DTRC instruction, DTRO is useful to show a part of executed code.

Opcode: 0x3d

10.3. Interactive mode on DINT

Enable the interactive mode. The command line is activated immediately.

Opcode: 0x29

10.4. Register view DRV

The instruction dumps the content of all the general registers to the screen.

Opcode: 0x37

10.5. Halt machine DHLT

Halt the machine as well as the simulation immediately. Useful also as the power off feature.

Opcode: 0x28

10.6. View value DVAL

Print the content of the a0 (r4) register. The instruction can be used to instantly print a value of a variable.

Opcode: 0x35

11. GDB support

The GDB support is experimental in version 1.3. The feature will be described in more detail after it will be matured.