armie command reference

Note
The following content is relevant for Arm Instruction Emulator versions 18.2 and later. If you are using a previous version of Arm Instruction Emulator, please download the Arm Instruction Emulator v1.2.1 user guide instead.

The armie command runs a compiled binary using Arm Instruction Emulator. Arm Instruction Emulator is an emulator that can execute AArch64 and Scalable Vector Extension (SVE) instructions on Armv8-A hardware.

Usage

To execute and provide operational instructions to the Arm Instruction Emulator, use:

armie  [options] -- <command to execute>

Options

-m<string>
   -msve-vector-bits=<uint>
   -mlist-vector-lengths
Architecture specific options. Supported options:
  Vector length to use. Must be a multiple of 128 bits up to 2048 bits
  List all valid vector lengths
-e <client>, --eclient <client>

An emulation client based on the DynamoRIO API.

The libmemtrace_sve_<width>.so SVE emulation clients (in lib64/release) can be used in conjunction with the memory tracing instrumentation clients, where <width> is the vector width (in bits) between 128 and 2048 (in increments of 128).

Note: If this is not specified, the default SVE client is used.

-i <client>, --iclient <client>

An instrumentation client based on the DynamoRIO API.

The following instrumentation clients are provided with Arm Instruction Emulator (in samples/bin64):

  • libinscount_emulated.so
  • libinstrace_emulated.so
  • libmeminstrace_emulated.so
  • libmemtrace_emulated.so
  • libopcodes_emulated.so
  • libemulated_regs.so

To learn how to create your own custom instrumentation client, see
Building Custom Analysis Instrumentation and Building an Emulation-aware Instrumentation Client

-a, --arg-iclient <string> An optional <string> argument passed to the instrumentation client.
-x, --unsafe-ldstex DEPRECATED
Enables a workaround which avoids an exclusive load/store bug on certain AArch64 hardware.
This is always enabled and no longer needs to be set from the command line
(See 'Known Issues' in RELEASE_NOTES.txt for details).
-y, --safe-ldstex Use -y in the unlikely event that -x or --unsafe-ldstex needs to be disabled (see above).
(See 'Known Issues' in RELEASE_NOTES.txt for details)
-s, --show-drrun-cmd Write the full DynamoRIO drrun command used to execute ArmIE to stderr.

This can be useful when debugging or developing clients.
-h, --help Show command help.
-V, --version Print the version.

Example: Use '-mlist-vector-lengths' to list the valid vector lengths

To list all valid vector lengths:

armie -mlist-vector-lengths

Which returns:

128 256 384 512 640 768 896 1024 1152 1280 1408 1536 1664 1792 1920 2048

Example: Use '-msve-vector-bits' to specify the number of vector bits

To run the compiled binary 'sve_program' with 256-bit vectors:

armie -msve-vector-bits=256 -- ./sve_program

Related information