agent_handle

Description

The agent_handle class is used by Matic to resemble connections with Simics Agents, which are running on target systems. A handle provides the user with commands so that she can interact with the agent of the handle.

An agent handle can only be connected to one Simics Agent but an agent may be connected to several handles.

Matic requires the simulation to run, allowing Simics Agents on the target systems to run and respond. However, if the simulation is not running, any commands will be queued on the agent handle until they are run eventually.

The <agent_manager>.connect-to-agent command creates an agent handle that will be associated with an agent as soon as possible. Agent handles should be deleted when they no longer are needed.

The stale_timeout attribute controls the timeout period after the end of an agent poll interval until the Simics Agent is declared dead unless it has made contact. The setting applies individually to each Simics Agent, but control is shared among its handles. Once dead, all its handles will become stale and all their commands will be canceled. New commands cannot be given to a stale handle.

The handle also provides some other attributes: connected_to, magic, stale, state and windows. See the help text for each attribute for more information.

See also: Simics User's Guide as well as the agent_manager class.

Interfaces Implemented

conf_object, log_object

Notifiers

cell-change: Notifier that is triggered after the object's cell was changed.
object-delete: Notifier that is triggered just before Simics object is deleted.
queue-change: Notifier that is triggered after the object's clock was changed. New clock can be obtained with the SIM_object_clock function.

Commands for this class

agent-poll-interval – set the agent's polling interval
agent-quit – quit the agent for this handle
agent-restart – restart the Simics target agent
change-directory – change this handle's working directory
delete-handle – delete this agent handle
discard-jobs – discard jobs from this agent handle
download – download file from system to host
download-dir – download directory from target to host
get-captured-output – get or print the captured job output
info – print information about the object
list-files – list target directory contents
list-jobs – list commands posted on this handle
print-file – print file contents on Simics CLI
print-working-directory – print this handle's working directory
run – execute a command on the target system
run-until-job – run simulation until job completed
status – print status of the object
target-time – set or get target system date and time
upload – upload file from host to target
upload-dir – upload directory from host to target
wait-for-job – suspend script branch until job completed

Attributes

connected_to: Pseudo attribute; read-only access; type: s
The agent-id of the connected agent.
magic: Pseudo attribute; read-only access; type: i|n
The Simics Agent magic id number.
path: Pseudo attribute; read/write access; type: s
The private working directory on the target system.
stale: Pseudo attribute; read-only access; type: b
True, if the handle has become stale.
stale_timeout: Pseudo attribute; read/write access; type: i|f
Stale handle timeout, in seconds, started at the end of the poll interval. Requires an active connection.
state: Pseudo attribute; read-only access; type: s
The current state of the handle.
windows: Pseudo attribute; read/write access; type: b|n
True, if running on a Windows system.

Provided By

matic