2.2 The Command Line Interface

The Simics Command Line Interface (CLI) is an advanced text based user interface with built-in help system, context sensitive tab-completion, and scripting support (both built-in and for use with Python). It is provided as part of Simics.

If Simics graphical user interface (GUI) is used, the CLI is accessible via the Simics Control window (Tools → Command Line Window). When running Simics without a GUI, the CLI is accessible directly at the command line/shell where Simics is started.

2.2.1 Invoking Commands

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

Here are some possible invocations of the commands above:

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

2.2.1.1 How are Arguments Resolved?

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.

2.2.1.2 Referring to Simics Objects

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.

2.2.1.3 Namespace Commands

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 manuals for 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 2.4.4 and 2.4.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 2.3 for more information on Simics scripting and CLI variables.

2.2.1.4 Expressions

The CLI allows expressions to be evaluated, for example:

simics> print -x 2*(0x3e + %cr0) + %dx

The precedence order of the operators is as follows (highest first):

Parentheses can be used to override the priorities. Commands which return values can also be used in expressions if they are enclosed within parentheses:

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

2.2.1.5 Interrupting Commands

2.2.2 Tab Completion

The command line interface has a tab-completion facility. It works not only on commands but on their arguments as well. The philosophy is that the user should be able to press the tab key when uncertain about what to type, and Simics should fill in the text or list alternatives.

For example com<tab> will expand to the command beginning with com or list all commands with that prefix, if there is not a unique such command. Similarly, disassemble <tab> will display all arguments available for the command. In this case Simics will write:

address =   bytes =   count =   cpu-name =

to indicate that these alternatives for arguments exists. Typing disassemble cp<tab> will expand to disassemble cpu-name = and a further tab will fill in the name of the CPU that is defined (or list all of them).

2.2.3 Help System

The most useful Simics commands are grouped into categories. To list these categories, just type help at the command prompt. The list should look like this:

simics> help
[...]
Type help category to list the commands for a specific category. Here is a list
of command categories:

  Breakpoints    Disks      Inspection       Modules      Probes      Registers
  CLI            Execution  Instrumentation  Networking   Processors
  Components     Files      Logging          Notifiers    Profiling
  Configuration  Help       Matic            Parameters   Python
  Debugging      Image      Memory           Performance  Recording
[...]

Note that since Simics's configuration can change between sessions and even dynamically through the loading of modules, the list of commands and command categories may look different.

Type help category for a list of commands, e.g., help Help will list all commands belonging to that category:

simics> help category:Help
Commands available in the "Help" category:

api-help           get API help
api-search         search API help
copyright          print full Simics copyright information
get-command-args   get list of command arguments
help               help command
help-search        search for text in documentation
license            print Simics license
list-attributes    list all attributes
list-commands      list CLI commands
release-notes      display product release notes
version            display Simics version

Type help command to print the documentation for a specific command.

The help command can do much more than printing command documentation: it gives you access to nearly all Simics documentation about commands, classes, modules, interfaces, API types and functions, haps and more according to the configuration loaded in the simulator. All documentation is also available in the reference manuals.

Here are some more examples of usage of the help command:

simics> help print-time
[... print-time command documentation ...]

simics> help board.mb.cpu0.core[0][0].disassemble
[... <processor_info>.disassemble command documentation ...]

simics> help <processor_info>.disassemble
[... <processor_info>.disassemble command documentation ...]

simics> help board.mb.cpu0.core[0][0]
[... <x86QSP1> class documentation ...]

simics> help x86QSP1
[... <x86QSP1> class documentation ...]

simics> help processor_info
[... <processor_info> interface documentation ...]

simics> help board.mb.cpu0.core[0][0].freq_mhz
[... <x86QSP1>.freq_mhz attribute documentation ...]

simics> help x86QSP1.freq_mhz
[... <x86QSP1>.freq_mhz attribute documentation ...]

simics> help Core_Exception
[... Core_Exception hap documentation ...]

simics> help SIM_get_mem_op_type
[... SIM_get_mem_op_type() function declaration ...]

simics> help x86-intel64-turbo
[... x86-intel64-turbo module documentation ...]

When a name matches several help topics (for example, a command and an attribute, or a module and a class), help will print out the first topic coming in this order: command categories, commands, classes, interfaces, haps, modules, attributes, API functions and symbols. It will also inform you at the end of the documentation output that other topics were matching your search:

simics> load-module NS16450
simics> help NS16450
[... NS16450 class documentation ...]
     
Note that your request also matched other topics:
  module:NS16450

If you type help module:NS16450, the module documentation will be printed instead:

simics> help module:NS16450
[... NS16450 module documentation ...]

You can use specifiers like module: or class: at any time. It will also allow the help command to provide you with better tab-completion, since only items in the selected category of documentation will be proposed. The following specifiers are available: object:, class:, command:, attribute:, interface:, module:, api:, hap: and category:.

The help-search command can search for keywords in the documentation provided by help. Type help-search keyword to get a list of all documentation topics matching this keyword. Its alias is apropos, named after the UNIX command-line utility which has similar behavior.

simics> help-search step
The text 'step' appears in the documentation
for the following items:
 
Command        <cycle>.cycle-break
Command        <cycle>.cycle-break-absolute
Command        <cycle>.print-time
Command        <cycle>.wait-for-cycle
Command        <cycle>.wait-for-time
[...]
Interface      step_info

