5.2 Script Branches

5.2.1 Introduction to Script Branches

Script branches allow the user to write sequences of CLI commands that can be postponed, waiting for things to happen in the simulator, without breaking the sequential flow of commands. This is typically used to avoid breaking a script into many small sections, each run as a callback using Python.

A simple example of a script branch:

script-branch "script branch description (optional)" {
    echo "This is a script branch test - going to sleep."
    board.mb.cpu0.core[0][0].wait-for-step 10
    echo "Processor registers after 10 steps:"
    board.mb.cpu0.core[0][0].print-processor-registers
}

The example above will execute the first echo command at once, and then go to sleep waiting until the first 10 instructions (steps) have run. When the step counter for the processor has reached 10, the branch will wake up and run the next two commands, echo and print-processor-registers.

A big difference between script branches and the main script is that the main script (also called main branch) may be interrupted by the user pressing the stop button or typing Ctrl-C. The script branches are unaffected by such actions and can exist in the background, coexisting with any interactive command line use.

5.2.2 How Script Branches Work

When a script branch is started (using script-branch), it begins executing immediately, and runs until a wait-for-, command is issued. Execution is then resumed in the main script; i.e., there is never any concurrent activity. When some activity occurs that a script branch is waiting for, the branch continues executing once the currently simulated instruction is ready.

Note: Since only one branch can be active at once, any callback to Python from Simics will execute in the currently active branch, i.e., if a branch installs a callback, it is most likely that it will be called when the main branch is active.

5.2.3 Script Branch Commands

The following is a list of the commands related to script branches.

script-branch: Create a new script branch and start it.
list-script-branches: List all existing, but suspended, branches.
interrupt-script-branch: Interrupt a script-branch, causing it to exit.
create-script-barrier num_branches: Create a script barrier used to synchronize the execution of several script branches. The argument is the number of script branches that must enter the barrier before all of them are released.
wait-for-script-barrier barrier: Suspend branch until enough branches have reached the script branch barrier.
create-script-pipe: Create a script pipe, used to communicate data between script branches and also to synchronize them.
add-data-to-script-pipe pipe data: Add data (integer, string, floating point value or a list of any of those types) to the specified script pipe.
script-pipe-has-data pipe: Check if there is data to read from a script pipe.
wait-for-script-pipe pipe: Suspend branch until there is data to read on a script pipe. If there already is data in the pipe, return immediately. The return value is the first data item added to the pipe.
wait-for-log<conf_object>.wait-for-log [object] [substring] [type] [-re]: Wait until a log message is generated by an object or any object if the object variable is omitted. The substring and type can specify certain conditions.
wait-for-breakpoint breakpoint-id [-reverse] [-always]: Suspend branch until a specified breakpoint is triggered. If -reverse or -always is specified, this command is valid when the simulation is running in reverse.
<processor>.bp-wait-for-cycle cycle [-absolute] [-reverse] [-always]: Suspend branch until the processor has executed cycle number of cycles. If -absolute is specified, the branch will instead be suspended until the processor reaches the specified cycle in the simulation. If -reverse or -always is specified, this command is valid when the simulation is running in reverse.
<processor>.bp-wait-for-step step [-absolute] [-reverse] [-always]: Suspend branch until the processor has executed step number of steps. If -absolute is specified, the branch will instead be suspended until the processor reaches the specified step in the simulation. If -reverse or -always is specified, this command is valid when the simulation is running in reverse.
<processor>.bp-wait-for-time seconds [-absolute] [-reverse] [-always]: Suspend branch until the processor has executed seconds number of seconds. If -absolute is specified, the branch will instead be suspended until the processor reaches the specified time in the simulation. If -reverse or -always is specified, this command is valid when the simulation is running in reverse.
<int_register>.wait-for-register-read reg [-reverse] [-always]: Suspend branch until the register reg in the object implementing the int_register interface is read. Only registers that are catchable can be waited on. If -reverse or -always is specified, this command is valid when the simulation is running in reverse.
<int_register>.wait-for-register-write reg [-reverse] [-always]: Suspend branch until the register reg in the object implementing the int_register interface is written. Only registers that catchable can be waited on. If -reverse or -always is specified, this command is valid when the simulation is running in reverse.
<text-console>.bp-wait-for-string string: Suspend branch until string is printed on the text console.

5.2.4 Variables in Script Branches

Variable references in CLI are evaluated when accessed. This is important to remember when writing script branches, since some commands are executed when the branch has been suspended, and variables may have been changed. To make sure that CLI variables in script branches are untouched by other scripts, they should be made local.

The following example

script-branch "sample script branch" {
    $foo = 20
    board.mb.cpu0.core[0][0].wait-for-step 10
    echo "foo is " + $foo
}
$foo = 15
run

will produce the output foo is 15 while the following script will print foo is 20.

script-branch "sample script branch" {
    local $foo = 20
    board.mb.cpu0.core[0][0].wait-for-step 10
    echo "foo is " + $foo
}
$foo = 15
run

5.2.5 Script Branches and Reverse Execution

The script environment is used to control the simulated system and is not reversed itself when the simulation runs backwards. As a result, it is possible to write scripts that run the simulation both forward and backwards.

By default, the wait-for- script branch commands only wait for events to happen when the simulation is running forward and silently ignore them when reversing. The -reverse and -always flags, provided by most wait-for- commands, can be used to wait for events occurring in only the reverse direction or in both.

5.2.6 Script Branches and Multi-Threaded Simulation

Large system configurations can be split up over several cells where each cell runs in its own host thread to speed up simulation. Care must be taken when writing scripts in such sessions. If the simulation is stopped or paused, for example by a breakpoint, other cells than the one where the breakpoint occurred may be ahead or behind in simulated time. The difference in time between cells is limited by the minimum latency setting. The time where cells are stopped may also differ between runs of the same setup. To ensure deterministic behavior, a script stopping a simulation as result of some event should only access the cell where the event occurred. If the script needs to access the full configuration, i.e. also objects in other cells, then all cells have to be synchronized in time. The wait-for-global-time and wait-for-global-sync commands can be used to run until a point where all cells have synchronized.

5.2.7 Canceling Script Branches

It is possible to cancel a suspended script branch by interrupting it using the interrupt-script-branch command. Each branch has an ID associated that can be found using list-script-branches, and that is returned by the script-branch command.

$id = (script-branch "sample script branch" {
    wait-for-breakpoint $bp
})

...

simics> interrupt-script-branch $id
Command 'wait-for-breakpoint' interrupted.
Script branch 1 interrupted.

5.2.8 Script Branch Restrictions

There are a few things related to script branches that are discouraged or not allowed:

Starting and stopping the simulation should be avoided from script branches that run in sessions with interactive use, such as target start scripts. It is only in batch mode that controlling the simulation from script branches is acceptable, but then care should be taken to avoid script branches that conflict with each other.
A script branch may not define a new script branch nested inside itself.
The wait-for- command can not run in the main branch. The reason is that the main branch may be interrupted by the user pressing the stop button or Ctrl-C, while script branches and the wait-for- commands are unaffected by such actions.
The write-configuration command cannot be run while Simics is executing. This is a limitation that will be removed in a future Simics version, but for now the execution has to be stopped first. The following is an example that writes a checkpoint when the simulation reaches a login prompt, and then continues running. It assumes that a text-console called text_console_cmp0.con is used.
```
script-branch "create checkpoint" {
    board.console.con.bp-wait-for-string login
    stop
    write-configuration login.conf
    run
}
  
```
This is one of few exceptions to the rule that script branches should not start or stop the simulation.

5.1 Script Support in CLI 5.3 Targets and parameters