Appendix H - CSIM Preprocessor and Simulator Command-Line Options

• I. Build-time options - CSIM Preprocessor.
• II. Run-time options - Sim.exe Simulator.

I. CSIM Build-Time Options

• -v or -verbose - Verbose level. Must be followed by an integer (separated by white-space) indicating the verbosity level. For instance:

  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:

  Sim>

  See: 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

• -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 enable core-dumps.

• -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.)