This chapter describes an overview of the Simics commands that can be used in relation to instrumentation support.
When Simics has loaded a system configuration, providers normally already exist, as part of the device models. Which tools that are available depends on the Simics packages installed. To get an overview of the available instrumentation commands in Simics, use the command: help Instrumentation.
It is also possible to use the list-instrumentation-tools command to see the tools available.
Available tools must first be created with a new-<tool> command, for example new-instruction-histogram.
Once a tool has been created it will have a number of generic instrumentation commands associated with it, as well as tool specific commands. Tools typically supports the following generic commands:
By connecting an Instrumentation tool object to an Instrumentation provider object, information can be extracted from the running system. Connecting can be done either directly when the tool is created with the new-<tool> command, or done afterwards with the <tool>.add-instrumentation command.
The established connections between providers and tools can be listed with the list-instrumentation command.
Figure 10 shows a simple example of commands for creating two different instruction histograms and their output after running some instructions.
simics> new-instruction-histogram -connect-all view = size [board.mb.cpu0.core[0][0] info] VMP not engaged. Reason: instrumentation enabled. Created ihist0 (connected to 1 processor) simics> new-instruction-histogram -connect-all view = mnemonic Created ihist1 (connected to 1 processor) simics> list-instrumentation 1 ihist0 - connected to board.mb.cpu0.core[0][0]:0 view = "size" 2 ihist1 - connected to board.mb.cpu0.core[0][0]:1 view = "mnemonic" simics> c 10000 simics> ihist0.histogram ┌─────┬───────┬─────┬───────┬───────────┐ │Row #│ Size │Count│ Count%│Accumulated│ │ │(bytes)│ │ │ Count% │ ├─────┼───────┼─────┼───────┼───────────┤ │ 1│ 2│ 4480│ 44.80%│ 44.80%│ │ 2│ 1│ 1661│ 16.61%│ 61.41%│ │ 3│ 3│ 1596│ 15.96%│ 77.37%│ │ 4│ 5│ 1074│ 10.74%│ 88.11%│ │ 5│ 4│ 560│ 5.60%│ 93.71%│ │ 6│ 6│ 408│ 4.08%│ 97.79%│ │ 7│ 7│ 212│ 2.12%│ 99.91%│ │ 8│ 8│ 8│ 0.08%│ 99.99%│ │ 9│ 10│ 1│ 0.01%│ 100.00%│ ├─────┼───────┼─────┼───────┼───────────┤ │Sum │ │10000│100.00%│ │ └─────┴───────┴─────┴───────┴───────────┘ Average size of executed instruction: 2.702500 (21 bits) simics> ihist1.histogram max = 10 ┌─────────┬────────┬─────┬───────┬───────────┐ │ Row # │mnemonic│Count│ Count%│Accumulated│ │ │ │ │ │ Count% │ ├─────────┼────────┼─────┼───────┼───────────┤ │ 1│mov │ 3025│ 30.25%│ 30.25%│ │ 2│jmp │ 901│ 9.01%│ 39.26%│ │ 3│add │ 864│ 8.64%│ 47.90%│ │ 4│cmp │ 854│ 8.54%│ 56.44%│ │ 5│out │ 731│ 7.31%│ 63.75%│ │ 6│movsx │ 413│ 4.13%│ 67.88%│ │ 7│jne │ 386│ 3.86%│ 71.74%│ │ 8│inc │ 377│ 3.77%│ 75.51%│ │ 9│je │ 345│ 3.45%│ 78.96%│ │ 10│jae │ 267│ 2.67%│ 81.63%│ ├─────────┼────────┼─────┼───────┼───────────┤ │# 10/42 │ │ │ │ │ │Sum (all)│ │10000│100.00%│ │ │Sum shown│ │ 8163│ 81.63%│ │ └─────────┴────────┴─────┴───────┴───────────┘
The framework also supports creating named groups, which can be used in the above commands to, for example, disable a number of connections with a single command. Such groups can be created with the create-instrumentation-group command. The group name can then be used when the connection is established with the new-<tool> and <tool>.add-instrumentation commands.
Each established connection between a provider and tool gets a connection specific sub-object associated with the tool. When multiple tools are connected to a provider, by default, the provider will give instrumentation information to each tool in the order they where connected. That is, each new connection automatically comes last.
Some providers, however, supports re-arranging the order of how the tools are called. This can be useful if one tool makes any kind of change to the simulation that the other tools should see the effect of. For providers which support re-arranging the dispatch order, the instrumentation-order command can be used to see the order and the instrumentation-move command can be used to move a tool connection to an earlier or later stage.
The instrumentation setup is session specific, thus it will not be saved in checkpoints. To re-establish the instrumentation capabilities after loading a checkpoint, objects must be re-created and communication setup again using the same commands that was used before the checkpoint was saved. This can for example be done in a script executed after the checkpoint has been loaded.