Arm Instruction Emulator 18.0
=============================

This version of the Arm Instruction Emulator (ArmIE) allows users to emulate
SVE instructions on AArch64 hardware with added features for instrumenting
AArch64 and SVE instructions.

This is the first release which integrates ArmIE with the Open Source DynamoRIO
dynamic binary instrumentation platform (http://www.dynamorio.org/home.html).

The previous release of Arm Instruction Emulator was 1.2.1. The version
numbering scheme has changed with this release in order to remain consistent
with other Arm AArch64 HPC software tools.

Changes in this Release
=======================

Removed features:

The functionality enabled by the following command line options is not available
in this release. They may be added in future releases.

-d, --debug             Enabled assertion checks in the emulator.
-o, --output            Redirected all messages generated by armie to a file.
-p, --profile-period    Enabled the performance profiler.
-msve-memtrace          Enabled memory tracing.

New features:

- Arm Instruction Emulator 18.0 runs using DynamoRIO clients to provide SVE
  emulation and limited instrumentation for both emulated SVE instructions and
  native AArch64 instructions. Previous releases emulated SVE instructions with
  no coverage of native AArch64 instructions.

Bug fixes:

- None. This is the first release based on DynamoRIO.

Other changes:

- None.

System Requirements
===================

This suite is supported on the following Linux platforms:

- AArch64 Redhat 7.2 and 7.3
- AArch64 SuSE 12
- AArch64 Ubuntu 16.04

Installation Instructions
=========================

To install the emulator, you should untar the release package:

$ tar -xvzf ARM-Instruction-Emulator_18.0_AArch64_<OS>_<OS_Version>_aarch64.tar.gz

Where:
ARM-Instruction-Emulator_18.0_AArch64_<OS>_<OS_Version>_aarch64.tar.gz
is the name of the <OS> <OS_Version> package.

$ cd ARM-Instruction-Emulator_18.0_AArch64_<OS>_<OS_Version>_aarch64

Install the emulator as root user:

$ sudo ./arm-instruction-emulator-18.0_Generic-AArch64_<OS>-<OS_Version_aarch64-linux-rpm.sh

You must read the EULA, presented to you as part of the install process, before
accepting or rejecting the agreement.

All files including EULA.txt are unpacked to /opt/arm/arm-instruction-emulator-18.0_Generic-AArch64_<OS>-<OS_Version>_aarch64-linux
If, after installation, you decide not to agree to the terms of the EULA you
must not run the emulator and you should delete all the installed files as
described in 'Uninstalling' below.

Known Issues
============

Execution of multi-threaded applications may be unreliable in this release. For
example, programs built using OpenMPI and MPI may fail. Full multi-threading
support will be available in a later release.

There are DynamoRIO defects and issues logged at https://github.com/DynamoRIO/dynamorio/issues
which may result in instrumentation and emulation failures.

There is a known DynamoRIO issue which causes hangs on some AArch64 hardware:
https://github.com/DynamoRIO/dynamorio/issues/1698
ArmIE has a workaround for this using the --unsafe-ldstex option. This feature
is not enabled by default as it is not yet a reliable fix.

Code Advisor is not compatible with this version of the Arm Instruction Emulator.

Documentation
=============

Refer to the Arm Developer website for supporting information about Arm
Instruction Emulator:
https://developer.arm.com/products/software-development-tools/hpc/arm-instruction-emulator

Further help and tutorials for all of Arm’s HPC tools can be found online at:
https://developer.arm.com/products/software-development-tools/hpc/documentation

There is also a README.txt file in /opt/arm/arm-instruction-emulator-18.0_Generic-AArch64_<OS>-<OS_Version>_aarch64-linux.

If you require support please contact support-hpc-sw@arm.com

Uninstalling
============

Delete all files and directories in the /opt/arm/arm-instruction-emulator-18.0_Generic-AArch64_<OS>-<OS_Version>_aarch64-linux directory.