4 Command Line Interface (CLI)

This section focuses on some practical information related to the use of the CLI. Particularly, the following information is presented:

• a brief introduction to the CLI
• how to use command line completion, also known as tab completion
• how to use the help command
• where to find more information about the CLI

This section doesn’t cover all available CLI commands, but here are some examples of what can be done with commands:

• load a target
• run and stop the simulation
• inspect the state of target machines
• set breakpoints and tracepoints
• save and roll back to checkpoints

4.1 Introduction

As a short introduction to the functionality of the CLI:

• The CLI allows running (and combining):
  • CLI commands (which also can be run from Python)
  • Python code (prefixed with @ or in python-mode)
  • Host shell commands (prefixed with ! or shell)
  • Most of the Intel Simics simulator interfaces can be executed as Python functions
• Each executed command is saved to a command history.
• The state of objects can be inspected by accessing attributes, commands, and interfaces.
• The CLI has variables which are prefixed with $. The $ prefix is used both when assigning and retrieving value (for example $var = 1 or echo $var).
• There are built-in command aliases, but it's also possible to create custom aliases with the alias command.
• Comments are created with # (# this is a comment).

4.1.1 CLI Prompts

When launching the simulator (simics.bat on Windows or ./simics on Linux), the CLI is started automatically. The CLI has several prompts, but here are most important.

• Simulation stopped (default)
  The default prompt is simics>. This also indicates that the simulation is not running.
• Simulation running
  When the simulation is running, the prompt changes to running>. Note that most commands (such as stop) can be issued while the simulation is running.
• Python Mode
  The simulator has a Python mode for using Python interactively. When running the python-mode command, the prompt changes to simics>>>.

4.1.2 Keyboard Shortcuts

These are some shortcuts that may be useful:

• Control-C
  A running simulation (running>) can be interrupted with Control-C, as an alternative to typing stop.
• Arrow up
  Put the previous command (from the command history) on prompt without having to re-type it. To see older commands, press Arrow up again.
• Control-R
  Search the command history by first pressing Control-R and then type a substring to search for in the command history. Press Control R again to see the next matching.
• Tab
  The Tab key is used for command line completion.

4.2 Command Line Completion

To simplify interactive use, the CLI implements command line completion, also known as tab completion. The CLI can complete commands, arguments, file names, and some other entities. Let’s see how command line completion works for the load-target command:

• Launch the simulator.

• Use tab-completion to complete the command load-target by typing only load-t and then press tab:

  simics> load-t # press tab once to complete command
  simics> load-target
  

• To get further with command line completion, press the tab key twice. The CLI will print the list of parameters and flags which can be passed to the load-target command:

  simics> load-target # press tab twice to get arguments
  namespace =  preset =  preset_yml =  presets =  target =
  simics> 
  

  Please note that we had to press the tab key twice. It is because the command completion system could not unambiguously complete the command after the tab key was pressed once. After the tab key is pressed again, the command completion system shows all possible completions.

• Let’s proceed with our current command line entry and expand arguments that begin with the letter t. Enter t followed by the tab key and observe that the target argument appears:

  simics> load-target t # press tab to expand the 'target' argument
  simics> load-target target = 
  

• We would like to load the target qsp-x86/firststeps. The command line completion can help with this. With the current command entry, type q and then tab once to expand all targets that begin with q.

  simics> load-target target = q # press tab once to complete qsp-x86
  simics> load-target target = "qsp-x86/
  

• Now type f and then tab to expand the target named qsp-x86/firststeps:

  simics> load-target target = "qsp-x86/f # press tab to complete target name
  simics> load-target target = "qsp-x86/firststeps"
  

• We now have the complete command for loading the qsp-x86/firststeps target. Pressing enter to load this target machine:

  simics> load-target target = "qsp-x86/firststeps"
  "firststeps"
  simics>
  

We have now used command line completion to load the qsp/firststeps target.

4.3 The help command

The simulator documentation can be accessed in the CLI with the help command. The help command provides access to the documentation for:

• commands
• scripts
• objects
• classes
• modules
• attributes
• API functions

To try the command, enter the following command to see the documentation for the load-target command:

simics> help load-target
Command load-target

   Synopsis
      load-target "target" ["namespace"] ["preset"|presets|"preset_yml"]
...

To get the documentation for any command just run the help command specifying the command you are interested in:

simics> help <command-of-interest>

More information on the help command can be obtained by reading the documentation for the help command itself:

simics> help help
Command help

   Alias
      h, man

   Synopsis
      help ["topic"]
...

The help-search command allows to search the documentation for a particular string. Here is a sample usage of the help-search command:

simics> help-search python
The text 'python' appears in the documentation
for the following items:

Command        %
Command        <bp-manager.log>.break
Command        <bp-manager.log>.run-until
Command        <bp-manager.log>.trace
...

4.4 Further Reading

More information about the CLI can be found in Simics User's Guide, section The Command Line Interface.