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.
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) are 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.
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.
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 and a 5 1/4' floppy drive.
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 =
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.
int
An integer. Integers can be written in decimal, hex (0x1e3) or binary (0b1011).
float
A floating-point number or integer.
string
Any string, like "Miss Piggy". Quotes can be omitted for word-like strings, like x86_64.
bool
Either TRUE or FALSE.
file(PATTERN)
A string that names an existing file. PATTERN is a (double-quoted) string with a pattern that suggests what file names are acceptable, such as "*.exe". The pattern is just a hint for the user interface; any existing file will be accepted. Use file("*") to indicate no particular file name preference.
File names may start with %simics% to force a look-up relative the current project and Simics package path, or with %script% representing the script directory itself. (%script% is only allowed in default values.)
{VALUE1, VALUE2, ...}
One of the enumerated values (which each can be of any type).
Example: {1, "apple pie", 8.25}
TYPE or nil
A value that matches TYPE or is the value NIL.
Example: string or nil will match "abc" or NIL, but not 1.3.
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.
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 '<' and '&', respectively. Use blank lines to break paragraphs.
The following typographic elements exist:
<tt>TEXT</tt><em>TEXT</em><param>TEXT</param>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.
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.
When a script with a declaration block is run, interactively or from another script, this is what happens in detail:
The script declaration is read and checked for errors. Imported parameters ("params from") are resolved recursively.
Actual parameter values are taken from, in order:
run-script.An error is signalled if a parameter value is missing or has the wrong type.
The current CLI variables, if any, are saved away and replaced with the script parameters having their initial values as described above.
The command part of the script (below the declaration) is executed. If the script runs another script, this entire algorithm is used again.
CLI variables corresponding to declared result names are retrieved. An error is signalled for missing results or ones with the wrong type.
The saved CLI variables are restored, throwing away all current variables except for the declared results, which retain their values from the executed script.
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 and a 5 1/4" floppy drive.
# 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 & 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.