cli
import cli
The cli module contains the API for interacting with the Simics Command Line Interface.
class cli.arg(
handler,
name='',
spec='1',
default=None,
data=None,
doc='',
expander=None,
pars=[]
)
Class defining a command argument.
Define a CLI command argument when using new_command. A complete explanation of new_command and arg is available in Simics Model Builder User's Guide, in the Adding New Commands section.
class cli.bool_t(true_str='TRUE', false_str='FALSE')
Generator function for boolean arguments.
A boolean argument accepts the strings "TRUE" and "FALSE", as well as boolean integers (that is, the values 0 and 1). In addition, if the optional strings true_str and false_str are given, the boolean argument will accept them as well. The argument passes True or False to the command function depending on which string (or value) was given.
class cli.CliError
Exception used for errors in CLI commands.
This exception can be raised whenever a command can not complete successfully.
class cli.command_quiet_return(value)
Suppresses interactive messages from commands.
Use this class to return from a command that returns a value but should not print anything when used interactively.
value should either be the value returned, or a function taking no arguments that returns the actual value.
Note that value can only be of types directly supported by CLI.
cli.command_quiet_return.is_quiet()
Should return True if no message or return value should be printed when used interactively.
class cli.command_return(message=None, value=None)
Returns interactive messages from commands
Use this class to return from a command that returns one value value but (may) print something else message when run interactive.
message and value may both be functions that take no arguments and return the message (a string) or a value, respectively.
If it is a function, message is only evaluated if needed.
Note that value (or, when a function, its return value) can only be of types directly supported by CLI.
cli.command_return.is_quiet()
Should return True if no message or return value should be printed when used interactively.
cli.command_return.is_verbose()
Should return True if a no message or return value should be printed even when used non-interactively.
class cli.command_verbose_return(message=None, value=None)
Always print return messages from commands.
Use this class to return from a command that returns a value or message that should be printed even when used non-interactively, but not when used in an expression.
The value and message parameters are identical to the same as for cli.command_return.
cli.command_verbose_return.is_verbose()
Should return True if a no message or return value should be printed even when used non-interactively.
class cli.filename_t(
dirs=False,
exist=False,
simpath=False,
checkpoint=False,
keep_simics_ref=False
)
Generator function for filename arguments.
If the dirs argument is false (which is default), no directories will be accepted. The exist flag, when set, forces the file to actually exist. If simpath is true, files will be checked for existence using SIM_lookup_file(), searching the Simics search path. simpath implies exist. On Windows, if Cygwin path conversion is performed (see SIM_native_path() for details), the filename will be converted to host native format. The checkpoint flag will constrain the argument to checkpoints, and treat existing checkpoints as opaque entities.
cli.get_available_object_name(prefix)
Return a non-allocated object name.
Return an object name suitable for creating a new object (i.e., that has not been used yet) by adding a suffix to prefix.
cli.global_cmds
Namespace with functions to run global CLI commands
The namespace provides wrapper Python functions to run global Simics CLI commands. A wrapper function name is usually the same as a name of the command it executes with hyphens replaced with underscores. The parameters of the wrapper functions are the same as of the corresponding command (again, with hyphens replaced with underscores). Command flags (the names of the corresponding function parameters start with an underscore) could be passes as Python Boolean values. In the rare cases that a wrapper function name or a wrapper function parameter name turns out to be a Python keyword, the _cmd suffix is added to the wrapper function name and the function parameter gets the _ suffix. Wrapper functions return the value returned by the command which they execute.
Please consult the docstring of the wrapper function and the respective command documentation for the information about function arguments and the returned value.
cli.int16_t
Accepts any unsigned integer that fits in 16 bits, modulo-reducing values outside into that range.
cli.int32_t
Accepts any unsigned integer that fits in 32 bits, modulo-reducing values outside into that range.
cli.int64_t
Accepts any unsigned integer that fits in 64 bits, modulo-reducing values outside into that range.
cli.int8_t
Accepts any unsigned integer that fits in 8 bits, modulo-reducing values outside into that range.
cli.integer_t
Accepts any unsigned integer that fits in 64 bits, modulo-reducing values outside into that range.
cli.interactive_command()
Check if current command is run interactively.
Returns true if the current command was run interactively by the user and false if run from a script. This function may only be called by CLI commands.
cli.ip_port_t
Accepts integers that are valid IP port numbers (that is, integers between 0 and 65535 inclusive).
cli.new_command(name, fun, args=[], **kwargs)
Define a new CLI command.
A complete explanation of new_command and its parameters is available in Simics Model Builder User's Guide, in the Adding New Commands` section.
cli.new_info_command(cls, get_info, ctype=None, doc=None)
Define a new info command.
Define a new info command for a given configuration class. cls is the class for which the infocommand should be registered. get_info is a function returning the information to be printed. get_info() should return a data structure of the following kind:
[(SectionName1, [(DataName1.1, DataValue1.1),
(DataName1.2, DataValue1.2), ...]),
(SectionName2, [(DataName2.1, DataValue2.1),
(DataName2.2, DataValue2.2), ...]),
...]
Each section will be printed separately. Each piece of data will be printed on one line. If no sections are necessary, just provide None as the only section’s name, followed by the list of data.
cli.new_status_command(cls, get_status, ctype=None, doc=None)
Define a new status command.
Define a new status command for a given configuration class. cls is the class for which the status command should be registered. get_status is a function returning the information to be printed. get_status() should return a data structure of the same kind as in cli.new_info_command.
cli.nil_t
Nil argument.
Accepts NIL, zero or the empty string, and passes None to the command function. Not so usable by itself, but see e.g. cli.poly_t.
cli.number_str(val, radix=None, group=None, use_prefix=True, precision=1)
Return a ready-to-print representation of a number.
Return a ready-to-print representation of the number val in a given base (radix) or the current base by default, using the current settings for number representation as set by the output-radix and digit-grouping commands.
The default digit grouping can be overridden with the group parameter, where 0 means no grouping. The radix prefix can be removed by specifying use_prefix as False.
The minimum number of digits to be printed is specified by precision. If precision is negative, the precision is taken to be zero. Regardless of the radix, a value of zero with zero precision will always return the empty string.
Negative numbers that fit in a signed 64-bit integer are treated as such. Other negative numbers are prefixed with a minus ("-").
class cli.obj_t(desc, kind=None, want_port=False, cls=None, iface=None)
Returns an argument which accepts any object.
desc is the string returned as a description of the argument. kind can be used to limit the accepted objects to only allow objects of a certain kind. This parameter can either be a class name that the object should be an instance of, or the name of an interface that the object must implement, or a tuple of kinds. want_port indicates whether it should be allowed to specify an object and a port name, separated with a colon. If a port is wanted, the argument will be a list [obj, port] instead of only the object.
cli.object_expander(kind)
A standard expander for an object argument.
For command writing: standard expander that can be use to provide argument completion on all objects of a given class or matching a given interface (kind).
For example, to expand a string with the list of processor available in the machine, you would write:
arg(str_t, "cpu", expander = object_expander("processor_info"))
To expand a string to all gcache objects:
arg(str_t, "cache", expander = object_expander("gcache"))
class cli.poly_t(desc, *types)
Generator function that generates arguments for given types.
Generates an argument with the given description that will match any of the given types; they will be tried one by one, in the order specified, and the first one that accepts the input will be used.
cli.quiet_run_command(text, output_mode=output_modes.formatted_text)
Runs a CLI command and return output.
Runs a CLI command, or a CLI expression, as if it has been entered at the prompt. Errors are reported using CliError exception.
The cli.quiet_run_command function is similar to cli.run_command but returns a tuple with the command return value as first entry, and the command output text as the second. Please note that sometimes unrelated output might be included, e.g., for commands that advance the virtual time or in some other way may allow other commands to run in parallel with them.
Set ‘output_mode’ to one of the output modes:
output_modes.regularoutput_modes.formatted_textoutput_modes.unformatted_textclass cli.range_t(min, max, desc, name=None, modulo=False, positive=False)
Returns an argument which accepts any integer x between min and max inclusively. desc is the string returned as a description of the argument.
Values outside the interval cause an error to be signalled if modulo is false, and a modulo-reduction to the specified interval otherwise.
cli.register_command_category(name=None)
Register a command category
Registers a command category for the ‘type’ argument given to the new_command function. Command categories are optional but may be useful if many commands are defined for a particular use case that is of general interest.
name should be at least 3 characters long and preferably just one capitalized word, a noun.
Do not register any command category for a class, as those are listed on the class itself.
Invoke this function without any argument to print the standard categories, assuming no modules or targets have been loaded.
cli.run_command(text)
Run a CLI command.
Runs a CLI command, or a CLI expression, as if it has been entered at the prompt. Errors are reported using CliError exception, and any return value from the command is returned by this function to Python.
Use cli.quiet_run_command if you need to suppress or catch messages printed.
cli.simenv
CLI variable namespace.
The simenv namespace provides access to the CLI variables in the Simics Python interpreter. If the variable $foo was defined in CLI, simenv.foo will represent the same variable in Python.
Running del simenv.foo will unset that variable. The return value from the dir function will also include defined variables. The repr function will return the dictionary of variable and value pairs as a string.
cli.sint16_t
Accepts any signed integer that fits in 16 bits, modulo-reducing values outside into that range.
cli.sint32_t
Accepts any signed integer that fits in 32 bits, modulo-reducing values outside into that range.
cli.sint64_t
Accepts any signed integer that fits in 64 bits, modulo-reducing values outside into that range.
cli.sint8_t
Accepts any signed integer that fits in 8 bits, modulo-reducing values outside into that range.
cli.str_number(text)
convert a string to a number.
Converts a string returned from cli.number_str back to an integer.
A number representing the string.
ValueError is raised for invalid arguments.
class cli.string_set_t(strings, visible=None)
Accepts only strings from the given set.
strings can be any iterable, such as a tuple, list, or set, in which case the return value is the exact string the user gave; or a dictionary mapping acceptable user input strings to return values. The optional parameter visible is a list of strings. If given, only strings in this list will be suggested by the expander.
cli.uint16_t
Accepts any unsigned integer that fits in 16 bits, modulo-reducing values outside into that range.
cli.uint32_t
Accepts any unsigned integer that fits in 32 bits, modulo-reducing values outside into that range.
cli.uint64_t
Accepts any unsigned integer that fits in 64 bits, modulo-reducing values outside into that range.
cli.uint8_t
Accepts any unsigned integer that fits in 8 bits, modulo-reducing values outside into that range.