ART VIXL Simulator Integration

This file documents the use of the VIXL Simulator for running tests on ART. The simulator enables us to run the ART run-tests without the need for a target device. This helps to speed up the development/debug/test cycle. The full AOSP source tree, as well as the partial master-art AOSP source tree, are supported.

Quick User Guide

  1. Set lunch target and setup environment:

    source build/envsetup.sh; lunch armv8-eng

  2. Build ART target and host:

    art/tools/buildbot-build.sh --target
art/tools/buildbot-build.sh --host

  3. Run Tests:

    To enable the simulator we use the --simulate-arm64 flag. The simulator can be used directly with the dalvikvm or the ART test scripts.

    To run a single test on simulator, use the command:

    art/test/run-test --host --simulate-arm64 --64 <TEST_NAME>

    To run all ART run-tests on simulator, use the art/test.py script with the following command:

    ./art/test.py --simulate-arm64 --run-test --optimizing

  4. Enable simulator tracing

    Simulator provides tracing feature which is useful in debugging. Setting runtime option -verbose:simulator will enable instruction trace and register updates. For example,

    ./art/test/run-test --host --runtime-option -verbose:simulator --optimizing \
  --never-clean --simulate-arm64 --64 640-checker-simd

  5. Debug

    Another useful usecase of the simulator is debugging using the --gdb flag.

    ./art/test/run-test --gdb --host --simulate-arm64 --64 527-checker-array-access-split

    If developing a compiler optimization which affects the test case 527-checker-array-access-split, you can use the simulator to run and generate the control flow graph with:

    ./art/test/run-test --host --dex2oat-jobs 1 -Xcompiler-option --dump-cfg=oat.cfg \
  --never-clean --simulate-arm64 --64 527-checker-array-access-split

  6. Control simulation

    By default, in simulator mode, all methods in art/test/ run-tests files are simulated. However, within art/simulator/code_simulator_arm64.cc, the CanSimulate() function provides options for developer to control simulation:

    • the kEnableSimulateMethodAllowList to restrict the methods run in the simulator;
    • the $simulate$ tag to force the simulator to run a method.

    Allow list to control simulation

    Sometimes we may wish to restrict the methods run in the simulator, this can be done using the simulate_method_white_list. Here a list of methods which we know to be safe to run in the simulator is kept in art/simulator/code_simulator_arm64.cc, the simulator can be forced to only run the methods on this list by setting

    kEnableSimulateMethodAllowList = true

    and recompile art and rerun the test cases. For example, if we set the white list to

    static const std::vector<std::string> simulate_method_white_list = {
  "other.TestByte.testDotProdComplex",
  "other.TestByte.testDotProdComplexSignedCastedToUnsigned",
  "other.TestByte.testDotProdComplexUnsigned",
  "other.TestByte.testDotProdComplexUnsignedCastedToSigned",
 };

    We only allow these methods to be run in simulator and all the other methods will run in the interpreter.

    The $simulate$ tag to control simulation

    In the case that we may wish to quickly change a Java method test case and force the simulator to run a method without recompiling art, add the $simulate$ tag in the method name. For example,

    public void $simulate$foo() {}