Plain command scripts, i.e. scripts without any script declaration block, execute in the same variable scope as the script calling run-command-file. The only exception are variables in the called script declared using the local keyword. Such variables are not available to the calling script. If the -local flag is supplied to the command, then the called script will run with its own copy of all global CLI variables. When the script has finished executing, the original variable values are restored.
CLI variable scoping is different for scripts starting with a script declaration block. Only variables declared in the decl {} block are available to such scripts and only return variables will be passed back to the calling CLI environment.
If run-command-file is issued in a script-branch and the -main-branch flag is specified, then the commands in the file will execute in the main script branch the next time it is scheduled. This allows the command file to define its own script branches for example. Note that scripts without a script declaration block will run in the global CLI variable environment and not within the script-branch scope. Scripts with a declaration block on the other hand will get its parameter set from the script-branch CLI environment at the time run-command-file is called.
If the script to run has declared parameters, then those parameters can be specified as arguments to run-command-file. Tab completion can be used to list the parameters available to a script.
run-command-file script-with-parameters.simics name = "abc" cycle = 20
This is identical to:
$name = "abc"
$cycle = 20
run-command-file script-with-parameters.simics
unset name cycle
It is not possible to pass parameters in this way to a plain script.
Python code can be included in a script by using the @ prefix. Multi-line Python statements only need @ on the first line. For larger sections of Python code, the use of run-python-file is encouraged instead.
Example Simics script:
# This is a Simics script
break 0xffc000 # set a breakpoint
run
echo "breakpoint reached"
run-command-file another-script.simics
If a command fails, the user presses Ctrl-C or stops the simulation from a GUI, the Simics script is interrupted.
run-command-file uses Simics's Search Path and path markers (%simics%, %script%) to find the script to run. Refer to The Command Line Interface chapter of the Simics User's Guide manual for more information.