instrumentation

Synopsis

instrumentation.make_tool_commands(
    simics_class,
    object_prefix,
    provider_requirements,
    tied_to_class=None,
    provider_names=('provider', 'providers'),
    cmd_type=None,
    make_new_cmd=True,
    make_add_instrumentation_cmd=True,
    make_remove_instrumentation_cmd=True,
    make_enable_cmd=True,
    make_disable_cmd=True,
    make_info_cmd=True,
    make_status_cmd=True,
    make_delete_cmd=True,
    fast_delete=False,
    make_filter_cmds=True,
    new_cmd_name=None,
    new_cmd_extra_args=([], None),
    new_cmd_can_connect=True,
    new_cmd_doc='',
    connect_extra_args=([], None, ''),
    connect_all_flag=True,
    info_cmd_extend_fn=None,
    status_cmd_extend_fn=None,
    unsupported=False
)

Description

Python function which creates commands for instrumentation tools

This factory function creates several useful commands for an instrumentation tool. Using this function will assert that all instrumentation tools works in an uniform manner. The following commands are created:

new-<tool>
<tool>.add-instrumentation
<tool>.remove-instrumentation
<tool>.enable-instrumentation
<tool>.disable-instrumentation
<tool>.info
<tool>.status
<tool>.delete
<tool>.add-filter
<tool>.remove-filter

The function should be called from the tool’s simics_start.py file (read at Simics start-up time, before the module is loaded). The new-<tool> will be created directly while the other commands will appear once the tool’s module has been loaded.

For the simplest case, only the simics_class, object_prefix and provider_requirements parameters needs to be specified. The rest of the parameters can be used to make tool specific adaptations for the commands created.

By default, all commands useful for an instrumentation tool are created. However, if certain commands should be omitted, the corresponding make_* parameters can be set to False.

new-<tool>: This command creates a Simics object for the given class. The command will be called new-<simics_class> where any underscores are replaced with hyphens. The object_prefix is used to create an automatic name for the object, by concatenating the prefix with a serial number. This automatic name can be overridden by supplying the name command argument.

The provider_requirements specifies what interface(s) the tool depends on from the provider in order to connect, two variants can be used.

A string with the interface requirement. For example, cpu_instrumentation_subscribe (when this interface is needed) or more complex such as cpu_instrumentation_subscribe & x86_instrumentation_subscribe when both interfaces must be available.
A Python function acting as a filter function, which takes an object as argument and returns True if it was accepted or False if it should not be connected.

By default, the new-<tool> command is created in the Simics global namespace. The optional tied_to_class creates the new-<tool> command in the class’s namespace, i.e. it will be invoked as <class>.new-<tool>.

The provider_names parameter should be a tuple of two strings, where the first part is the singular name of the provider and the second the plural. This can be used to give a more descriptive name for the provider objects, e.g., (‘processor’, ‘processors’) or (‘mouse’, ‘mice’). This is used in both the argument description and the commands associated help text. If the tool can only be connected to one object, None can be specified as the plural argument.

By default, the new-<tool> command uses simics_class as the command name. Other name can be used by setting the optional new_cmd_name.

If the tool needs additional arguments when created, for instance to be able to set required attributes, the new_cmd_extra_args parameter can be used. This parameter is a tuple with two elements; the first specifies additional CLI arguments added to the command and the second element specifies a function that will be called to create the object. The function takes the class of the tool, the name of the object, and then user added parameters corresponding to the CLI arguments. The function should return the created object. The following example illustrates how this can be done:

import instrumentation
def create_logger(tool_class, name, filename):
    return SIM_create_object(tool_class, name, log_file=filename)

instrumentation.make_tool_commands(
    'logger_tool', 'logger',
    new_cmd_extra_args = ([(filename_t(), 'log-file', '?', 'default.log')],
                          create_logger),
    new_cmd_doc = 'The log-file argument sets the log file to write to')

The optional cmd_type may specify a list of help categories for the created commands. If not specified, all commands will be added to the “Instrumentation” category.

By default, the new-<tool> command will get the same connection arguments as the <tool>.add-instrumentation command, see below. However, the new_cmd_can_connect can be set to False to remove the connection arguments. The new_cmd_doc can be set to improve and customize the help text for the command.

<tool>.add-instrumentation: This command connects the tool to one or several providers.

The connect_all_flag which is set to True by default adds a -connect-all command switch to the add-instrumentation command. This is a convenient way to connect to all compatible providers in the system.

When using add-instrumentation, each connection to a provider can be configured differently, allowing the tool to instrument different aspects of the system. Tools that supports this, should use the connect_extra_args parameter to add additional arguments to the command. This parameter is a tuple with three elements:

The additional CLI arguments as a list. A pre-connect function (called prior to connecting to the provider), which takes the parameters: (tool_object, provider_object, *additional_cli_args). The function should return a tuple with two elements; the argument list which will be passed to the tool’s connect() method, followed by a textual description of the arguments used, this string is used as a short description of the connection and will for instance be used by the list-instrumentation command. Any errors in the additional arguments can raise a cli.CliError exception, causing the connection to be discarded.
Additional documentation for the arguments added to the add-instrumentation command, found in the help text of the command.

The provider can be None if the tool is created without any connection(s). This allows the tool to signal an error if arguments are given which do not have any effect.

The following code is an example of how to use the connect_extra_args:

import instrumentation
def pre_connect(obj, provider, verbose_flag, reg_num):
    if provider == None and (verbose_flag or reg_num != None):
        raise cli.CliError("Connect arguments given without a provider")

    args = [["verbose", verbose_flag],
            ["reg_num", reg_num]]
    desc = 'Traces reg-%d %s' % (
        reg_num, '-verbose' if verbose_flag else '')
    return (args, desc)

instrumentation.make_tool_commands(
    'reg-trazer', 'traze',
    connect_extra_args = (
        [cli.arg(cli.flag_t, '-v'),
         cli.arg(cli.int_t, 'reg-num', "?", None)],
        pre_connect,
        '-v for verbose mode. The reg-num sets which register to trace.'))

The add-instrumentation command also gets a group argument that can be set to add the connection to an instrumentation group. See the add-instrumentation-group command for more information.

<tool>.remove-instrumentation: This command removes connections previously established.

<tool>.info and <tool>.status: These commands displays some simple generic instrumentation information. It is also possible to extend the output of the info/status commands by passing a Python function in the info_cmd_extend_fn and status_cmd_extend_fn parameters. These functions takes the tool objects as parameter and should return a list of the following format:

[(heading, [(tag, value), ...]), ...]

This gives the following output to the info/status command:

heading:
   tag1 : value1
   tag2 : value2
   ...
...

<tool>.disable-instrumentation and <tool>.enable-instrumentation: These commands allows the user to disable and enable the tools connections.

<tool>.add-filter and <tool>.remove-filter: These commands add or remove a filter associated with the tool. A filter can disable and enable the tools connection during execution.

The <tool>.delete command will remove the tool and the corresponding connections. By default, connections are teared down one by one by the disconnect() method in the instrumentation-tool interface. On large configurations with many objects, and connections this leads to performance problems iterating over SIM_delete_object() many times. The fast_delete switch can be set to true, to change the delete mechanism and only the tool itself is initially removed, and all the children (connections and aggregators) are automatically deleted as a side-effect. This requires that the connection objects are placed under the tool object itself, such as “tool0.conn0”.

instrumentation

Name

Synopsis

Python