Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 1 | Connection |
| 2 | ========== |
| 3 | |
| 4 | A :class:`Connection` abstracts an actual physical connection to a device. The |
| 5 | first connection is created when :func:`Target.connect` method is called. If a |
| 6 | :class:`Target` is used in a multi-threaded environment, it will maintain a |
| 7 | connection for each thread in which it is invoked. This allows the same target |
| 8 | object to be used in parallel in multiple threads. |
| 9 | |
| 10 | :class:`Connection`\ s will be automatically created and managed by |
| 11 | :class:`Target`\ s, so there is usually no reason to create one manually. |
| 12 | Instead, configuration for a :class:`Connection` is passed as |
| 13 | `connection_settings` parameter when creating a :class:`Target`. The connection |
| 14 | to be used target is also specified on instantiation by `conn_cls` parameter, |
| 15 | though all concrete :class:`Target` implementations will set an appropriate |
| 16 | default, so there is typically no need to specify this explicitly. |
| 17 | |
| 18 | :class:`Connection` classes are not a part of an inheritance hierarchy, i.e. |
| 19 | they do not derive from a common base. Instead, a :class:`Connection` is any |
| 20 | class that implements the following methods. |
| 21 | |
| 22 | |
| 23 | .. method:: push(self, source, dest, timeout=None) |
| 24 | |
| 25 | Transfer a file from the host machine to the connected device. |
| 26 | |
| 27 | :param source: path of to the file on the host |
Brendan Jackman | adedad8 | 2017-01-27 19:31:44 +0000 | [diff] [blame] | 28 | :param dest: path of to the file on the connected device. |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 29 | :param timeout: timeout (in seconds) for the transfer; if the transfer does |
| 30 | not complete within this period, an exception will be raised. |
| 31 | |
| 32 | .. method:: pull(self, source, dest, timeout=None) |
| 33 | |
Brendan Jackman | 1cb4eb2 | 2017-01-27 19:32:11 +0000 | [diff] [blame] | 34 | Transfer a file, or files matching a glob pattern, from the connected device |
| 35 | to the host machine. |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 36 | |
Brendan Jackman | 1cb4eb2 | 2017-01-27 19:32:11 +0000 | [diff] [blame] | 37 | :param source: path of to the file on the connected device. If ``dest`` is a |
| 38 | directory, may be a glob pattern. |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 39 | :param dest: path of to the file on the host |
| 40 | :param timeout: timeout (in seconds) for the transfer; if the transfer does |
| 41 | not complete within this period, an exception will be raised. |
| 42 | |
| 43 | .. method:: execute(self, command, timeout=None, check_exit_code=False, as_root=False) |
| 44 | |
| 45 | Execute the specified command on the connected device and return its output. |
| 46 | |
| 47 | :param command: The command to be executed. |
| 48 | :param timeout: Timeout (in seconds) for the execution of the command. If |
| 49 | specified, an exception will be raised if execution does not complete |
| 50 | with the specified period. |
Anouk Van Laer | a02d68d | 2017-02-07 10:43:42 +0000 | [diff] [blame] | 51 | :param check_exit_code: If ``True`` the exit code (on connected device) |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 52 | from execution of the command will be checked, and an exception will be |
| 53 | raised if it is not ``0``. |
| 54 | :param as_root: The command will be executed as root. This will fail on |
| 55 | unrooted connected devices. |
| 56 | |
| 57 | .. method:: background(self, command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, as_root=False) |
| 58 | |
| 59 | Execute the command on the connected device, invoking it via subprocess on the host. |
| 60 | This will return :class:`subprocess.Popen` instance for the command. |
| 61 | |
| 62 | :param command: The command to be executed. |
| 63 | :param stdout: By default, standard output will be piped from the subprocess; |
| 64 | this may be used to redirect it to an alternative file handle. |
| 65 | :param stderr: By default, standard error will be piped from the subprocess; |
| 66 | this may be used to redirect it to an alternative file handle. |
| 67 | :param as_root: The command will be executed as root. This will fail on |
| 68 | unrooted connected devices. |
| 69 | |
| 70 | .. note:: This **will block the connection** until the command completes. |
Anouk Van Laer | a02d68d | 2017-02-07 10:43:42 +0000 | [diff] [blame] | 71 | |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 72 | .. note:: The above methods are directly wrapped by :class:`Target` methods, |
Anouk Van Laer | a02d68d | 2017-02-07 10:43:42 +0000 | [diff] [blame] | 73 | however note that some of the defaults are different. |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 74 | |
| 75 | .. method:: cancel_running_command(self) |
| 76 | |
| 77 | Cancel a running command (previously started with :func:`background`) and free up the connection. |
| 78 | It is valid to call this if the command has already terminated (or if no |
| 79 | command was issued), in which case this is a no-op. |
| 80 | |
| 81 | .. method:: close(self) |
| 82 | |
| 83 | Close the connection to the device. The :class:`Connection` object should not |
| 84 | be used after this method is called. There is no way to reopen a previously |
| 85 | closed connection, a new connection object should be created instead. |
| 86 | |
| 87 | .. note:: There is no :func:`open` method, as the connection is assumed to be |
| 88 | opened on instantiation. |
| 89 | |
| 90 | |
| 91 | .. _connection-types: |
| 92 | |
| 93 | Connection Types |
| 94 | ---------------- |
| 95 | |
| 96 | .. class:: AdbConnection(device=None, timeout=None) |
| 97 | |
| 98 | A connection to an android device via ``adb`` (Android Debug Bridge). |
| 99 | ``adb`` is part of the Android SDK (though stand-alone versions are also |
| 100 | available). |
| 101 | |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 102 | :param device: The name of the adb device. This is usually a unique hex |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 103 | string for USB-connected devices, or an ip address/port |
| 104 | combination. To see connected devices, you can run ``adb |
| 105 | devices`` on the host. |
| 106 | :param timeout: Connection timeout in seconds. If a connection to the device |
Anouk Van Laer | a02d68d | 2017-02-07 10:43:42 +0000 | [diff] [blame] | 107 | is not esblished within this period, :class:`HostError` |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 108 | is raised. |
| 109 | |
| 110 | |
| 111 | .. class:: SshConnection(host, username, password=None, keyfile=None, port=None,\ |
Sergei Trofimov | b3cea0c | 2016-12-08 11:48:41 +0000 | [diff] [blame] | 112 | timeout=None, password_prompt=None) |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 113 | |
Sergei Trofimov | b3cea0c | 2016-12-08 11:48:41 +0000 | [diff] [blame] | 114 | A connectioned to a device on the network over SSH. |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 115 | |
| 116 | :param host: SSH host to which to connect |
| 117 | :param username: username for SSH login |
| 118 | :param password: password for the SSH connection |
| 119 | |
| 120 | .. note:: In order to user password-based authentication, |
| 121 | ``sshpass`` utility must be installed on the |
| 122 | system. |
Anouk Van Laer | a02d68d | 2017-02-07 10:43:42 +0000 | [diff] [blame] | 123 | |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 124 | :param keyfile: Path to the SSH private key to be used for the connection. |
| 125 | |
Anouk Van Laer | a02d68d | 2017-02-07 10:43:42 +0000 | [diff] [blame] | 126 | .. note:: ``keyfile`` and ``password`` can't be specified |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 127 | at the same time. |
| 128 | |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 129 | :param port: TCP port on which SSH server is listening on the remote device. |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 130 | Omit to use the default port. |
| 131 | :param timeout: Timeout for the connection in seconds. If a connection |
| 132 | cannot be established within this time, an error will be |
| 133 | raised. |
Sergei Trofimov | b3cea0c | 2016-12-08 11:48:41 +0000 | [diff] [blame] | 134 | :param password_prompt: A string with the password prompt used by |
| 135 | ``sshpass``. Set this if your version of ``sshpass`` |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 136 | uses something other than ``"[sudo] password"``. |
Sergei Trofimov | b3cea0c | 2016-12-08 11:48:41 +0000 | [diff] [blame] | 137 | |
| 138 | |
| 139 | .. class:: TelnetConnection(host, username, password=None, port=None,\ |
| 140 | timeout=None, password_prompt=None,\ |
| 141 | original_prompt=None) |
| 142 | |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 143 | A connection to a device on the network over Telenet. |
Sergei Trofimov | b3cea0c | 2016-12-08 11:48:41 +0000 | [diff] [blame] | 144 | |
| 145 | .. note:: Since Telenet protocol is does not support file transfer, scp is |
| 146 | used for that purpose. |
| 147 | |
| 148 | :param host: SSH host to which to connect |
| 149 | :param username: username for SSH login |
| 150 | :param password: password for the SSH connection |
| 151 | |
| 152 | .. note:: In order to user password-based authentication, |
| 153 | ``sshpass`` utility must be installed on the |
| 154 | system. |
| 155 | |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 156 | :param port: TCP port on which SSH server is listening on the remote device. |
Sergei Trofimov | b3cea0c | 2016-12-08 11:48:41 +0000 | [diff] [blame] | 157 | Omit to use the default port. |
| 158 | :param timeout: Timeout for the connection in seconds. If a connection |
| 159 | cannot be established within this time, an error will be |
| 160 | raised. |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 161 | :param password_prompt: A string with the password prompt used by |
| 162 | ``sshpass``. Set this if your version of ``sshpass`` |
| 163 | uses somethin other than ``"[sudo] password"``. |
| 164 | :param original_prompt: A regex for the shell prompted presented in the Telenet |
| 165 | connection (the prompt will be reset to a |
| 166 | randomly-generated pattern for the duration of the |
| 167 | connection to reduce the possibility of clashes). |
| 168 | This paramer is ignored for SSH connections. |
| 169 | |
| 170 | |
| 171 | .. class:: LocalConnection(keep_password=True, unrooted=False, password=None) |
| 172 | |
| 173 | A connection to the local host allowing it to be treated as a Target. |
| 174 | |
| 175 | |
| 176 | :param keep_password: If this is ``True`` (the default) user's password will |
Anouk Van Laer | a02d68d | 2017-02-07 10:43:42 +0000 | [diff] [blame] | 177 | be cached in memory after it is first requested. |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 178 | :param unrooted: If set to ``True``, the platform will be assumed to be |
| 179 | unrooted without testing for root. This is useful to avoid |
| 180 | blocking on password request in scripts. |
| 181 | :param password: Specify password on connection creation rather than |
| 182 | prompting for it. |
Anouk Van Laer | a02d68d | 2017-02-07 10:43:42 +0000 | [diff] [blame] | 183 | |
| 184 | |
| 185 | .. class:: Gem5Connection(platform, host=None, username=None, password=None,\ |
| 186 | timeout=None, password_prompt=None,\ |
| 187 | original_prompt=None) |
| 188 | |
| 189 | A connection to a gem5 simulation using a local Telnet connection. |
| 190 | |
| 191 | .. note:: Some of the following input parameters are optional and will be ignored during |
| 192 | initialisation. They were kept to keep the anology with a :class:`TelnetConnection` |
| 193 | (i.e. ``host``, `username``, ``password``, ``port``, |
| 194 | ``password_prompt`` and ``original_promp``) |
| 195 | |
| 196 | |
| 197 | :param host: Host on which the gem5 simulation is running |
| 198 | |
| 199 | .. note:: Even thought the input parameter for the ``host`` |
| 200 | will be ignored, the gem5 simulation needs to on |
| 201 | the same host as the user as the user is |
| 202 | currently on, so if the host given as input |
| 203 | parameter is not the same as the actual host, a |
| 204 | ``TargetError`` will be raised to prevent |
| 205 | confusion. |
| 206 | |
| 207 | :param username: Username in the simulated system |
| 208 | :param password: No password required in gem5 so does not need to be set |
| 209 | :param port: Telnet port to connect to gem5. This does not need to be set |
| 210 | at initialisation as this will either be determined by the |
| 211 | :class:`Gem5SimulationPlatform` or can be set using the |
| 212 | :func:`connect_gem5` method |
| 213 | :param timeout: Timeout for the connection in seconds. Gem5 has high |
| 214 | latencies so unless the timeout given by the user via |
| 215 | this input parameter is higher than the default one |
| 216 | (3600 seconds), this input parameter will be ignored. |
| 217 | :param password_prompt: A string with password prompt |
| 218 | :param original_prompt: A regex for the shell prompt |
| 219 | |
| 220 | There are two classes that inherit from :class:`Gem5Connection`: |
| 221 | :class:`AndroidGem5Connection` and :class:`LinuxGem5Connection`. |
| 222 | They inherit *almost* all methods from the parent class, without altering them. |
| 223 | The only methods discussed belows are those that will be overwritten by the |
| 224 | :class:`LinuxGem5Connection` and :class:`AndroidGem5Connection` respectively. |
| 225 | |
| 226 | .. class:: LinuxGem5Connection |
| 227 | |
| 228 | A connection to a gem5 simulation that emulates a Linux system. |
| 229 | |
| 230 | .. method:: _login_to_device(self) |
| 231 | |
| 232 | Login to the gem5 simulated system. |
| 233 | |
| 234 | .. class:: AndroidGem5Connection |
| 235 | |
| 236 | A connection to a gem5 simulation that emulates an Android system. |
| 237 | |
| 238 | .. method:: _wait_for_boot(self) |
| 239 | |
| 240 | Wait for the gem5 simulated system to have booted and finished the booting animation. |