Simics Agent is a feature in Simics which can be used to move files and directories in and out of a simulation in a deterministic way, without any network connection or kernel modules. It also provides a deterministic way of executing commands on the target systems and knowing when they finish.
This feature consists of two parts. One part is present inside a Simics
simulation session (agent_manager and
agent_handler objects) and the other part is
the simics-agent application running on the target system.
The simics-agent application must be located on the target system
and the user is in charge of starting it. The application as well as the
target system must be running for its commands to execute. There is typically
just a single Simics Agent in a target system, but there may be more target
systems and agents.
The user has to create the agent_manager object with the start-agent-manager Simics command. The object will find running Simics Agents and keep track of them. There can be only one agent_manager in Simics session.
In order to control and issue commands to a Simics Agent, the user must run the <agent_manager>.connect-to-agent command, which returns a unique agent_handle for the Simics Agent. Several handles may be connected to one Simics Agent, which are executing commands concurrently.
All the commands that the agent_handle provides are asynchronous and queued in the handle until they have completed. Handles can be created and used in scripts, script-branches, or interactively on the Simics command-line. The two commands, <agent_handle>.run-until-job and <agent_handle>.wait-for-job, allow the user to wait until a particular or all queued commands have finished.
Exactly when a Simics Agent runs and executes a particular command is defined by the target system, neither Simics nor the user can control it.
A ready-to-use Simics Agent is installed on some virtual platform images.
Agents for some architectures are also available on CD (ISO) in the
[simics-base]/targets/common/images/ directory.
For other use cases, the agent source code comes with Simics Base
and can be copied onto and compiled for the target system, usually
without, or with only minor, adjustments. The source code is located
at [simics-base]/src/misc/simics-agent/.
A Simics Agent runs only when needed, otherwise it sleeps and regularly polls for requests. Agent responsiveness versus performance taxing is a trade-off that is controlled by the polling interval, but affects all users of that Simics Agent.
The examples assume that a target system is booted and a Simics Agent is running on it. All but the first example expects the simulation to be running.
Creating a Simics Agent Manager is done once per simulation session, both for interactive use and for scripts.
simics> start-agent-manager agent-manager 'agent_manager' is created and enabled.
The agent_manager was started above, but the user needs an agent_handle to issue commands to. The connect command below will return immediately, whether the simulation is running or not, and whether there is any known Simics Agents matching the requested identity or not. Since no name was given, the returned handle will have the default name.
It is recommended, but not required, to issue commands while the simulation is stopped, like in this example, for the sake of determinism and repeatability.
simics> agent_manager.connect-to-agent matic0 connected to simics_agent0 simics> matic0.upload -executable my_test /bin/ matic0:job 1 simics> matic0.run "/bin/my_test -out /var/my_test.log" matic0:job 2
Now two commands have been given, but since the simulation is stopped they will not execute yet. The first command will upload the application binary and make it executable (if it isn't already), while the second command will run it. The queued commands can be listed along with their sequence id's.
simics> matic0.list-jobs #1 upload my_test /bin/my_test, queued #2 run "/bin/my_test -out /var/my_test.log", queued
Note that the <agent_handle>.list-jobs command does not require the simulation to be running (nor even a Simics Agent to exist). Then, run the queued commands and wait for them to complete.
simics> matic0.run-until-job File my_test copied from host to target /bin/my_test ... [the output of the my_test command, if any] ... matic0:job 2 finished
The test application produced an output log file that should be downloaded
from the simulation to the host. When downloading files the user may want to
specify the -overwrite flag. Otherwise the file will not be
downloaded on following runs, as the file will persist on the host.
simics> matic0.download -overwrite /var/my_test.log matic0:job 3 simics> matic0.run-until-job File /var/my_test.log copied from target to host ./my_test.log matic0:job 3 finished
This example will perform the same tasks as the previous example, but in a script-branch. The handle will automatically run the queued commands one after another in strict order, and they will complete in due time. Technically, the script-branch will queue all commands up until a <agent_handle>.wait-for-job command and only then wait for them to finish.
script-branch "run my_test" {
local $matic = (agent_manager.connect-to-agent)
$matic.upload -executable from = my_test to = /bin/
$job = ($matic.run -capture "/bin/my_test -out /var/my_test.log")
$matic.download -overwrite /var/my_test.log
$matic.wait-for-job # wait until ALL jobs are done
echo ($matic.get-captured-output $job)
$matic.delete-handle
}
This example prints the output of the my_test application, but
requires a wait-for-job command, because without it the application
will not have run before the script-branch reaches the echo statement and then
deletes the handle.
It is good practice to delete any lingering objects in the end of a script branch. The output of the my_test command is captured and printed, but can alternatively be written to a file instead.
File my_test copied from host to target /bin/my_test File /var/my_test.log copied from target to host ./my_test.log ... [the output of the my_test command, if any] ...
Similar to the previous examples, a test log file will be copied from the target system to the host system. Here, the execution is controlled completely from the command-line in the target system shell.
~ # simics-agent --executable --download my_test --to /bin/ File my_test copied from host to target /bin/my_test The Simics target agent has quit. ~ # my_test -out /var/my_test.log ... ~ # simics-agent --overwrite --upload /var/my_test.log File /var/my_test.log copied from target to host ./my_test.log The Simics target agent has quit.
Give the --help argument to the simics-agent for more
information on the available commands and options.
For these target initiated commands to work, the Agent Manager must be started on the host, but no Simics Agents are required to be running in the target system. Different Simics Agents and using them will not conflict or interfere with each other.