.TH simulate 1 "Sept 18, 2007" "" "SAM system simulator"
.SH NAME
simulate - run SAM with a particular system configuration
.SH SYNOPSIS
simulate [-p 
.I processor]
-c 
.I config
[-w 
.I workers]
[-sav] 
[-f
.I cmd_file]
[-l
.I log_file]
[-I
.I system]
[-C
.I system]
[-L
.I image]
[-D
.I define]
[-V
.I veracity-script -b]

simulate [-p 
.I processor]
-c 
.I config
[-w 
.I workers]
[-ra] 
[-f
.I cmd_file]
[-l
.I log_file]
[-I
.I system]
[-C
.I system]
[-L
.I image]
[-D
.I define]
[-V
.I veracity-script -b]

simulate [-p 
.I processor]
-c 
.I config
-d
[-w 
.I workers]
[-f
.I cmd_file]
[-l
.I log_file]
[-I
.I system]
[-C
.I system]
[-L
.I image]
[-D
.I define]

simulate -p 
.I processor
-R 
.I chkpnt
[-f
.I cmd_file]
[-I
.I system]
[-D
.I define]
[-l
.I log_file]


.SH DESCRIPTION
.PP
Simulate is a wizard script that is used to run SAM
with a SAM configuration (rc-file) that was generated
on the fly. The script generates the file sam.rc. 
After generating the file it invokes sam -c sam.rc

The simulate wizard expects that the collection of binaries 
needed to run RUST or Solaris is present in the current 
working directory. Simulate expects a known collection 
of filenames to be present there. Use the getrust(1) and
getsolaris(1) wizards to get a working starting set of files.

Simulate is best used in conjunction with the getrust(1) 
and getsolaris(1) wizards. The get wizards getrust(1) 
and getsolaris(1) create a directory outside the current 
working directory. Change directory into that created 
directory and invoke the simulate wizard there. 

The simulate wizard is not a one for all solution. The
sam.rc file that it generates can always be taken and 
modified for a special need. After the modification,
invoke SAM directly: sam -c modifiedsam.rc, see sam(1).

.SH OPTIONS
.TP
.B -h
Help
.TP
.BI -p " processor"
Be a wizard for 
.I processor
and create a sam.rc file that resembles a system for this 
processor. 
The 
.I processor 
can be one of: n2, depending on the SAM release
that is being used.
.TP
.BI -c " config"
.I config
= 1c1t 1up 1c2t 1g2p 1g4p 1g16p 1g32p 8c8t ...
.br
The configuration is a machine description. Usually for
Solaris and RUST you will find 
.I config-md.bin 
and 
.I config-hv.bin 
files. simulate will err and exit if it can't find the 
specified configuration.
.TP
.BI -w " workers"
.I workers
= 1 2 3 4 ...
.br
The number of workers (worker-threads) to create. A number >1 causes
the simulator to run MP on MP if a configuration with more
then one strand is used. 
.TP
.B -s
Boot Solaris. See getsolaris(1) on how to get Solaris binaries.
The -s option cannot be used in conjunction with the 
-r, -d, or -R options.
.TP
.B -r
Run RUST. See getrust(1) on how to get RUST binaries.
The -r option cannot be used in conjunction with the 
-s, -d, or -R options.
.TP
.B -d 
Run a diag. The -d option cannot be used in conjunction 
with the -s, -r, or -R options.
.TP
.B -a
Auto boot OBP followed by Solaris or RUST. This option 
causes the file nvram1-auto to be loaded instead of the 
file nvram1. In non autoboot mode, the user is expected to know
what to type at the OBP ok prompt. For solaris this
usually is 
.I boot disk
, for RUST this usually is 
.I go.
The -a option is only compatible with -r or -s.
.TP
.B -v
Verbose boot Solaris. This option uses a Solaris
disk image (disk1.verbose) that has a modified 
/etc/system file. The line
.I set moddebug=0x80000000 
was added. The -v option is only compatible with -s.
.TP
.BI -I " system"
This option is for including extra rc files in the generated
sam.rc file. This is useful for example to extend say a bare bone
N2 system (Huron) with devices connected to the pcie bus.
.TP
.BI -C " system"
This option is for advanced users that want to modify the 
system setup. The default system setup 
.IR processor .rc
(here
.I processor 
is the same as provided with the -p option)
is in the etc directory of the release.
.TP
.BI -R " chkpnt"
Start SAM from a dump that is in
.I chkpnt.
A dump is generated at the SAM prompt with the
.BI dump " chkpnt" 
command.
The -R option cannot be used in conjunction with the 
-s, -r, or -d options.
.TP
.BI -L " image"
The 
.I image
argument can be of the form 
.I filename,address
which means load binary file
.I filename
into memory at
.I address.
If there is no comma character in the 
.I image
argument, or image has a trailing comma, then 
.I image 
is a file that is expected to be in the cpu and system 
verilog memory image format. This file-format is usually 
produced by the Midas tool. For the -s and -r option the 
.I image
files are loaded after the standard set of files that are loaded
in these run modes.
The -L can be used to override memory with user specific
values.
The simulate wizard accepts multiple -L options. The 
.I image
files are loaded into memory in the order they appear on 
the command line.
.TP
.BI -D " define"
This option is for advanced users that want to tightly control
the system setup. The -D option passes 
.I define 
on to the m4 tool that preprocesses the system rc file before it
is added to sam.rc. A common
.I define
is 
.I -Dpop=
which disables popping the xterm when used in conjunction with
the -r or -s option.
.TP
.BI -V " veracity-script"
Runs veracity with
.I veracity-script
as an argument.  simulate will create a veracity script to start up
RUST or Solaris, depending on whether
.B -r
or
.B -s
is present.  The start-up script will be called
.B start_rust.ver
or
.B start_solaris.ver
respectively which can be included by
.I veracity-script
to perform standard initialization.
.TP
.B -b
Used with the
.B -V
flag, this runs veracity in batch mode, directing all serial console
output to
.B stdout.
.TP
.BI -f " cmd_file"
Run SAM UI commands from file <cmd_file> before returning to UI prompt.
.TP
.BI -l " log_file"
Turn on output logging to file <log_file>.
.SH EXAMPLES
.LP
The example processor here is n2. The available processor depend 
on the SAM release.
.LP
Run Solaris on one strand, autoboot, and in verbose mode.
.IP
.B "simulate -p n2 -c 1c1t -s -a -v"
.LP
Run Solaris on two strands, autoboot and use two workers.
.IP
.B "simulate -p n2 -c 1c2t -w2 -s -a"
.LP
Run RUST on one strand, autoboot.
.IP
.B "simulate -p n2 -c 1c1t -r -a"
.LP
Run RUST on two strands, autoboot and use two workers.
.IP
.B "simulate -p n2 -c 1c2t -w 2 -r -a"
.LP
Run Solaris on one strand, loading one extra binary file into memory.
.IP
.B "simulate -pn2 -c1c1t -sa -Lmyreset.bin,0xff0000000"
.LP
Run a diag on one strand, loading one verilog memory image file into memory.
.IP
.B "simulate -pn2 -c1c1t -d -Lmem.image"
.LP
Run Solaris and do not pop up the console xterms
.IP
.B "simulate -pn2 -c1c2t -w2 -sa -Dpop="
.SH BUGS
.PP
The config -c option in combination with -s or -r option is at the 
mercy of the available machine description files.
.SH SEE ALSO
.BR getsolaris (1),
.BR sam (1),
.BR m4 (1)
.SH AUTHORS
.nf
Wizard and manual page by SUN
.f