From a02d68decd089f72c7460f177527fe35cc54c3bb Mon Sep 17 00:00:00 2001 From: Anouk Van Laer 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.