Appendix H - CSIM Preprocessor and Simulator Command-Line Options
The two sections below list the command-line options for:
- I. Build-time options - CSIM Preprocessor.
- II. Run-time options - Sim.exe Simulator.
I. CSIM Build-Time Options
The CSIM-Preprocessor supports the following command-line options:
(Options to csim)
- -v or -verbose - Verbose level.
Must be followed by an integer (separated by white-space)
indicating the verbosity level.
csim my_models.sim -verbose 2
The verbosity levels span from 0 to 501, where 0 is the minimum, and 1, 2, 3, 4, ... provide
progressively more detailed information. 0 is the default. The
higher the verbosity level, the more information is printed to the screen during pre-
processing. The higher levels are helpful when there are problems, since they give a
closer indication as to where the problem is. Each higher level includes the lower level printouts.
Summary of Verbosity levels:
0 - Default, minimal output.
1 - Leaves intermediate files.
2 - Shows major intermediate processing steps.
Shows variable and macro definitions.
3 - Shows variable/macro substitutions intermediate steps.
4 - Shows more detailed build steps. Additional checking reports.
6 - Messages about graph flattening, connecting links.
7 - Detailed summaries of links in processed graphs.
10 - Port list parsing checks.
11 - Attribute expansion printouts.
21 - Summaries of links in intermediate flattening steps.
41 - Arc data lists.
51 - Show macro expansions. List detailed geometry info.
101 - Variables listings.
501 - Attributes listings.
- -rigorous - This option causes the CSIM preprocessor to
consider topology checking with greater rigor. Specifically,
this option causes unconnected ports to be left unconnected and
considered an error.
(By default, unconnected ports would otherwise be automatically connected to
dev-null and only a small warning notice would be issued.)
This option is useful to prevent unintentional topological errors
from being over-looked. It causes the build-process to be stopped
on detecting an unconnected port, no simulation would be produced.
- -lenient - This option causes the CSIM preprocessor to
suppress warnings about inconsistent connections to instances of
common device types, -- otherwise known as Warning 47.
This situation often arises when the newer variable-port models
are used in several different places with different connections,
and it is not necessarily an error.
- -trace - This option causes the preprocessor to insert a
unique Debug xx printf between every line of your model-code
in the out.c file. The result is a detailed execution history
of every line of code executed when your simulation runs.
This is a heavy-duty debugging option that is useful, for example,
to isolate the exact sequence of lines of code executed within your
model prior to a crash. It complements the power of a debugger,
which may only show the line where the crash occurred, or in the unlikely
event that debugger interaction alters a crash condition.
- -count_threads - This options causes
CSIM to continually print a running tally of the number of threads
which are active. It is useful for understanding the number of
parallel threads that a simulation generates while running.
It provides insight into the changing memory resources required by
a given simulation. This option is intended for debugging and
exploration. It is also useful for exploring any thread-creation
limitations on a given platform. This option causes the simulation
to print an updated tally of the thread-count every time a new thread
is created. The thread-count is also decremented whenever a thread dies.
The active, peak, and total threads created are shown. At the end of
the simulation, when there are no more events, a summary of the
thread counts is shown in the textual output of the simulation.
- -not_abs - Not absolute pathname for graphical file.
By default, the absolute pathname for the graphical file, or top-level
diagram, is embedded in the simulation executable (sim.exe).
However, there are situations when you may wish for the pathname to
be relative, or not include the directory name. For example, when
you wish to move the directory, such as when transferring files to
another account or machine. By specifying -not_abs on the
csim command line, only the relative file name will be embedded.
You can then invoke the simulation as long as you are in the same
directory as the graphical file (top-level diagram file).
- -nongraphical - This option causes the CSIM preprocessor
to build a Non-Graphical simulation, or in other words, the
original text-only, command-line simulator. When you invoke the
textual simulation, you will not see the graphical control panel.
rather, you will see a textual simulation prompt:
Textual Command-line Simulator.
The text-based simulator is interactive, like the GUI-based version,
and expects commands to be typed at the simulation prompt, such as
run and quit.
The text-based simulator is useful for running simulations from
script-files, such as unattended batch runs that cannot be driven
from the GUI-based control panel. For non-interactive simulations,
direct commands from a script file, as in: sim.exe < script.com
> logfile & .
If you have custom graphical calls in your models, you may need to
conditionally compile them out by #if (GRAPHICAL_SIM==1) ... #endif.
- -nomarks - Option to report errors relative to the actual intermediate
out.c file line-number, rather than the original source (model) files.
By default, C-code errors are reported
from the C-compiler by their line-number in the source files by embedding trace-back
information in out.c so the C-compiler knows the original source file (xx.sim)
and original line numbers. This option removes the default markers, so compile-time and run-time errors
are then reported relative to the out.c file, which is sometimes more accurate.
- -nocomp - No Compile. This option forces the CSIM preprocessor
to preform just the preprocessing steps to yield an out.c file,
without attempting the invoke the C compiler. I.E. Skips compile.
- -update_params - Just update an existing simulation's attributes/parameters - without re-compiling.
This option saves time when you merely change attribute values of an existing simulation.
You can also access this feature from the GUI's Tools/Modify-Command/Update Parameters Only
Menu. (Attributes are conveniently changed from the GUI, and this feature facilitates their
application during iterative modify/simulate sessions.)
- -sbdt - This option causes the simulator to produce a summarization by device type.
It shows the numbers of instances for each model-type in the compiled simulation. They are listed in order of
most numerous to least numerous. This is handy to guide optimizations by indicating which models are most numerous,
and how many of each type are instantiated.
- -testbox - Replaces all device boxes with testbox type boxes for interactive routing-path displays
or other testing purposes. See Displaying Selected Routing Paths for further information on usage.
- -maxerrs xx - By default, the csim pre-processor exits after encountering 5 serious errors.
This option lets you set the maximum number of errors to display before aborting the build.
- -maxwarns xx - By default, the csim pre-processor allows 20 warnings without aborting a build.
This option lets you set the maximum number of warnings to tolerate before aborting the build.
- -compile_all - By default, the models (behavior code definitions) of device types, which are
not instantiated anywhere, are not included in out.c for compilation. This option causes all
model definitions to be included in out.c, even if they are not used. Useful for checking if all elements
of a library will compile without having a test-case that instantiates each one.
- -ncports - Force unconnected ports to be of type NC, explicitly Not-Connected, instead of
the default Null termination. Useful for finding inadvertent usage of unconnected ports.
By default, any unconnected ports on each box-instance are automatically
connected to Dev_Null. Dev_Null is a bit-bucket that absorbs all inadvertent output without complaining.
However, there are situations when you might wish to know about any unconnected ports which had otherwise escaped
notice, or that may contribute to memory leaks by not freeing tokens. This option causes all ports which
are not explicitly connected to anything, to be connected to NC, or explicitly Not-Connected type.
Any inadvertent output to an NC port causes the simulator to stop with a corresponding message.
Unlike null terminated ports, sending or receiving on an NC port stops the simulation
and raises a fatal error. See Finding or Suppressing Unconnected Ports.
- -o - Specify an alternative resulting output file name.
By default, CSIM produces a simulation executable named sim.exe .
This options enables you to specify an alternative simulation location and name.
Example: csim test.sim -o ../simulator.exe
- -help - Show a convenient command-option summary. (Added in version 4.10.)
II. Simulator Run-time Command-Line Options
(Options to Sim.exe)
- -batch - This option causes the simulator come up running.
Normally when you invoke the simulator, you have to type run (for the
textual simulator) or press Run (for the graphical simulator)
to start the simulation running. And when there are no more events, the
simulation prompt, or the graphical control panel, stay up until you
explicitly exit. The -batch option is intended for background (ie. batch)
processing, - when there is no one there to type run.
When invoked with this option, the simulation begins running immediately.
When there are no more events, the simulation exits automatically.
- -runto - Like -batch above, but causes continuous simulations to
start running immediately and exit at a specified time. The option must be
followed by the simulation duration.
Example: ./sim.exe -runto 700.5
- -quiet - Suppresses the customary "Welcome ..." and "Exiting" messages
that appear when staring and exiting the simulator. Useful for logged production
runs, or where sims are embedded within larger systems. Reduces the clutter
in log files, (when screen output is directed to a file).
- -core - This option causes the simulator to not catch
termination signals, but instead to exit with a core dump.
Termination signals occur from unusual events, such as when the
user presses ^C, or when an out-of-bounds memory access occurs.
By default, the simulator catches these events and traps to a
reduced capability mode, which enables some examination of the
simulation state, but does not allow resumption. Because
the simulation process does not exit, it does not produce a core-dump.
However, some users prefer a core-dump for post-mortem debugging.
Therefore, placing -core on the simulation command-line will
- -stacksize - This option enables you to specify a stack size for all
threads which is different than the default of 16384 bytes. The option must be
followed by the new stack size in bytes.
- -verbose - This option causes the simulator to print additional informational messages.
The option must be followed with an integer that represents the degree of verbose-ness.
The default value is 0. Currently the other valid value is 1 or greater.
- -help - Show convenient command-option summary. (Added in version 4.10.)