-------------------------------
| Arm Instruction Emulator 18.2 |
 -------------------------------

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.

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

ArmIE 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.2_AArch64_<OS>_<OS_Version>_aarch64.tar.gz

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

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

Install the emulator in /opt as root user:

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

Or use the -i, --install-to <directory> option to install to a specified location.

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.2_Generic-AArch64_<OS>-<OS_Version>_aarch64-linux
unless the -i, --install-to <directory> option is used.

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.2_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.2_Generic-AArch64_<OS>-<OS_Version>_aarch64-linux directory.

 ----------------
| RELEASE HISTORY |
 ----------------

Changes in Release 18.2
=======================

Removed Features
----------------
- None.

New Features and Enhancements
-----------------------------
This release begins the process of separating emulation clients from
instrumentation clients. The implementation of an instruction count client and
memory tracing clients are the first examples of such a separation.

Bug Fixes
---------
- A bug in counting non-SVE instructions has been fixed.

Other Changes
-------------
- None.

Changes in Release 18.1
=======================

Removed Features
----------------
- None.

New Features and Enhancements
-----------------------------
- There are significant improvements in runtime performance principally due to
  optimisations in SVE emulation functions (mostly floating-point emulation
  including faster FCMLA) and memory copying.

Bug Fixes
---------
- Floating point corrections including:
  - Handling of inactive vector elements.
  - Floating point <-> integer conversions.
  - FPSR updates by and for modifying instructions.
  - Operand ordering for commutative operations.
  - Handling of NaNs.

Other Changes
-------------
- None.

Changes in Release 18.0
=======================

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.

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.