Connection¶
A Connection
abstracts an actual physical connection to a device. The
first connection is created when Target.connect()
method is called. If a
Target
is used in a multi-threaded environment, it will
maintain a connection for each thread in which it is invoked. This allows
the same target object to be used in parallel in multiple threads.
Connection
s will be automatically created and managed by
Target
s, so there is usually no reason to create one
manually. Instead, configuration for a Connection
is passed as
connection_settings parameter when creating a
Target
. The connection to be used target is also
specified on instantiation by conn_cls parameter, though all concrete
Target
implementations will set an appropriate
default, so there is typically no need to specify this explicitly.
Connection
classes are not a part of an inheritance hierarchy, i.e.
they do not derive from a common base. Instead, a Connection
is any
class that implements the following methods.
-
push
(self, source, dest, timeout=None)¶ Transfer a file from the host machine to the connected device.
Parameters: - source – path of to the file on the host
- dest – path of to the file on the connected device.
- timeout – timeout (in seconds) for the transfer; if the transfer does not complete within this period, an exception will be raised.
-
pull
(self, source, dest, timeout=None)¶ Transfer a file, or files matching a glob pattern, from the connected device to the host machine.
Parameters: - source – path of to the file on the connected device. If
dest
is a directory, may be a glob pattern. - dest – path of to the file on the host
- timeout – timeout (in seconds) for the transfer; if the transfer does not complete within this period, an exception will be raised.
- source – path of to the file on the connected device. If
-
execute
(self, command, timeout=None, check_exit_code=False, as_root=False, strip_colors=True, will_succeed=False)¶ Execute the specified command on the connected device and return its output.
Parameters: - command – The command to be executed.
- timeout – Timeout (in seconds) for the execution of the command. If specified, an exception will be raised if execution does not complete with the specified period.
- check_exit_code – If
True
the exit code (on connected device) from execution of the command will be checked, and an exception will be raised if it is not0
. - as_root – The command will be executed as root. This will fail on unrooted connected devices.
- strip_colours – The command output will have colour encodings and most ANSI escape sequences striped out before returning.
- will_succeed – The command is assumed to always succeed, unless there is
an issue in the environment like the loss of network connectivity. That
will make the method always raise an instance of a subclass of
DevlibTransientError' when the command fails, instead of a :class:`DevlibStableError
.
-
background
(self, command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, as_root=False)¶ Execute the command on the connected device, invoking it via subprocess on the host. This will return
subprocess.Popen
instance for the command.Parameters: - command – The command to be executed.
- stdout – By default, standard output will be piped from the subprocess; this may be used to redirect it to an alternative file handle.
- stderr – By default, standard error will be piped from the subprocess; this may be used to redirect it to an alternative file handle.
- as_root – The command will be executed as root. This will fail on unrooted connected devices.
Note
This will block the connection until the command completes.
Note
The above methods are directly wrapped by Target
methods,
however note that some of the defaults are different.
-
cancel_running_command
(self)¶ Cancel a running command (previously started with
background()
) and free up the connection. It is valid to call this if the command has already terminated (or if no command was issued), in which case this is a no-op.
-
close
(self)¶ Close the connection to the device. The
Connection
object should not be used after this method is called. There is no way to reopen a previously closed connection, a new connection object should be created instead.
Note
There is no open()
method, as the connection is assumed to be
opened on instantiation.
Connection Types¶
-
class
devlib.utils.android.
AdbConnection
(device=None, timeout=None, adb_server=None, adb_as_root=False)[source]¶ A connection to an android device via
adb
(Android Debug Bridge).adb
is part of the Android SDK (though stand-alone versions are also available).Parameters: - device – The name of the adb device. This is usually a unique hex
string for USB-connected devices, or an ip address/port
combination. To see connected devices, you can run
adb devices
on the host. - timeout – Connection timeout in seconds. If a connection to the device
is not established within this period,
HostError
is raised. - adb_server – Allows specifying the address of the adb server to use.
- adb_as_root – Specify whether the adb server should be restarted in root mode.
- device – The name of the adb device. This is usually a unique hex
string for USB-connected devices, or an ip address/port
combination. To see connected devices, you can run
-
class
devlib.utils.ssh.
SshConnection
(host, username, password=None, keyfile=None, port=None, timeout=None, password_prompt=None, sudo_cmd="sudo -- sh -c {}", options=None)[source]¶ A connection to a device on the network over SSH.
Parameters: - host – SSH host to which to connect
- username – username for SSH login
- password –
password for the SSH connection
Note
In order to user password-based authentication,
sshpass
utility must be installed on the system. - keyfile –
Path to the SSH private key to be used for the connection.
Note
keyfile
andpassword
can’t be specified at the same time. - port – TCP port on which SSH server is listening on the remote device. Omit to use the default port.
- timeout – Timeout for the connection in seconds. If a connection cannot be established within this time, an error will be raised.
- password_prompt – A string with the password prompt used by
sshpass
. Set this if your version ofsshpass
uses something other than"[sudo] password"
. - sudo_cmd – Specify the format of the command used to grant sudo access.
- options – A dictionary with extra ssh configuration options.
-
class
devlib.utils.ssh.
TelnetConnection
(host, username, password=None, port=None, timeout=None, password_prompt=None, original_prompt=None)[source]¶ A connection to a device on the network over Telenet.
Note
Since Telenet protocol is does not support file transfer, scp is used for that purpose.
Parameters: - host – SSH host to which to connect
- username – username for SSH login
- password –
password for the SSH connection
Note
In order to user password-based authentication,
sshpass
utility must be installed on the system. - port – TCP port on which SSH server is listening on the remote device. Omit to use the default port.
- timeout – Timeout for the connection in seconds. If a connection cannot be established within this time, an error will be raised.
- password_prompt – A string with the password prompt used by
sshpass
. Set this if your version ofsshpass
uses something other than"[sudo] password"
. - original_prompt – A regex for the shell prompted presented in the Telenet connection (the prompt will be reset to a randomly-generated pattern for the duration of the connection to reduce the possibility of clashes). This parameter is ignored for SSH connections.
-
class
devlib.host.
LocalConnection
(keep_password=True, unrooted=False, password=None)[source]¶ A connection to the local host allowing it to be treated as a Target.
Parameters: - keep_password – If this is
True
(the default) user’s password will be cached in memory after it is first requested. - unrooted – If set to
True
, the platform will be assumed to be unrooted without testing for root. This is useful to avoid blocking on password request in scripts. - password – Specify password on connection creation rather than prompting for it.
- keep_password – If this is
-
class
devlib.utils.ssh.
Gem5Connection
(platform, host=None, username=None, password=None, timeout=None, password_prompt=None, original_prompt=None)[source]¶ A connection to a gem5 simulation using a local Telnet connection.
Note
Some of the following input parameters are optional and will be ignored during initialisation. They were kept to keep the analogy with a
TelnetConnection
(i.e.host
, username`,password
,port
,password_prompt
andoriginal_promp
)Parameters: - host –
Host on which the gem5 simulation is running
Note
Even though the input parameter for the
host
will be ignored, the gem5 simulation needs to be on the same host the user is currently on, so if the host given as input parameter is not the same as the actual host, aTargetStableError
will be raised to prevent confusion. - username – Username in the simulated system
- password – No password required in gem5 so does not need to be set
- port – Telnet port to connect to gem5. This does not need to be set
at initialisation as this will either be determined by the
Gem5SimulationPlatform
or can be set using theconnect_gem5()
method - timeout – Timeout for the connection in seconds. Gem5 has high latencies so unless the timeout given by the user via this input parameter is higher than the default one (3600 seconds), this input parameter will be ignored.
- password_prompt – A string with password prompt
- original_prompt – A regex for the shell prompt
- host –
There are two classes that inherit from Gem5Connection
:
AndroidGem5Connection
and LinuxGem5Connection
.
They inherit almost all methods from the parent class, without altering them.
The only methods discussed below are those that will be overwritten by the
LinuxGem5Connection
and AndroidGem5Connection
respectively.