simics> apropos step
[... yields the same output ...]

2.2.4 Simics's Search Path

Many Simics commands will look up files based on the current directory. When Simics is launched from the command line, the current directory is the current directory of the shell Simics was launched from. When Simics is launched by double clicking its icon, the current directory is the project directory. This may be impractical when writing scripts or building new configurations, so Simics provides two features to ease directory handling:

• Simics recognizes some special path markers that are translated before being used:

  • %simics%
    This path marker causes Simics to locate the file (following the marker) in the project directory or in any of the installed packages. If not found in the project directory, Simics will start searching in the newest package, i.e. the one with the highest build-id number.

    For example, %simics%/scripts/foo.simics could be translated to:

    • Windows:
      C:\Program Files\Simics\Simics 6\Simics 6.0.1\scripts\foo.simics
    • Linux:
      /opt/simics/simics-6/simics-6.0.1/scripts/foo.simics

    Note that if you change the version of Simics, %simics% will change as well, so you should use it to refer only to files that you know are present in all Simics versions. Notice also that %simics% has no meaning if no file can be found. You can use the command lookup-file to find out how the path will be translated.

  • %script%
    Translated to the directory where the currently running script is located. A possible usage is to let a script call another one in the same directory, independently of what the current directory is.

    For example, if the directory baz contains the scripts foo.simics and bar.simics, even if the user uses Simics with another current directory, it will be possible for foo.simics to call bar.simics by issuing the command:

    simics> run-script %script%/bar.simics
    

  %simics% and %script% are always translated to absolute paths, so they never interact with the next feature, called Simics's search path. One consequence is that they must always be used in double quotes "%simics%/targets/qsp-x86/images" to ensure that escaped characters such as spaces are used correctly.

• Simics has a list of paths called Simics's search path where files will be looked up when using some specific commands (among others, load-binary, load-file and run-script) and a number of classes (such as the image class and the tftp server implementation in the service-node). The file is first looked up in the current directory, then in all entries of Simics's search path, in order.

  • Windows:
    Let us assume for example that Simics's search path contains
    C:\Users\joe\scripts\
    and that the current directory is
    C:\Users\joe\project\
    If the command:

    simics> run-script test/start-test.simics
    

    is issued, Simics will look for the following files to run:

    1. C:\Users\joe\project\test\start-test.simics
    2. C:\Users\joe\scripts\test\start-test.simics

  • Linux:
    Let us assume for example that Simics's search path contains
    /home/joe/scripts/ and that the current directory is /home/joe/project. If the command:

    simics> run-script test/start-test.simics
    

    is issued, Simics will look for the following files to run:

    1. /home/joe/project/test/start-test.simics
    2. /home/joe/scripts/test/start-test.simics

Simics's search path can be manipulated using the add-directory, clear-directories and list-directories commands. Simics's search path is also used when looking for image files belonging to checkpoints or new configurations. This is described in section 2.4.2.3.1.

Remember that setting a CLI variable to a path with %simics% or %script% does not in itself evaluate the path marker. This means that the path marker may evaluate to another directory than is anticipated. The following two lines evaluate quite differently:

simics> $just_a_string = "%script%/images/my_image"
simics> $absolute_path = (lookup-file "%script%/images/my_image")

The first CLI variable reads the given text and may evaluate to wherever. The second variable is evaluated locally and reads the absolute path for the my_image file that is located nearby the script.

2.2.5 Using the Pipe Command

The pipe command lets you send the output of a Simics command to a shell command through a pipe:

simics> pipe "help" "grep Tracing"

This will run help (which lists all Simics commands categories) and send its output to the standard input of the grep Tracing process. grep will discard all lines not containing "Tracing" and forward the rest to its standard output, which will be printed on the Simics terminal.

The pipe command can be used to send all the output of a command to a file:

simics> pipe "stepi 1000" "cat > trace.txt"

Or you can use it to view information using the shell command more:

simics> pipe "print-processor-registers -all" more

Note that you have to enclose both the Simics command (the first argument) and the shell command (the second argument) in double quotes if they contain whitespace or other non-letter characters.

2.2.6 Running Shell Commands

The ! Simics command can be used to run command line commands. It will take everything after the ! sign and run it in a command interpreter (the current shell, on Linux, and cmd.exe, on Windows). For example:

2.2.7 Command-line Keyboard Shortcuts

The Simics CLI supports two modes with different keyboard shortcuts: Windows and GNU Readline style. Most shortcuts are the same in both modes but there are some minor differences between the two as listed in the following table. The mode can be set in the preferences, via the GUI or the CLI:

simics> prefs->readline_shortcuts = TRUE
simics> save-preferences

The command line in Simics can be accesses in several different ways. The shortcuts are supposed to be the same everywhere, but some terminals and telnet clients may not forward certain key combinations to Simics. A typical example where keyboard shortcuts do not work properly is the Cygwin terminal on Windows hosts. To run Simics in command-line mode on Windows, a standard Windows command line console is recommended.

2.2.7.1 List of Shortcuts

The following is a list of all keyboard shortcuts supported in Simics, where some are marked as Windows or GNU Readline only.
Move Shortcuts

Edit Shortcuts

History Shortcuts

Completion Shortcuts

Transpose Shortcuts

Undo Shortcuts