Introduction
This document is a quick sequence of steps to become familiar with nsim.
This document is not full documentation. See REFERENCES at the end of this file to obtain full documentation.
Setup
UNIX
Use an NSIM installation package from http://www.liberouter.org or
- download Liberouter CVS (at least the directory liberouter/sys_sw/nsim)
- go to liberouter/sys_sw/nsim directory
- type `make install' (if make fails try `make install -f Makefile.no_readline' or `make help')
MS Windows
Use an NSIM installation package from http://www.liberouter.org or
- install cygwin from http://cygwin.com
- open a cygwin console (command line)
- download Liberouter CVS (at least the directory liberouter/sys_sw/nsim)
- change directory to the place where nsim source files are located (usually liberouter/sys_sw/nsim)
- type `./install_for_cygwin.sh'
Nanoprogramming
If you do not know how to write a nanoprogram, see file `nanoprogramming'.
Compilation
to have your program compiled, type
`nsim my_program -o my_program.bin' ... compiled program will be written
into a 64-bit binary file (higher bits are zero
if instructions are shorter that 64-bit).
`nsim my_program -b' ...compiled program will be written on console;
`nsim my_program -b -o my_program.bin.txt' ... compiled program will be
written to text file of binary numbers `1' and `0'.
You can use -h instead of -b, the difference is that hexadecimal
numbers will be displayed instead of binary. Both options may be present,
too.
Debugging
to have your program debugged, type `nsim my_program -i' ... nsim prompt will occur. Type `next' several times and watch the progress of simulation. Type `where' to inspect the value of instruction pointer and line number. Use line number in following command: `break line_number'. This command sets a breakpoint at the current instruction address. Type `quit' and confirm by pressing `y'. Now, execute the simulation again by typing the same command `nsim my_program -i'. A message announces that nsim saved the breakpoint for you. We will utilize this; type `run'. Simulation advances to the next breakpoint. To get a list of other commands that provide further debugging possibilities, type `help'.
If your program cycles and the simulation turns out to be infinite, just press Ctrl+C. The nsim prompt will occur immediately. At this point, the sequence of commands `where' and `setip number' is recommended (where number is a safe instruction address).
Important!
The interpreter often requires additional parameters like I/O files.
These are called interpreter_options and the are different for various
nanoprocessors. interpreter_options are supposed to follow the `-i' option,
i.e., `nsim my_program -i -d input_file -o output_file'. Description of
interpreter_options for individual nanoprocessors should be provided with
instruction set definition.
General syntax for debugging is:
`nsim my_program -i [interpreter_options]'
It is up to the author of instruction set definition to provide a proper documentation concerning the interpreter_options. It is recommended that these options include `-h', help. If the instruction set conforms to this recommendation, the help for the interpreter_options may be obtained by:
`nsim my_program -i -h'
interpretation
It is clear that the interpretation is a part of debugging. If your program is already debugged, you may wish to have it only interpreted. In this mode, no prompt is displayed unless an error occurs or Ctrl+C is pressed.
General syntax for interpretation is:
`nsim my_program -n -i [interpreter_options]'
The purpose of this batch mode is the transformation of nanoprocessor inputs to outputs, i.e.,
`nsim my_program -n -i -i in_file -o out_file'
How to get help
- Type `nsim' with no parameters to get help on nsim syntax.
- When nsim prompt occurs, type `help' to get the list of debugging commands.
- Type `man nsim' for nsim manual page
References
- Filip Hofer, CESNET technical report number 5/2003, available at http://www.cesnet.cz/doc/techzpravy/2003/ipv6pktanalysis/ipv6pktanalysis.pdf Chapter 6, Chapter 7 and Appendix A
- The Liberouter project, NSIM group, http://www.liberouter.org
