8.4 Snapshots (in-memory) 8.6 Virtual disks

8.5 Writing Custom Scripts

In addition to interactive use, the Intel Simics simulator can also run scripts with CLI commands and/or Python code. This section provides some examples on how to write custom scripts and run them.

When the situation occurs that the same commands have to be repeated, it is recommended to instead put these in a script.

8.5.1 Create and Run a Script

Here we describe how to create and run a simple script. We will create a script in the project directory and run it.

8.5.1.1 Create the script

Open an editor, and copy/paste/save the below lines to first.simics in the project folder.

echo "Script is running"

8.5.1.2 Run the script

This can be done in two ways:

Launch the simulator with the script (using -q to get less output).

On Windows

c:\simics\project>simics.bat -q first.simics
Script is running
simics>

On Linux

project>./simics -q first.simics
Script is running
simics>

With --batch-mode launch option, the script will simulator will exit after running the script (example on Linux).

project>./simics -q --batch-mode first.simics
Script is running
project>

From simulator CLI:

simics> run-script first.simics
Script is running

8.5.2 CLI Script

Let's say we repeatedly input the following lines on the CLI:

$target = "qsp-x86/firststeps"
$run_time = 0.2

echo "Load the target " + $target + " and run " + $run_time + " seconds"
load-target "qsp-x86/firststeps"
run-seconds $run_time
ptime

To speed up the turnaround time, we can put these line in a script, and run this script.

Create the script run-target.simics with the above commands, in the project folder.

Run the script run-target.simics and verify that the output from the last command, ptime is:

Load the target qsp-x86/firststeps and run 0.2 seconds
┌────────────────────────┬─────────┬─────────┬────────┐
│       Processor        │  Steps  │ Cycles  │Time (s)│
├────────────────────────┼─────────┼─────────┼────────┤
│board.mb.cpu0.core[0][0]│387346147│400000000│   0.200│
└────────────────────────┴─────────┴─────────┴────────┘

8.5.3 Python calling CLI commands

This is an example of a Python script which does essentially the same thing as CLI Script example, and shows different ways of calling CLI commands from Python.

Create the script run-target.py with the below contents:

import cli
import simics

target = "qsp-x86/firststeps"
run_time = 0.2

cli.run_command(f'echo "Load the target {target} and run {run_time} seconds"')
simics.SIM_load_target(target, None, [], [])
cli.global_cmds.run_seconds(seconds=run_time)
cpu = cli.current_cpu_obj()  # get the current CPU object
print(cpu.cli_cmds.ptime())

The target is loaded by calling the simulator API function simics.SIM_load_target which corresponds to what is done with the load-target command.

Run the script run-target.py and verify that the output is:

Load the target qsp-x86/firststeps and run 0.2 seconds
[[<the x86QSP1 'board.mb.cpu0.core[0][0]'>, 387346147, 400000000, 0.2]]

Note that it's the return value of ptime is printed.

In run-target.py two ways of running CLI commands from Python are demonstrated:

Using cli.run_command
Using Python functions that wrap CLI commands
These functions have underscore (_) where the command has dashes (-). Also, the name space location depends on if the command is global or if it is accessed from an object:
- global commands - Global commands are named cli.global_cmds.*, for example cli.global_cmds.run_seconds(seconds=run_time).
- object commands - Object commands are named <object>.cli_cmds.*, for example cpu.cli_cmds.ptime().

The function arguments are documented with the Python help system. Note that the function arguments can be different from the command arguments. For the full command documentation, use the CLI help command.

Examples of viewing help text for the board.log-group command:

Get the full command documentation.

simics> help board.log-group
Command <conf_object>.log-group

   Synopsis
      <conf_object>.log-group [-enable|-disable] ["log-group"] [-r]
      log-group [object] [-enable|-disable] ["log-group"] [-r]

   Description
      Enable (-enable) or disable (-disable) a log-group, or show whether it is 
...

Get the Python function arguments.

simics> @help(conf.board.cli_cmds.log_group)
Help on function log_group in module cli_impl:

log_group(*args, **kw)
    Function to run the '<conf_object>.log-group' command.
    No positional parameters are accepted.
    The following keyword-only parameter(s) are accepted:
    - _enable: optional, flag, default value - (flag_t, 0, None)
    - _disable: optional, flag, default value - (flag_t, 0, None)
    - log_group: optional, string, default value - None
    - _r: optional, flag, default value - False...

Note in the above example:

The object board is accessed from Python using conf.board.
The CLI command name log-group has the corresponding function named log_group (with underscore).

8.5.4 CLI Script mixed with Python

Here follows another example script, which demonstrates scripting that combines CLI commands and Python:

Create the script mix.simics with the below contents:
```
@import cli
@import conf
@import simics

@def log_cli_var(name):
    print(f'Log the value of "{name}" from Python')
    contents = cli.simenv[name]
    simics.SIM_log_info(1, conf.sim, 0, f'{name} = {contents}')

$a = 1
@log_cli_var("a")
@b = cli.simenv.a + 1
expect ($a + 1) `b`
```
In the script the following is demonstrated:
1. Calling Python code using @.
2. Access CLI variables from Python using cli.simenv.
3. Access Python variables from CLI using backticks (`b`).
4. Using the simulator object sim from Python by prepending conf. to the object name (the sim object is always present).
5. Calling of the simulator API function simics.SIM_log_info.
Run the script mix.simics and verify that the output is:
```
Log the value of "a" from Python
[sim info] a = 1
```

For further information about CLI, see the Simics User's Guide.

8.4 Snapshots (in-memory) 8.6 Virtual disks