-------------------------------
| Arm Instruction Emulator 19.1 |
 -------------------------------

Arm Instruction Emulator (ArmIE) allows users to emulate SVE instructions on
AArch64 hardware. Based on the DynamoRIO dynamic binary instrumentation API,
ArmIE has added features for instrumenting AArch64 and SVE instructions. See
'RELEASE HISTORY' below for changes in this release.

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

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

$ cd ARM-Instruction-Emulator_19.1_AArch64_<OS>_<OS_Version>_aarch64

Install the emulator in /opt as root user:

$ sudo ./arm-instruction-emulator-19.1_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 the EULA file, license_agreement.txt, are unpacked to
/opt/arm/arm-instruction-emulator-19.1_Generic-AArch64_<OS>-<OS_Version>_aarch64-linux
If the -i, --install-to <directory> option is used, files are unpacked to
<directory>/opt/arm/arm-instruction-emulator-19.1_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
============

There are DynamoRIO defects and issues logged at https://github.com/DynamoRIO/dynamorio/issues
which may result in instrumentation and emulation failures. Note that thorough
testing and validation of this release has not resulted in any bugs related to
those issues.

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/tools-and-software/server-and-hpc/arm-architecture-tools/arm-instruction-emulator
This includes tutorials and other useful information for custom analysis of your
code:
https://developer.arm.com/tools-and-software/server-and-hpc/arm-architecture-tools/arm-instruction-emulator/tutorials

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

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

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

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

Run the /opt/arm/arm-instruction-emulator-19.1_Generic-AArch64_<OS>-<OS_Version>_aarch64-linux/uninstall.sh script.

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

Changes in Release 19.1
=======================

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

New Features and Enhancements
-----------------------------
- Addition of an uninstall.sh script

Bug Fixes
---------
- None.

Other Changes
-------------
- License extended to 31st March 2021.

Changes in Release 19.0
=======================

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

New Features and Enhancements
-----------------------------
- The regions-of-interest feature (ROI), has been added to the following
  instrumentation clients:
  api/samples/inscount_emulated.cpp
  api/samples/instrace_emulated.c
  api/samples/memtrace_emulated.c
  api/samples/opcodes_emulated.cpp

Bug Fixes
---------
- An ELF loader bug which resulted in failures when running Fortran binaries has
  been fixed.

Other Changes
-------------
- Documentation has been updated to include more information about analysing
  specific aspects of runtime performance using existing instrumentation
  clients, or developing your own. See:
  https://developer.arm.com/tools-and-software/server-and-hpc/arm-architecture-tools/arm-instruction-emulator
  https://developer.arm.com/tools-and-software/server-and-hpc/arm-architecture-tools/arm-instruction-emulator/tutorials
  https://developer.arm.com/tools-and-software/server-and-hpc/arm-architecture-tools/arm-instruction-emulator/structure-of-an-instrumentation-client
  https://developer.arm.com/tools-and-software/server-and-hpc/arm-architecture-tools/arm-instruction-emulator/building-custom-analysis-instrumentation
  https://developer.arm.com/tools-and-software/server-and-hpc/arm-architecture-tools/arm-instruction-emulator/building-an-emulation-aware-instrumentation-client

Change in Release 18.4
======================

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

New Features and Enhancements
-----------------------------
- None.

Bug Fixes
---------
- This version can successfully run multi-threaded subject binaries, including
  those linked with OpenMP libraries.

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

Changes in Release 18.3
=======================

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

New Features and Enhancements
-----------------------------
- Emulation has been separated from instrumentation based on the addition of an
  emulation interface to the DynamoRIO API allowing users to develop their own
  instrumentation clients:

  drmgr_is_emulation_start()
  drmgr_is_emulation_end()
  drmgr_get_emulation_instr_data()
  drmgr_create_emulation_start()
  drmgr_create_emulation_end()
  emulated_instr_t

  Two instruction count clients, an opcodes client and a memory trace client have
  been provided as examples. Another emulation feature to simplify iteration over
  blocks with emulated instructions is planned for a future release. If accepted
  upstream, this emulation-aware iterator will simplify instrumentation when
  running with emulation clients.

Bug Fixes
---------
- None

Other Changes
-------------
- A script, enc2instr.py, which can be used to disassemble instruction encodings
  to mnemonics. Useful for disassembling the output from
  drmgr_get_emulation_instr_data(). The script is based on llvm-mc and defaults
  to disassembling SVE, but can be any legal -mattr value supported by llvm-mc.
- All license files are now in the license_terms directory.

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
-------------
- A helper option to output the full drrun command used by armie:
 -s, --show-drrun-cmd.

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.