5 Appendix
Intel® Simics® Simulator User’s Guide  /  5 Appendix  / 

5.1 Old Script Parameters

This describes the old script parameter system, which is deprecated. See section 2.3.3 for the target parameter framework.

A Simics target script may declare its parameters and resulting values.

5.1.1 Declarations and Parameters

Script declaration blocks are optional, and have the form

  decl {
    declarations
  }

Such a block must come before any commands in the script file. Possible declarations are:

Whitespace (spaces, tabs, line breaks) is in general not significant unless specifically noted. Comments are allowed, starting with ‘#’ and running to the end of the line.

A parameter declaration takes the form

  param NAME : TYPE [= DEFAULT-VALUE]

where the default value is optional. Example:

  param ram_size : int = 8

This means that the variable $ram_size will be set when the script is executed, that it must be an integer, and that it will be 8 if not specified in any other way.

If there is no default value, then the parameter must be specified; otherwise, it is optional.

A script with a declaration block will only see the variables that have been declared as parameters. Other variables are hidden during the script’s execution and will re-appear when the script terminates.

5.1.2 Results

A script can return variables that it has set by declaring results:

  result NAME : TYPE

Example:

  result mac_address : string

It means that the script must set $mac_address before terminating, that it must be a string value, and that this variable is available to the caller. All other variables assigned to by the script are lost.

The same name can be used for both a parameter and a result.

5.1.3 Running Scripts

Parameters are given on the command line when running Simics:

$ ./simics myscript.simics ram_size=64

or as arguments to the run-script command:

simics> run-script myscript.simics ram_size = 64

or by setting the CLI variables before invoking the script:

simics> $ram_size = 64
simics> run-script myscript.simics

The -help command-line option will show all parameters of a script:

$ ./simics myscript.simics -help

From the Simics command line, the arguments for a file can be listed by using the help command:

simics> help myscript.simics
The original IBM PC XT from 1983, complete with
a full-height 10 MB fixed disk.

networking:
  mac_addr  -  string or NIL
...

It is also possible to use tab completion with the run-script command:

simics> run-script myscript.simics<tab>
  -local  -main-branch  ram_size =  cpu_freq =

5.1.4 Types

The following type specifications are allowed in the declarations of parameters and results. Each item in the list below describes the values permitted by the type.

File names may start with %simics% to force a look-up relative to the current project and Simics package path, or with %script% representing the script directory itself. (%script% is only allowed in default values.)

Complex or compound data types can often be packed into a string and unpacked and verified by the receiver in Simics. See documentation of the split-string command.

5.1.5 Documentation

Parameters can have documentation strings that are shown in the command-line. These consist of one or more lines that begin with an exclamation mark, immediately following the parameter. Example:

  param ram_size : int
  ! RAM size in megabytes.
  ! Note that Windows 95 needs at least 2 MiB to run.

The script itself can also be described in the same way, by putting a documentation string first in a declaration block:

  decl {
    ! Atari 2600 Video Game Console System
    param cartridge : string = "COMBAT"
  }

Documentation strings are written in a subset of the Simics JDocu mark-up language, which is XML-based. Most plain text can be written directly, but the symbols ‘<’ and ‘&’ must be written ‘&lt;’ and ‘&amp;’, respectively. Use blank lines to break paragraphs.

The following typographic elements exist:

5.1.6 Parameters from Other Scripts

Parameter declarations can be taken (imported) from other script files by using the declaration

  params from SCRIPT [except NAMES] [default NAME = VALUE ...]

All parameter (but not result) declarations from the given script will be used as if they had been declared in the importing script.

The optional except clause will exclude one or more comma-separated parameters.

Example: if the script a.simics contains:

  decl {
    params from "b.simics" except y
    param x : int
    result r : string
  }

and b.simics contains:

  decl {
    param y : int = 10
    param z : bool = TRUE
    result s : string
  }

then a.simics will behave as if it had been written:

  decl {
    param z : bool = TRUE
    param x : int
    result r : string
  }

The default value of imported parameters can be overridden by adding default clauses. Example:

  params from "hardware-setup.simics"
    default ram_size = 256
    default cpu_freq = 3.58e6

There is also a substitute declaration that is reserved for Simics internal use.

5.1.7 Parameter Groups

Parameters can be arranged into groups, to make them easier to browse when they are numerous. The declaration

  group "Networking"

will put all parameters that follow (in that file) into the group named “Networking”. Groups do not affect how parameters actually work; they only serve to make the presentation better.

5.1.8 Script Execution

When a script with a declaration block is run, interactively or from another script, this is what happens in detail:

  1. The script declaration is read and checked for errors. Imported parameters (“params from”) are resolved recursively.
  2. Actual parameter values are taken from, in order:
    1. The supplied arguments, if the script was started from a shell command, or from run-script.
    2. CLI variables.
    3. Default values from the script declaration.

An error is signalled if a parameter value is missing or has the wrong type.

  1. The current CLI variables, if any, are saved away and replaced with the script parameters having their initial values as described above.
  2. The command part of the script (below the declaration) is executed. If the script runs another script, this entire algorithm is used again.
  3. CLI variables corresponding to declared result names are retrieved. An error is signalled for missing results or ones with the wrong type.
  4. The saved CLI variables are restored, throwing away all current variables except for the declared results, which retain their values from the executed script.

5.1.9 Example

Here is a slightly longer example of a script declaration block.

# A machine from the good old days (?)
decl {
  ! The original IBM PC XT from 1983, complete with
  ! a <em>full-height</em> 10 MB fixed disk.

  # Note that comments (like this one) are distinct from doc strings.

  param ram_size : int = 256
  ! RAM size in KiB. Max is 640, which should be enough for anyone.

  param cpu_freq : float = 4.77
  ! CPU frequency in MHz.

  param video : {mda, cga, hercules} = cga
  ! Type of video card. mda &amp; hercules look best.

  group "networking"
  param mac_addr : string or nil = NIL
  ! Ethernet MAC address, or NIL if no Ethernet adapter present.

  param rom_file : file("*.bin") = "%script%/pc_xt_rom.bin"
  ! File containing the ROM image. Must be exactly 40 KiB.

  param rtc_time : string = "2015-02-01 13:37:00"
  ! Initial time and date of the real-time clock, on the form
  ! <tt>"YYYY-MM-DD HH:MM:SS"</tt>.

  # Include parameters declared in another file.
  params from "ms-dos.simics"

  # Override the default value of a parameter from that file
  default dos_ver = "2.11"

  result system : string
  ! Name of generated system component object.
}

# Here the actual script starts with commands to execute.
5 Appendix