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 28 :param dest: path of to the file on the connected device. 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 34 Transfer a file, or files matching a glob pattern, from the connected device 35 to the host machine. 36 37 :param source: path of to the file on the connected device. If ``dest`` is a 38 directory, may be a glob pattern. 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. 51 :param check_exit_code: If ``True`` the exit code (on connected device) 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. 71 72 .. note:: The above methods are directly wrapped by :class:`Target` methods, 73 however note that some of the defaults are different. 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 102 :param device: The name of the adb device. This is usually a unique hex 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 107 is not esblished within this period, :class:`HostError` 108 is raised. 109 110 111 .. class:: SshConnection(host, username, password=None, keyfile=None, port=None,\ 112 timeout=None, password_prompt=None) 113 114 A connectioned to a device on the network over SSH. 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. 123 124 :param keyfile: Path to the SSH private key to be used for the connection. 125 126 .. note:: ``keyfile`` and ``password`` can't be specified 127 at the same time. 128 129 :param port: TCP port on which SSH server is listening on the remote device. 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. 134 :param password_prompt: A string with the password prompt used by 135 ``sshpass``. Set this if your version of ``sshpass`` 136 uses something other than ``"[sudo] password"``. 137 138 139 .. class:: TelnetConnection(host, username, password=None, port=None,\ 140 timeout=None, password_prompt=None,\ 141 original_prompt=None) 142 143 A connection to a device on the network over Telenet. 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 156 :param port: TCP port on which SSH server is listening on the remote device. 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. 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 177 be cached in memory after it is first requested. 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. 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. 241
