-------------------------------
| Arm Instruction Emulator 20.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, untar the release package:

$ tar -xvzf ARM-Instruction-Emulator_20.1_AArch64_<OS>_<OS_Version>_aarch64.tar.gz

Where:

ARM-Instruction-Emulator_20.1_AArch64_<OS>_<OS_Version>_aarch64.tar.gz

is the name of the <OS> <OS_Version> package.

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

Install the emulator in /opt as root user:

$ sudo ./arm-instruction-emulator-20.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-20.1_Generic-AArch64_<OS>-<OS_Version>_aarch64-linux

If the -i, --install-to <directory> option is used, files are unpacked to

<directory>/arm-instruction-emulator-20.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 enabled by default and has now been deprecated. It will be removed in a
future release.

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

Refer to the Arm Developer website for supporting information about Arm
Instruction Emulator:
https://developer.arm.com/tools-and-software/server-and-hpc/compile/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/compile/arm-instruction-emulator/resources

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/help/help-and-tutorials

There is also a README.txt file in /opt/arm/arm-instruction-emulator-20.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-20.1_Generic-AArch64_<OS>-<OS_Version>_aarch64-linux/uninstall.sh script.

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

Changes in Release 20.1
=======================

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

New Features and Enhancements
-----------------------------
- Added support for the following v8.2 instructions based on detection of
  hardware capability at startup:
  fmov, scvtf, frecpe, fabs, fcmgtz, fcvtzs, frintn, frsqrte, frsqrts, fmax,
  fmaxp and fdiv, scvtf, ucvtf

Bug Fixes
---------
- Some SVE2 instructions that were not being emulated correctly have been
  fixed.

- CAS-164399-V9L7T0
  Output from the -s option now shows double-quoted client parameter strings
  correctly.

Other Changes
-------------
- The license that is included in ArmIE 20.1 is set to expire after 31st August
  2021.

Changes in Release 20.0
=======================

Removed Features
----------------
- The --unsafe-ldstex has been deprecated and is enabled by default. A new
  option, --safe-ldstex, has been added in the unlikely event that
  --unsafe-ldstex needs to be disabled.

New Features and Enhancements
-----------------------------
- Added command option --safe-ldstex, (see 'Removed Features' above).

- Added support for the emulated v8.2 instructions: frsqrte, frsqrts, fmax, fmaxp
  and fdiv. Optimization of emulated v8.2 instructions: fmax and fma.

- Adds support for the full diagnostic reporting of illegal instructions
  (SIGILL), in other words, displaying the illegal encoding and its subject
  binary PC address.

- Added armie command line option, --arg-iclient, to enable the passing of
  arguments to instrumentation clients.

- Consistency updates to Region-of-Interest (ROI) feature, originally extended
  from memory tracing instrumentation client to instruction counting, opcode
  counting, and instruction tracing clients.

- Added an example of using Region-of-Interest (ROI) macros in Fortran source
  code in the samples/fortran_roi directory.

- Updated GCC linker/loader support from GCC 8.2 to GCC 9.2.

Bug Fixes
---------
- Critical bug fix for OpenMPI applications.

- Improved installation compatibility with Arm Compiler for Linux and Arm
  Performance Libraries. This fixes a bug which required users to load the ArmIE
  environment module before loading the Arm Compiler for Linux and Arm
  Performance Libraries environment module.

Other Changes
-------------
- License is set to expire after 31st January 2021.

Changes in Release 19.2
=======================

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

New Features and Enhancements
-----------------------------
- Emulation of the following v8.2 and v8.3 instructions based on detection of
  hardware capability at startup:

  v8.2 half-precision instructions:
  fadd, fsub, fmul, fmul (by element), fmla, fmla (by element), fmadd, fmsub,
  fmls, fmls (by element), fneg, fcmp.

  v8.3: fcmla, fcadd

- Upgraded to be compatible with GCC 8.2 linker/loader, (from GCC 7.1).

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

Other Changes
-------------
- License set to expire after 31st August 2020.

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.