Commands are invoked by typing them at the command line followed by their arguments. The synopsis part of a command documentation explains how to execute a command (you can see many examples in the reference manuals). Here are two examples:
Arguments starting with a hyphen are flags and are always optional. Flags can be more than one character long, so it is not possible to write -xy for -x -y. The order of the flags is not significant and they can appear anywhere in the argument list.
Arguments enclosed within square brackets are optional; in the example above, it is not necessary to specify cpu-name, but address is required. The last argument to command1 is either a size or a name, but not both. Such arguments are called polyvalues and can be of different types. Size and name are called sub-arguments.
If an argument is followed by three dots as the file argument in command2 it indicates that the argument can be repeated one or more times.
The type of the arguments; e.g., whether they are integers or strings, should be evident from their names. For example, size should be an integer and name a string if not documented otherwise.
Integers are written as a sequence of digits beginning with an optional
minus character for negative numbers. Hexadecimal numbers can be written by
prefixing them with 0x, octal numbers with 0o, and binary
numbers with 0b. Integers may contain "_" characters to make
them easier to read. They are ignored during parsing. For example:
simics> 170_000 170000 simics> 0xFFFF_C700 4294952704
Strings are written as is or within double quotes if
they contain spaces or begin with a non-letter. Within double quotes, a
backslash (\) is an escape character, which can be used to include
special characters in the string.
The supported escape sequences are the usual C ones: \n for
newline, \t for tab, \033 for the octal ASCII character 33
(27 decimal) escape, etc. \ followed by one, two or three octal
digits, or \x followed by exactly two hexadecimal digits is the
corresponding byte value.
\u followed by exactly four hexadecimal digits is the corresponding
Unicode character. CLI strings are in the current version of Simics always
stored in their UTF-8 encoding, which means that a single \u
character can be represented as several bytes in the CLI string. As this is
expected to change in a future version of Simics, do not rely on this
functionality.
simics> echo no_quotes_needed no_quotes_needed simics> echo "first line\nsecond line" first line second line simics> echo "Two As: \101 \x41, and a micro sign: \u00b5" Two As: A A, and a micro sign: ยต
C:\temp\file.txt. If the path contains spaces, it
has to be written within quote characters, and the directory
separators have to be written using double backslashes. This is due
to the way that the Simics command line uses backslashes to
generate special characters like newline and tab. Such a path
would look like "C:\\Users\\joe\\Documents\\file.txt".
simics> command1 -small board.mb.cpu0.core[0][0] 0x7fff_c000 14 -y simics> command1 0x7fffc000 foo simics> command1 -x "Pentium 4" 0x7fff_c000 -8 simics> command2 "/tmp/txt" "../bootdisk" floppy
In the first example cpu-name is passed as the string
board.mb.cpu0.core[0][0]
and size as the integer 14. In the second invocation
cpu-name has been omitted and name is set to the string
foo. The third example illustrated the use of a string containing a
space. In all command1 examples the address is set to the
hexadecimal value 0x7fffc000. command2 takes a list of
at least 1 string.
A few commonly used commands have aliases. For example, it is possible to write c for continue and si for step-instruction for example. Command aliases are documented with their corresponding command in the Simics Reference Manual.
Parenthesis can be used to break a command with its arguments across
multiple lines. In the console, the prompt will change to .......
for code spanning more than one line. The example shows that use case, as
well as how parenthesis are used to encompass expressions.
simics> (echo 10 ....... + (20 - 5) ....... + (max 4 7))
Simics tries to match the provided arguments in same the order as they appear in the synopsis. If the type of the next argument is identical to what is typed at the command line, the argument will match. If there is a mismatch and the argument is optional, the argument will be skipped and the next argument will be matched, and so on. If a mismatching argument is not optional, the interpreter will fail and explain what it expected. For polyvalues, the argument will match if one of its sub-arguments matches.
There are situations when this method is not sufficient.
For example, when two arguments both have the same type and are
optional, there is no way to know which argument to match if only
one is given. This is resolved by naming the arguments:
arg-name=value. For example command1 in
the example above can be invoked like this:
simics> command1 size=32 -y address = 0xf000 -small cpu-name=board.mb.cpu0.core[0][0]
Thus there is no ambiguity in what is meant and in fact this is the only way to specify a polyvalue with sub-arguments of the same type. Note also that named arguments can be placed in any order.
Many Simics commands accept configuration object references as
arguments. An object reference is simply a string which contains the
fully qualified name of the object. Simics provides a hierarchical
namespace for objects. The fully qualified name is similar to a file
system path, but with the parts separated by dots. For example, the
fully qualified name of
cpu0 in the system0 namespace is
system0.cpu0.
Configuration objects (such as devices or CPUs) that define user commands usually place them in a separate namespace. The namespace is the fully qualified name of the object. Interfaces may also define commands, in which case all objects implementing these interfaces will inherit the commands in their own namespace.
Namespace commands are invoked by typing the fully qualified name of the object, followed by a dot and the command name: system.component.object.command, e.g.,
simics> system0.board0.cache0.print-status
All namespace commands are listed in the Simics Reference Manual under the class or interface they belong to.
When using large configurations with a hierarchical structure of components and objects it can be inconvenient to type the fully qualified name all the time when invoking namespace commands. You can than use the change-namespace command (alias cn) to set a current namespace just like navigating in a file system with the cd command. From the current namespace you can refer to objects with a relative name, for example:
simics> cn system0.board0 simics:system0.board0> cache0.print-status
Note that the Simics prompt changes to reflect the new position in the hierarchy. You can only change the current namespace to other components. It would have been illegal to do:
simics> cn system0.board0.cache0 system0.board0.cache0 is not a component
Cache0 is not a component, it is an object located in the cache0 slot (see 6.4 and 6.5 for more information on how objects are named and referenced).
To go "up" one level in the hierarchy you can type cn ..:
simics:system0.board0> cn .. simics:system0>
You can still refer to other components relative to the root by writing a dot before the fully qualified name, e.g.:
simics:system0> .system1.cpu0.ptime processor steps cycles time [s] system1.cpu0 14545 14545 0.000
The command current-namespace is provided to get the current namespace and can be used in scripts to save a location in a CLI variable:
simics:system0> current-namespace .system0 simics:system0> $location = (current-namespace) simics:system0> cn .. simics> cn $location simics:system0>
See section 5 for more information on Simics scripting and CLI variables.
The CLI allows expressions to be evaluated, for example:
print -x 2*(0x3e + %cr0) + %dx
The precedence order of the operators is as follows (highest first):
$ | variable access |
% | register access |
[] | list indexing |
-> | attribute access |
pow | power of |
~ | bitwise not |
*, /, % | multiplication, division, modulo |
+, - | addition, subtraction |
<<, >> | left, right shift |
& | bitwise and |
^ | bitwise xor |
| | bitwise or |
<, <=, ==, !=, >=, > | comparison |
not | boolean not |
and | boolean and |
or | boolean or |
Parentheses can be used to override the priorities. Commands which return values can also be used in expressions if they are enclosed within parentheses:
print -x (board.mb.cpu0.core[0][0].read-reg cr0)
Values can be saved in variables for later use. You set a variable by simply giving an assignment command such as $var = 15. You can also store a command in a variable such as $my_read_reg = board.mb.cpu0.core[0][0].read-reg which is different from storing the return value from a command $value_cr0 = (board.mb.cpu0.core[0][0].read-reg cr0).
running> prompt or the stop button in Simics Control
window.