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

-msve-vector-bits=<uint> Vector length to use. Must be a multiple of 128 bits up to 2048 bits.
-mlist-vector-lengths List all valid vector lengths.
-e, --eclient An emulation client based on the DynamoRIO API.

Note: If this is not specified, the default SVE client is used.
-i, --iclient An instrumentation client based on the DynamoRIO API.
-s, --show-drrun-cmd Writes the full DynamoRIO drrun command used to execute ArmIE to stderr.

This can be useful when debugging or developing clients.
--unsafe-ldstex Enables a workaround to avoid an exclusive load or store bug on certain AArch64 hardware. Refer to the known issues section in the release notes for further details.
-h, --help Show command help.
-V, --version Print the version.

Examples

  • 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

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

    armie -msve-vector-bits=256 -- ./sve_program
  • Dynamic instruction counts count instructions executed by a binary at run time. They are a useful way of measuring the performance of an application.

    An instruction count client, libsve_inscount.so, is supplied. To run the client with armie, use -i or --iclient option. For example:

    armie -msve-vector-bits=512 -i libsve_inscount.so -- ./sve_program             
    Client inscount is running
    117743 instructions executed of which 22 were SVE instructions 
  • Another useful performance measurement is the memory access behavior of an executable.

    A memory trace client (for all vector lengths), libmemtrace_sve_<vector length>.so is supplied to work with the DynamoRIO client, libmemtrace_simple.so. To trace memory accesses with armie, use the -e and -i options with these clients. For example:

    armie -e libmemtrace_sve_512.so -i libmemtrace_simple.so -- ./sve_program
    Data file /path/to/your/current/directory/memtrace.sve_program.<PID>.0000.log created

    Note: This will create two memory trace files in the current working directory: one for SVE and another for non-SVE AArch64.

Related information

Getting started with Arm Instruction Emulator