8.7.2 Using the Intel Simics Agent

File transfer can be done in several ways. The preferred method is to use the Intel Simics Agent, which is piece of software that must be present on the target machine. The qsp-x86/firststeps target comes with the agent already on disk.

For other targets, if the agent is not present, it must be transferred to the target machine using one of the methods described later. The agent is preferred since it is the fastest and least intrusive method.

The steps required to configure the agent can be summarized as:

in the simulator:
Start the agent manager. The agent manager is a single global manager in the simulator, used to manage all connections to all agents on all targets. The agent manager is started with the
start-agent-manager command.
on the target:
Start the simics-agent on the target.
in the simulator:
Connect the agent manager with the agent with the <agent_manager>.connect-to-agent command. After connecting, an agent handle will be created, which is a Simics object which can be used access the target.

Here is an example of using the agent for transferring files, using the qsp-x86/firststeps target.

Follow the preparation steps to launch the simulator and reach prompt in the target machine.
Start the simulation and, from the target console, start simics-agent as a background process.
```
simics> run
running>
```
```
# simics-agent &
[1] 2638
grml, v1.5, Feb 21 2023 14:13:26 
```
Stop the simulation.
```
running> stop
simics>
```
Start the agent manager from the CLI. The manager object will get the default name of agent_manager.
```
simics> start-agent-manager
'agent_manager' is created and enabled.
```
Now we can connect the agent manager to the agent running on the target. A connection between the agent manager and a specific agent is represented by an agent handle. We specify the name agent0 for the agent handle.
```
simics> agent_manager.connect-to-agent name = agent0
```
Upload the file config.mk in the projects to /tmp in the target. The agent0.run-until-job provides a way to run until the upload finishes, and can be useful when scripting, even though not strictly necessary in this example.
```
simics> agent0.upload from = ./config.mk to = /tmp/
agent0:job 1 (upload config.mk)
simics> agent0.run-until-job 1
agent0:job 1 (upload config.mk) finished
```
Observe that the file is available in /tmp/config.mk in the target. This can be done by starting the simulator, and typing ls /tmp/config.mk in the target console, but we will instead use the
agent0.list-files command to list files under /tmp.
```
simics> agent0.list-files target-dir = /tmp
agent0:job 2 (ls /tmp)
simics> agent0.run-until-job 2
...
config.mk
agent0:job 2 (ls /tmp) finished
...
```

Similarly, we can use the agent handle to transfer a file from the target to the host.

simics> agent0.download -overwrite from = "/tmp/config.mk" to = /tmp
agent0:job 3 (download config.mk)
simics> agent0.run-until-job 3
agent0:job 3 (download config.mk) finished

Note that the agent operations are necessarily asynchronous, which is why we must wait for them to finish. However, there is no need to wait after each command; several commands can be queued up before a wait is issued.

In the example, we only started the simulation to allow starting simics-agent in the target machine, and while waiting for agent operations to complete, using <agent_handle>.run-until-job.

An alternative method is to keep the simulation running. With this method, the requested agent operations will start directly, and <agent_handle>.run-until-job or <agent_handle>.status may only be required to await or check completion of the operation. This method (work with a running simulator) can be convenient for interactive work.

The agent can also perform other operations, such as

Print target file contents (agent0.print-file)
Run arbitrary target (shell) commands (agent0.run)
Retrieve output of the commands (agent0.get-captured-output)

To see other available commands, run help agent0 or use the tab-completion by typing agent0. followed by two tabs:

agent0 # press tab twice to expand all commands
agent0.agent-poll-interval  agent0.log-group
agent0.agent-quit           agent0.log-level
agent0.agent-restart        agent0.ls
agent0.cd                   agent0.print-file
agent0.change-directory     agent0.print-working-directory
agent0.delete-handle        agent0.pwd
agent0.discard-jobs         agent0.run
agent0.download             agent0.run-until-job
agent0.download-dir         agent0.status
agent0.get-captured-output  agent0.target-time
agent0.info                 agent0.upload
agent0.list-files           agent0.upload-dir
agent0.list-jobs            agent0.wait-for-job

8.7.1 Preparation 8.7.3 Using disk images