Commands are invoked by typing them at the command line followed by their arguments. The synopsis part of a command documentation (you can see many examples in the Simics Reference Manual) explains how to call a command. 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. address, on the other hand, 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., if 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 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.
Here are some possible invocations of the commands above:
simics> command1 -small cpu0 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 cpu0 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.
Simics tries to match the provided arguments in same 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 however 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=cpu0
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.
Configuration objects (such as devices or CPUs) that define user commands usually place them in a separate namespace. The namespace is the name of the object. Interfaces may also define commands, in which case all objects implementing these interfaces will inherit of the commands in their own namespace.
Namespace commands are invoked by typing the name of the object, followed by a dot and the command name: object.command, e.g.,
simics> cache0.print-status
All namespace commands are listed in the Simics Reference Manual under the class or interface they belong to.
The CLI allows expressions to be evaluated, for example:
print -x 2*(0x3e + %g7) + %pc
The precedence order of the operators is as follows (highest first):
| $ | read Simics variable |
| % | get register value |
| [] | variable indexing |
| -> | attribute access |
| pow | power of |
| ~ | bitwise not |
| *, / | multiplication, division |
| +, - | 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 (cpu0.read-reg g7)
Values can be saved in variables for later use. You set a variable by simply giving an assignment command such as $var = 15.
Any command which causes the simulation to advance can be interrupted by typing control-C. The simulator will gracefully stop and prompt for a new command. If Simics hangs for some reason, possibly due to some internal error, you can usually force a return to the command line by pressing control-C two or more times in a row.