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.

Connections will be automatically created and managed by Targets, 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, sources, dest, timeout=None)

Transfer a list of files from the host machine to the connected device.

Parameters:

  • sources – list of paths on the host

  • dest – path to the file or folder on the connected device.

  • timeout – timeout (in seconds) for the transfer of each file; if the transfer does not complete within this period, an exception will be raised.

pull(self, sources, dest, timeout=None)

Transfer a list of files from the connected device to the host machine.

Parameters:

  • sources – list of paths on the connected device.

  • dest – path to the file or folder on the host

  • timeout – timeout (in seconds) for the transfer for each file; if the transfer does not complete within this period, an exception will be raised.

execute(self, command, timeout=None, check_exit_code=True, 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 not 0.

  • 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 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.

forward_port(self, target_port, host_port=None):

Creates a TCP network port forward between target_port on the target device and host_port on the host machine. Returns the network port used on the host machine.

Parameters:

  • target_port – Network port to be used on the target device.

  • host_port – Network port to be used on the host machine. If not provided, A random free port will be used.

Connection Types

class devlib.utils.android.AdbConnection(device=None, timeout=None, adb_server=None, adb_as_root=False, connection_attempts=MAX_ATTEMPTS, poll_transfers=False, start_transfer_poll_delay=30, total_transfer_timeout=3600, transfer_poll_period=30)[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.

  • connection_attempts – Specify how many connection attempts, 10 seconds apart, should be attempted to connect to the device. Defaults to 5.

  • poll_transfers – Specify whether file transfers should be polled. Polling monitors the progress of file transfers and periodically checks whether they have stalled, attempting to cancel the transfers prematurely if so.

  • start_transfer_poll_delay – If transfers are polled, specify the length of time after a transfer has started before polling should start.

  • total_transfer_timeout – If transfers are polled, specify the total amount of time to elapse before the transfer is cancelled, regardless of its activity.

  • transfer_poll_period – If transfers are polled, specify the period at which the transfers are sampled for activity. Too small values may cause the destination size to appear the same over one or more sample periods, causing improper transfer cancellation.

class devlib.utils.ssh.SshConnection(host, username, password=None, keyfile=None, port=22, timeout=None, platform=None, sudo_cmd='sudo -- sh -c {}', strict_host_check=True, use_scp=False, poll_transfers=False, start_transfer_poll_delay=30, total_transfer_timeout=3600, transfer_poll_period=30)[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

    To connect to a system without a password this parameter should be set to an empty string otherwise ssh key authentication will be attempted.

    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 and password 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.

  • platform – Specify the platform to be used. The generic Platform class is used by default.

  • sudo_cmd – Specify the format of the command used to grant sudo access.

  • strict_host_check – Specify the ssh connection parameter StrictHostKeyChecking. If a path is passed rather than a boolean, it will be taken for a known_hosts file. Otherwise, the default $HOME/.ssh/known_hosts will be used.

  • use_scp – Use SCP for file transfers, defaults to SFTP.

  • poll_transfers – Specify whether file transfers should be polled. Polling monitors the progress of file transfers and periodically checks whether they have stalled, attempting to cancel the transfers prematurely if so.

  • start_transfer_poll_delay – If transfers are polled, specify the length of time after a transfer has started before polling should start.

  • total_transfer_timeout – If transfers are polled, specify the total amount of time to elapse before the transfer is cancelled, regardless of its activity.

  • transfer_poll_period – If transfers are polled, specify the period at which the transfers are sampled for activity. Too small values may cause the destination size to appear the same over one or more sample periods, causing improper transfer cancellation.

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 Telnet.

Note

Since Telnet 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 of sshpass uses something other than "[sudo] password".

  • original_prompt – A regex for the shell prompted presented in the Telnet 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.

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 and original_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, a TargetStableError 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 the connect_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

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.

class devlib.utils.ssh.LinuxGem5Connection[source]

A connection to a gem5 simulation that emulates a Linux system.

_login_to_device(self)[source]

Login to the gem5 simulated system.

class devlib.utils.ssh.AndroidGem5Connection[source]

A connection to a gem5 simulation that emulates an Android system.

_wait_for_boot(self)[source]

Wait for the gem5 simulated system to have booted and finished the booting animation.