Sergei Trofimov | 1ba7fbd | 2016-12-09 15:06:35 +0000 | [diff] [blame] | 1 | .. _platform: |
| 2 | |
| 3 | Platform |
| 4 | ======== |
| 5 | |
| 6 | :class:`Platform`\ s describe the system underlying the OS. They encapsulate |
| 7 | hardware- and firmware-specific details. In most cases, the generic |
| 8 | :class:`Platform` class, which gets used if a platform is not explicitly |
| 9 | specified on :class:`Target` creation, will be sufficient. It will automatically |
| 10 | query as much platform information (such CPU topology, hardware model, etc) if |
| 11 | it was not specified explicitly by the user. |
| 12 | |
| 13 | |
| 14 | .. class:: Platform(name=None, core_names=None, core_clusters=None,\ |
| 15 | big_core=None, model=None, modules=None) |
| 16 | |
| 17 | :param name: A user-friendly identifier for the platform. |
| 18 | :param core_names: A list of CPU core names in the order they appear |
| 19 | registered with the OS. If they are not specified, |
| 20 | they will be queried at run time. |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 21 | :param core_clusters: A list with cluster ids of each core (starting with |
Sergei Trofimov | 1ba7fbd | 2016-12-09 15:06:35 +0000 | [diff] [blame] | 22 | 0). If this is not specified, clusters will be |
| 23 | inferred from core names (cores with the same name are |
| 24 | assumed to be in a cluster). |
| 25 | :param big_core: The name of the big core in a big.LITTLE system. If this is |
| 26 | not specified it will be inferred (on systems with exactly |
| 27 | two clasters). |
| 28 | :param model: Model name of the hardware system. If this is not specified it |
| 29 | will be queried at run time. |
| 30 | :param modules: Modules with additional functionality supported by the |
| 31 | platfrom (e.g. for handling flashing, rebooting, etc). These |
| 32 | would be added to the Target's modules. (See :ref:`modules`\ ). |
| 33 | |
| 34 | |
| 35 | Versatile Express |
| 36 | ----------------- |
| 37 | |
| 38 | The generic platform may be extended to support hardware- or |
| 39 | infrastructure-specific functionality. Platforms exist for ARM |
| 40 | VersatileExpress-based :class:`Juno` and :class:`TC2` development boards. In |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 41 | addition to the standard :class:`Platform` parameters above, these platforms |
Sergei Trofimov | 1ba7fbd | 2016-12-09 15:06:35 +0000 | [diff] [blame] | 42 | support additional configuration: |
| 43 | |
| 44 | |
| 45 | .. class:: VersatileExpressPlatform |
| 46 | |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 47 | Normally, this would be instantiated via one of its derived classes |
Sergei Trofimov | 1ba7fbd | 2016-12-09 15:06:35 +0000 | [diff] [blame] | 48 | (:class:`Juno` or :class:`TC2`) that set appropriate defaults for some of |
| 49 | the parameters. |
| 50 | |
| 51 | :param serial_port: Identifies the serial port (usual a /dev node) on which the |
| 52 | device is connected. |
| 53 | :param baudrate: Baud rate for the serial connection. This defaults to |
| 54 | ``115200`` for :class:`Juno` and ``38400`` for |
| 55 | :class:`TC2`. |
| 56 | :param vemsd_mount: Mount point for the VEMSD (Versatile Express MicroSD card |
| 57 | that is used for board configuration files and firmware |
| 58 | images). This defaults to ``"/media/JUNO"`` for |
| 59 | :class:`Juno` and ``"/media/VEMSD"`` for :class:`TC2`, |
| 60 | though you would most likely need to change this for |
| 61 | your setup as it would depend both on the file system |
| 62 | label on the MicroSD card, and on how the card was |
| 63 | mounted on the host system. |
| 64 | :param hard_reset_method: Specifies the method for hard-resetting the devices |
| 65 | (e.g. if it becomes unresponsive and normal reboot |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 66 | method doesn't not work). Currently supported methods |
Sergei Trofimov | 1ba7fbd | 2016-12-09 15:06:35 +0000 | [diff] [blame] | 67 | are: |
| 68 | |
| 69 | :dtr: reboot by toggling DTR line on the serial |
| 70 | connection (this is enabled via a DIP switch |
| 71 | on the board). |
| 72 | :reboottxt: reboot by writing a filed called |
| 73 | ``reboot.txt`` to the root of the VEMSD |
| 74 | mount (this is enabled via board |
| 75 | configuration file). |
| 76 | |
| 77 | This defaults to ``dtr`` for :class:`Juno` and |
| 78 | ``reboottxt`` for :class:`TC2`. |
| 79 | :param bootloader: Specifies the bootloader configuration used by the board. |
| 80 | The following values are currently supported: |
| 81 | |
| 82 | :uefi: Boot via UEFI menu, by selecting the entry |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 83 | specified by ``uefi_entry`` parameter. If this |
Sergei Trofimov | 1ba7fbd | 2016-12-09 15:06:35 +0000 | [diff] [blame] | 84 | entry does not exist, it will be automatically |
| 85 | created based on values provided for ``image``, |
| 86 | ``initrd``, ``fdt``, and ``bootargs`` parameters. |
| 87 | :uefi-shell: Boot by going via the UEFI shell. |
| 88 | :u-boot: Boot using Das U-Boot. |
| 89 | :bootmon: Boot directly via Versatile Express Bootmon |
| 90 | using the values provided for ``image``, |
| 91 | ``initrd``, ``fdt``, and ``bootargs`` |
| 92 | parameters. |
| 93 | |
| 94 | This defaults to ``u-boot`` for :class:`Juno` and |
| 95 | ``bootmon`` for :class:`TC2`. |
| 96 | :param flash_method: Specifies how the device is flashed. Currently, only |
| 97 | ``"vemsd"`` method is supported, which flashes by |
| 98 | writing firmware images to an appropriate location on |
| 99 | the VEMSD. |
| 100 | :param image: Specfies the kernel image name for ``uefi`` or ``bootmon`` boot. |
| 101 | :param fdt: Specifies the device tree blob for ``uefi`` or ``bootmon`` boot. |
| 102 | :param initrd: Specifies the ramdisk image for ``uefi`` or ``bootmon`` boot. |
| 103 | :param bootargs: Specifies the boot arguments that will be pass to the |
| 104 | kernel by the bootloader. |
| 105 | :param uefi_entry: Then name of the UEFI entry to be used/created by |
| 106 | ``uefi`` bootloader. |
| 107 | :param ready_timeout: Timeout, in seconds, for the time it takes the |
| 108 | platform to become ready to accept connections. Note: |
| 109 | this does not mean that the system is fully booted; |
| 110 | just that the services needed to establish a |
| 111 | connection (e.g. sshd or adbd) are up. |
| 112 | |
Anouk Van Laer | a02d68d | 2017-02-07 10:43:42 +0000 | [diff] [blame] | 113 | |
| 114 | .. _gem5-platform: |
| 115 | |
| 116 | Gem5 Simulation Platform |
| 117 | ------------------------ |
| 118 | |
| 119 | By initialising a Gem5SimulationPlatform, devlib will start a gem5 simulation (based upon the |
| 120 | arguments the user provided) and then connect to it using :class:`Gem5Connection`. |
| 121 | Using the methods discussed above, some methods of the :class:`Target` will be altered |
| 122 | slightly to better suit gem5. |
| 123 | |
| 124 | .. class:: Gem5SimulationPlatform(name, host_output_dir, gem5_bin, gem5_args, gem5_virtio, gem5_telnet_port=None) |
| 125 | |
| 126 | During initialisation the gem5 simulation will be kicked off (based upon the arguments |
| 127 | provided by the user) and the telnet port used by the gem5 simulation will be intercepted |
| 128 | and stored for use by the :class:`Gem5Connection`. |
| 129 | |
| 130 | :param name: Platform name |
| 131 | |
| 132 | :param host_output_dir: Path on the host where the gem5 outputs will be placed (e.g. stats file) |
| 133 | |
| 134 | :param gem5_bin: gem5 binary |
| 135 | |
| 136 | :param gem5_args: Arguments to be passed onto gem5 such as config file etc. |
| 137 | |
| 138 | :param gem5_virtio: Arguments to be passed onto gem5 in terms of the virtIO device used |
| 139 | to transfer files between the host and the gem5 simulated system. |
| 140 | |
| 141 | :param gem5_telnet_port: Not yet in use as it would be used in future implementations |
| 142 | of devlib in which the user could use the platform to pick |
| 143 | up an existing and running simulation. |
| 144 | |
| 145 | |
| 146 | .. method:: Gem5SimulationPlatform.init_target_connection([target]) |
| 147 | |
| 148 | Based upon the OS defined in the :class:`Target`, the type of :class:`Gem5Connection` |
| 149 | will be set (:class:`AndroidGem5Connection` or :class:`AndroidGem5Connection`). |
| 150 | |
| 151 | .. method:: Gem5SimulationPlatform.update_from_target([target]) |
| 152 | |
| 153 | This method provides specific setup procedures for a gem5 simulation. First of all, the m5 |
| 154 | binary will be installed on the guest (if it is not present). Secondly, three methods |
| 155 | in the :class:`Target` will be monkey-patched: |
| 156 | |
| 157 | - **reboot**: this is not supported in gem5 |
| 158 | - **reset**: this is not supported in gem5 |
| 159 | - **capture_screen**: gem5 might already have screencaps so the |
| 160 | monkey-patched method will first try to |
| 161 | transfer the existing screencaps. |
| 162 | In case that does not work, it will fall back |
| 163 | to the original :class:`Target` implementation |
| 164 | of :func:`capture_screen`. |
| 165 | |
| 166 | Finally, it will call the parent implementation of :func:`update_from_target`. |
| 167 | |
| 168 | .. method:: Gem5SimulationPlatform.setup([target]) |
| 169 | |
| 170 | The m5 binary be installed, if not yet installed on the gem5 simulated system. |
| 171 | It will also resize the gem5 shell, to avoid line wrapping issues. |