# ART VIXL Simulator Integration

This file documents the use of the ART 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:

    There are two environment variables that need to be set in order to build
    the simulator:
    - `ART_USE_RESTRICTED_MODE`: Setup ART in a restricted mode, disabling
                                 complex features, which allows the ART
                                 simulator to be gradually enabled.
    - `ART_USE_SIMULATOR`: Enables use of the simulator to run Arm64 tests on an
                           x86_64 host machine.

    Note that use of the ART simulator (via `ART_USE_SIMULATOR`) currently
    requires use of the restricted mode (via `ART_USE_RESTRICTED_MODE`).

    ```bash
    export ART_USE_RESTRICTED_MODE=true
    export ART_USE_SIMULATOR=true
    source build/envsetup.sh; lunch armv8-trunk_staging-eng
    ```

2. Build ART target and host:

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

3. Run Tests:

    To enable the simulator we use the `--simulator` flag with the ART test
    scripts.

    To run tests on the simulator, the regular testing scripts can be used:
    ```bash
    ./art/test.py --simulator --run-test --optimizing
    ```

## Debugging

### Simulator Tracing

#### Full Program Tracing

The simulator provides a tracing feature which is useful in debugging. Setting
runtime option `-verbose:simulator` will enable full instruction tracing and
register updates.

For example,
```bash
./art/test.py --simulator --optimizing --runtime-option=-verbose:simulator \
  -t 640-checker-simd
```

#### Partial Program Tracing

It is also possible to trace specific parts of the codegen by utilising the
macro-assembler to insert trace instructions into the codegen. This is
particulary useful when you only care about a specific piece of code, or if the
full program trace is too large.

The trace instruction takes a mask of `TraceParameters` (defined in
[external/vixl/src/aarch64/simulator-constants-aarch64.h]) which controls
exactly what the simulator will log. More details on the format of tracing can
be found in [external/vixl/doc/aarch64/topics/state-trace.md].

For example, the following code (from GenerateFrameEntry) will trace the
following instructions whenever they are simulated, showing instructions,
registers and branches.
```C++
__ Trace(LOG_ALL, TRACE_ENABLE);
__ Ldr(temp1, MemOperand(kArtMethodRegister,
                         ArtMethod::DeclaringClassOffset().Int32Value()));
__ Ldrb(temp2, HeapOperand(temp1, status_byte_offset));
__ Cmp(temp2, shifted_visibly_initialized_value);
__ Trace(LOG_ALL, TRACE_DISABLE);
```

Which produces this output when run:
```bash
./art/test.py --simulator --optimizing -t 001-HelloWorld

# Branch to 0x00000000604d9dec.
#             x0: 0x000000006021c568
#             x1: 0x0000000012c23298
#             x2: 0x0000000012c23298
#             x3: 0x0000000012c0f220
#             x4: 0x0000000012c0f000
#            x16: 0x00007ffff7511d60
#            x17: 0xfffffffffffc8288
#            x20: 0x0000000000000000
#            x21: 0x00005555555c7c50
#            x22: 0x0000000012c23298
#            x23: 0x0000000012c0f220
#            x24: 0x0000000000000001
#            x25: 0x0000000012c0da48
#            x26: 0x0000000000000000
#            x27: 0x0000000012c23328
#            x28: 0x00007ffff22d0d10
#            x29: 0x00007ffff22d0d04
#             lr: 0x00000000606081bc
#             sp: 0x00007ffff22d0c30
0x00000000604d9dec  b9400010        ldr w16, [x0]
#            w16:         0x60004be0 <- 0x000000006021c568
0x00000000604d9df0  3941ce11        ldrb w17, [x16, #115]
#            w17:         0x000000f0
#                                  ╙─ 0xf0 <- 0x0000000060004c53
0x00000000604d9df4  7103c23f        cmp w17, #0xf0 (240)
# NZCV: N:0 Z:1 C:1 V:0
0x00000000604d9df8  d45bd640        hlt #0xdeb2
Hello, world!
```

In addition, the [simulator debugger](#simulator-debugger) includes a `trace`
command to dynamically enable and disable tracing.

#### CFG Generation

Control flow graphs can also be generated as normal when simulating ART tests.
This can be particulary useful if developing a compiler optimization, that
affects e.g.: `527-checker-array-access-split`. When combined with other forms
of tracing this can help to view the code generated by dex2oat and the code
subsequently being run, by the simulator.
```bash
./art/test.py --simulator --optimizing --dump-cfg=oat.cfg --dex2oat-jobs 1 \
  -t 527-checker-array-access-split
```

### GDB

Another useful usecase of the simulator is debugging the runtime using the
`--gdb` flag. As both the simulator and runtime run on the host machine, this
allows a normal host debugger (e.g.: GDB) to be used to debug various aspects of
the runtime. Note that this is most useful when debugging the "native" (see the
comment for `enum StackType` in [thread.h]) part of the runtime.

```bash
./art/test.py --simulator --optimizing --gdb \
  -t 527-checker-array-access-split
```

Note: Implicit checks (e.g.: suspend checks) can interrupt GDB during simulation
requiring user input to proceed. To disable this stopping behaviour, run the
following in GDB:
```bash
(gdb) handle SIGSEGV nostop
```

### Simulator Debugger

The simulator includes a debugger which can be used to more easily step through
and inspect the simulated "quick" code (see the comment for `enum StackType` in
[thread.h]) generated by dex2oat.

The simulator debugger is disabled by default but can be enabled by setting
`kSimDebuggerEnabled` to `true` in [art/simulator/code_simulator_arm64.cc].
Once enabled the simulator debugger should be run alongside [GDB](#gdb) in
order to capture user input. In this way gdb can be used to debug the native
code until the simulator hits a breakpoint in the quick code which will enter
the simulator debugger.

For more information on how to use the simulator debugger refer to the VIXL
documentation at [external/vixl/doc/aarch64/topics/simulator-debugger.md].