With a small piece of practice, you fill find msim easy and confortable. Follow this tutorial to overcome the difficult beginner's live.

Status of the document



Let's start with downloading the simulator:

~/tmp$ wget http://d3s.mff.cuni.cz/~holub/sw/msim/msim-1.3.1.tar.gzEnter
--12:24:12--  http://d3s.mff.cuni.cz/~holub/sw/msim/msim-1.3.1.tar.gz
           => `msim-1.3.x.tar.gz'
Resolving d3s.mff.cuni.cz...
Connecting to d3s.mff.cuni.cz||:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 150,497 (147K) [application/x-gzip]

100%[==========================================================>] 150,497       --.--K/s

12:24:12 (5.39 MB/s) - `msim-1.3.x.tar.gz' saved [150497/150497]


Note that you should take a current version. That's why I've used an irregular tarball name, so you can't simply cut'n paste it. Unpack the tarball...

~/tmp$ tar xzf msim-1.3.x.tar.gzEnter
~/tmp$ cd msim-1.3.xEnter

and configure it:

~/tmp/msim-1.3.x$ ./configure --prefix=/optEnter
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking whether make sets $(MAKE)... yes
checking for working aclocal-1.4... found
checking for working autoconf... found
checking for working automake-1.4... found

Here, we select the /opt directory where the msim will be installed, you can specify whatever you want. For own installation, ~/opt sounds good. The default installation directory is /usr/local. For other parameters, look at ./configure --help.

The second step is to compile msim:

~/tmp/msim-1.3.x$ makeEnter

and install it (you should have rights to write to the destination directory, probably be a root):

~/tmp/msim-1.3.x$ make installEnter


Let's assume that the installation has been completed. After starting msim, you will see this:

~$ msimEnter

Not a lot - we are at the command line. A lot of magic things could be done via this simple but powerful interface. The first command we will learn is help. Just type h-e-l-p and press Enter.

[msim] helpEnter
List of available commands:
add type name        Adds a new device into the system.
rm dname             Removes the device from the system.
quit                 Exits msim.
md addr cnt          Dumps words from unmapped memory.
id addr cnt          Dumps instructions from unmapped memory.
dd                   Dumps all installed devices.
mbd                  Dumps all installed memory blocks.
stat                 Dumps available statistic information.
echo [text]          Prints user message.
goto [addr]          Go to the specified address or continue.
step/s [cnt]         Simulates one or a specified number of instructions.
set [name [= val]]   Sets enviroment variables.
unset name           Unsets enviroment variables.
help [cmd]           Displays a help text.

And we can see a list of available commands with a short description. To make life easier, you don't have to write the whole command name. Only first few letters which identifies the command uniquely are necessary. Just try to type hel and see. Even he and h is enough. You can also type the Tab key and the simulator will continue in typing until there is no ambiguity in command names (the so-called tab completion). When you type he and press Tab, the full name help will appear. If there are more choices available, msim will show you all of them by typing Tab twice. Try to type s and double-press Tab:

[msim] sTabTab
set   stat  step  
[msim] s

There are three commands which starts with s. Type the second letter t and the available commands are:

[msim] stTabTab
stat  step  
[msim] st

By the way, the best practice of how to learn msim is to follow this tutorial and try all the things yourself. Did you tried that? No, you didn't. Do so now, I'll wait for you...

You didn't try it anyway, am I right? So stop blaming me and do so now.

OK, let's move on. Complete the command step and run it:

[msim] stepEnter

Nothing happens? Well, it does, but nothing visible. The simulator is cycle-driven. It means that all the performed operations depends on a virtual clock. However, when you run the simulator without any parameters, the simulated machine is clear as the sky on the moon. You can have a look on it by the dd command which - as the help say - dumps all installed devices:

[msim] ddEnter
[  name  ] [  type  ] [ parameters...
-- no devices --

It's clearly visible the list is empty. All the machine pheripherals are reffered as devices. One such device may be a memory or a processor. By the way, why not add a memory and a processor? All we need is to choose a fine name :). The command add will enhance the machine on our request. We can ask for help when using add:

[msim] help addEnter
Adds a new device into the system.
Syntax: add  
	<type> Device type
	<name> Device name

All the commands have a similar help text. Yes, even the help command. So we need a device type and a name. Let's start with add and ask the tab completion for the list of device types:

[msim] add TabTab
dcpu       ddisk      dkeyboard  dorder     dprinter   dtime      rom        rwm

We are now interested in processors, so the dcpu device type is what we need. The device types are almost self-explanatory, rom stands for read-only memory and rwm stands for read-write memory, also incorrectly referred as ram. The first d letter is just for clearity, to somehow make a space for usual users identifies. Let's add a processor named c0 and check it by listing devices:

[msim] add dcpu c0Enter
[msim] dd
[  name  ] [  type  ] [ parameters...
c0         dcpu       type:R4000.32

Here it is, we have a processor in our system. Pretty easy, isn't it? Yeah, we can have more than one processors:

[msim] add dcpu GeorgeEnter
[msim] add dcpu JoeEnter
[msim] ddEnter
[  name  ] [  type  ] [ parameters...
Joe        dcpu       type:R4000.32
George     dcpu       type:R4000.32
c0         dcpu       type:R4000.32

Once again, to make us life easier, you can use up and down arrows on you keyborad to scroll the history of your typed commands.

Righ now, we don't need more processors. Sorry Geore and Joe, we apply the remove command rm:

[msim] rm GeorgeEnter
[msim] rm JoeEnter

Processors feels better in a memory. Thus we add a read-write memory by the add command:

[msim] add rwm main 0x0 256kEnter

We have added a memory called "main" which starts at the address 0 (that's the start of the address space) and has 256 kilobytes. Addresses are often typed in hexadecimal so we have used the 0x prefix, otherwise the number would be decimal. The number may be postfixed by a modificator "k", "K" or "M". The number will be than multiplied by 1000, 1024 or 1048576 respectively. In our example, the size of the memory is 256k which is 262144 bytes.

And the list of devices says:

[msim] ddEnter
[  name  ] [  type  ] [ parameters...
c0         dcpu       type:R4000.32
main       rwm        start:0x00000000 size:256k type:none

There is a specialized command for listing just memory devices - mbd.

So we have a processor and a memory. Fine, what to do next? We should somehow initialize the memory. We can do that by special device-oriented commands. Commands presented so far have been system-wide or, in other words, general. But each device has its own commands appliable on specified device instance. To type such a command, simply start the command line with the device name. In our case, the name of the memory block is "main". And the classic command help may look like:

[msim] main help