From a02d68decd089f72c7460f177527fe35cc54c3bb Mon Sep 17 00:00:00 2001
From: Anouk Van Laer <anouk.vanlaer@arm.com>
Date: Tue, 7 Feb 2017 10:43:42 +0000
Subject: [PATCH] gem5: Updated the documentation on the use of gem5 in devlib
modified: doc/connection.rst
modified: doc/index.rst
modified: doc/platform.rst
---
doc/connection.rst | 72 +++++++++++++++++++++++++++++++++++++++++-----
doc/index.rst | 1 +
doc/platform.rst | 59 +++++++++++++++++++++++++++++++++++++
3 files changed, 125 insertions(+), 7 deletions(-)
diff --git a/doc/connection.rst b/doc/connection.rst
index 1fd2fb5..1d8f098 100644
--- a/doc/connection.rst
+++ b/doc/connection.rst
@@ -48,7 +48,7 @@ class that implements the following methods.
:param 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.
- :param check_exit_code: If ``True`` the exit code (on connected device)
+ :param 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``.
:param as_root: The command will be executed as root. This will fail on
@@ -68,9 +68,9 @@ class that implements the following methods.
unrooted connected devices.
.. note:: This **will block the connection** until the command completes.
-
+
.. note:: The above methods are directly wrapped by :class:`Target` methods,
- however note that some of the defaults are different.
+ however note that some of the defaults are different.
.. method:: cancel_running_command(self)
@@ -104,7 +104,7 @@ Connection Types
combination. To see connected devices, you can run ``adb
devices`` on the host.
:param timeout: Connection timeout in seconds. If a connection to the device
- is not esblished within this period, :class:`HostError`
+ is not esblished within this period, :class:`HostError`
is raised.
@@ -120,10 +120,10 @@ Connection Types
.. note:: In order to user password-based authentication,
``sshpass`` utility must be installed on the
system.
-
+
:param keyfile: Path to the SSH private key to be used for the connection.
- .. note:: ``keyfile`` and ``password`` can't be specified
+ .. note:: ``keyfile`` and ``password`` can't be specified
at the same time.
:param port: TCP port on which SSH server is litening on the remoted device.
@@ -174,9 +174,67 @@ Connection Types
:param keep_password: If this is ``True`` (the default) user's password will
- be cached in memory after it is first requested.
+ be cached in memory after it is first requested.
:param 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.
:param password: Specify password on connection creation rather than
prompting for it.
+
+
+.. class:: Gem5Connection(platform, host=None, username=None, password=None,\
+ timeout=None, password_prompt=None,\
+ original_prompt=None)
+
+ 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 anology with a :class:`TelnetConnection`
+ (i.e. ``host``, `username``, ``password``, ``port``,
+ ``password_prompt`` and ``original_promp``)
+
+
+ :param host: Host on which the gem5 simulation is running
+
+ .. note:: Even thought the input parameter for the ``host``
+ will be ignored, the gem5 simulation needs to on
+ the same host as the user as the user is
+ currently on, so if the host given as input
+ parameter is not the same as the actual host, a
+ ``TargetError`` will be raised to prevent
+ confusion.
+
+ :param username: Username in the simulated system
+ :param password: No password required in gem5 so does not need to be set
+ :param port: Telnet port to connect to gem5. This does not need to be set
+ at initialisation as this will either be determined by the
+ :class:`Gem5SimulationPlatform` or can be set using the
+ :func:`connect_gem5` method
+ :param 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.
+ :param password_prompt: A string with password prompt
+ :param original_prompt: A regex for the shell prompt
+
+There are two classes that inherit from :class:`Gem5Connection`:
+:class:`AndroidGem5Connection` and :class:`LinuxGem5Connection`.
+They inherit *almost* all methods from the parent class, without altering them.
+The only methods discussed belows are those that will be overwritten by the
+:class:`LinuxGem5Connection` and :class:`AndroidGem5Connection` respectively.
+
+.. class:: LinuxGem5Connection
+
+ A connection to a gem5 simulation that emulates a Linux system.
+
+.. method:: _login_to_device(self)
+
+ Login to the gem5 simulated system.
+
+.. class:: AndroidGem5Connection
+
+ A connection to a gem5 simulation that emulates an Android system.
+
+.. method:: _wait_for_boot(self)
+
+ Wait for the gem5 simulated system to have booted and finished the booting animation.
diff --git a/doc/index.rst b/doc/index.rst
index 2c6d72f..7d99f7b 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -21,6 +21,7 @@ Contents:
instrumentation
platform
connection
+ platform
Indices and tables
==================
diff --git a/doc/platform.rst b/doc/platform.rst
index c3220a6..5270c09 100644
--- a/doc/platform.rst
+++ b/doc/platform.rst
@@ -110,3 +110,62 @@ support additional configuration:
just that the services needed to establish a
connection (e.g. sshd or adbd) are up.
+
+.. _gem5-platform:
+
+Gem5 Simulation Platform
+------------------------
+
+By initialising a Gem5SimulationPlatform, devlib will start a gem5 simulation (based upon the
+arguments the user provided) and then connect to it using :class:`Gem5Connection`.
+Using the methods discussed above, some methods of the :class:`Target` will be altered
+slightly to better suit gem5.
+
+.. class:: Gem5SimulationPlatform(name, host_output_dir, gem5_bin, gem5_args, gem5_virtio, gem5_telnet_port=None)
+
+ During initialisation the gem5 simulation will be kicked off (based upon the arguments
+ provided by the user) and the telnet port used by the gem5 simulation will be intercepted
+ and stored for use by the :class:`Gem5Connection`.
+
+ :param name: Platform name
+
+ :param host_output_dir: Path on the host where the gem5 outputs will be placed (e.g. stats file)
+
+ :param gem5_bin: gem5 binary
+
+ :param gem5_args: Arguments to be passed onto gem5 such as config file etc.
+
+ :param gem5_virtio: Arguments to be passed onto gem5 in terms of the virtIO device used
+ to transfer files between the host and the gem5 simulated system.
+
+ :param gem5_telnet_port: Not yet in use as it would be used in future implementations
+ of devlib in which the user could use the platform to pick
+ up an existing and running simulation.
+
+
+.. method:: Gem5SimulationPlatform.init_target_connection([target])
+
+ Based upon the OS defined in the :class:`Target`, the type of :class:`Gem5Connection`
+ will be set (:class:`AndroidGem5Connection` or :class:`AndroidGem5Connection`).
+
+.. method:: Gem5SimulationPlatform.update_from_target([target])
+
+ This method provides specific setup procedures for a gem5 simulation. First of all, the m5
+ binary will be installed on the guest (if it is not present). Secondly, three methods
+ in the :class:`Target` will be monkey-patched:
+
+ - **reboot**: this is not supported in gem5
+ - **reset**: this is not supported in gem5
+ - **capture_screen**: gem5 might already have screencaps so the
+ monkey-patched method will first try to
+ transfer the existing screencaps.
+ In case that does not work, it will fall back
+ to the original :class:`Target` implementation
+ of :func:`capture_screen`.
+
+ Finally, it will call the parent implementation of :func:`update_from_target`.
+
+.. method:: Gem5SimulationPlatform.setup([target])
+
+ The m5 binary be installed, if not yet installed on the gem5 simulated system.
+ It will also resize the gem5 shell, to avoid line wrapping issues.